deprecated¶

exception deprecated.BSKDeprecationWarning[source]¶: Bases: Warning

exception deprecated.BSKUrgentDeprecationWarning[source]¶: Bases: Warning

class deprecated.DeprecatedAttribute(removalDate: str, msg: str)[source]¶

Bases: object

Use this descriptor to deprecate class attributes (variables).

If you want to deprecate myAttribute in the following class:

class MyClass:

    def __init__(self) -> None:
        self.myAttribute = 0

You can use the following syntax:

class PythonTest:

    myAttribute = deprecated.DeprecatedAttribute("2099/05/05", "myAttribute is no longer used in the simulation")

    def __init__(self) -> None:
        with deprecated.ignore("myAttribute"): # Prevents warnings here
            self.myAttribute = 0

The attribute will work as before, but deprecation warnings will be raised everytime it’s used (read or set).

class deprecated.DeprecatedProperty(removalDate: str, msg: str, property: property)[source]¶

Bases: object

Use this descriptor to deprecate class properties.

If you want to deprecate myProperty in the following class:

class MyClass:

    @property
    def myProperty(self):
        return 0

    @myProperty.setter
    def myProperty(self, value: int):
        ...

You can use the following syntax:

class PythonTest:

    @property
    def myProperty(self):
        return 0

    @myProperty.setter
    def myProperty(self, value: int):
        ...

    myProperty = deprecated.DeprecatedProperty(
        "2099/05/05",
        "myProperty is no longer used in the simulation",
        myProperty)

The property will work as before, but deprecation warnings will be raised everytime it’s used (read or set).

deprecated.deprecated(removalDate: str, msg: str)[source]¶

A decorator for functions or classes that are deprecated.

Usage:

@deprecated.deprecated("2024/05/28", "Use MyNewClass")
class MyClass:
    ...

or:

@deprecated.deprecated("2024/05/28", "myFun is unsafe now")
def myFun(a, b):
    ...

or:

class ValidClass:

    @deprecated.deprecated("2024/05/28", "myMethod is slow, use myBetterMethod")
    def myMethod(self, a, b):
        ...

Parameters

removalDate (Union[datetime.date, str]) – The date when we expect to remove this deprecated feature, in the format ‘YYYY/MM/DD’ or as a datetime.date. Think of an amount of time that would let users update their code, and then add that duration to today’s date to find a reasonable removal date.
msg (str, optional) – a text that is directly shown to the users. Here, you may explain why the function is deprecated, alternative functions, links to documentation or scenarios that show how to translate deprecated code…

deprecated.deprecationWarn(id: str, removalDate: Union[datetime.date, str], msg: str)[source]¶

Utility function to raise deprecation warnings inside a function body.

This function should rarely be used on its own. For deprecated Python code, prefer the @deprecated decorator. For deprecated C++ code, use the SWIG macros in swig_deprecated.i.

Parameters

id (str) – An identifier for the deprecated feature (function/variable qualified name)
removalDate (Union[datetime.date, str]) – The date when we expect to remove this deprecated feature, in the format ‘YYYY/MM/DD’ or as a datetime.date. Think of an amount of time that would let users update their code, and then add that duration to today’s date to find a reasonable removal date.
msg (str, optional) – a text that is directly shown to the users. Here, you may explain why the function is deprecated, alternative functions, links to documentation or scenarios that show how to translate deprecated code…

deprecated.filterwarnings(action: Literal['error', 'ignore', 'always', 'default', 'module', 'once'], identifier: str, **kwargs: Any)[source]¶

Use this function to create global deprecation warning filters.

The most common use of this function is suppressing warnings for deprecated systems that you still intend to use. Imagine you want to ignore deprecation warnings for the method myMethod in class ValidClass in module my_module. You would add the following line to your simulation script:

deprecated.filterwarnings("ignore", "my_module.ValidClass.myMethod")

Note that deprecation warnings should not be ignored blindly. Deprecated code WILL be removed in future releases, so use warning suppression carefully.

Parameters

action (Literal["error", "ignore", "always", "default", "module", "once"]) – Controls how the filtered warnings will behave.
identifier (str) – The warning message must contain this string. This can be the function or variable identifier (qualified name) in order to hide deprecation warnings for specific features.
**kwargs (Any) – Any other keyword arguments are passed directly to warnings.filterwarnings.

deprecated.formatwarning(message, category, filename, lineno, line=None, __defaultformatwarning=<function formatwarning>)[source]¶: Hook to write a warning to a file; replace if you like.

class deprecated.ignore(identifier: str)[source]¶

Bases: object

Use this context manager to ignore warnings in a precise section of code.

The most common use of this function is suppressing warnings for specific calls. Imagine you want to ignore deprecation warnings for the method myMethod in class ValidClass in module my_module for a single call to this function. You would do:

myClass = my_module.ValidClass()

with deprecated.ignore("my_module.ValidClass.myMethod"):
    myClass.myMethod() # Does not raise a warning

myClass.myMethod() # Raises a warning

Note that deprecation warnings should not be ignored blindly. Deprecated code WILL be removed in future releases, so use warning suppression carefully.