pydrake.common.deprecation

Provides deprecation warnings and utilities for triggering warnings.

By default, this sets all DrakeDeprecationWarnings to be shown “once”, which overrides any -W command-line arguments. To change this behavior, you can do something like:

>>> import warnings
>>> from pydrake.common.deprecation import DrakeDeprecationWarning
>>> warnings.simplefilter("always", DrakeDeprecationWarning)

If you would like to disable all Drake-related warnings, you may use the “ignore” action for warnings.simplefilter.

pydrake.common.deprecation.deprecated(message, *, date=None)

Decorator that deprecates a member of a class based on access.

Parameters:
  • message – Warning message when member is accessed.
  • date – (Optional) String of the form “YYYY-MM-DD”. If supplied, will reformat the message to add the date as is done with DRAKE_DEPRECATED and its processing in mkdoc.py. This must be present if message does not contain the date itself.

Note

This differs from other implementations in that it warns on access, not when the method is called. For other methods, see the examples in https://stackoverflow.com/a/40301488/7829525.

Use ModuleShim for deprecating variables in a module.

pydrake.common.deprecation.deprecated_callable(message, *, date=None)

Deprecates a callable (a free function or a type/class object) by wrapping its invocation to emit a deprecation.

When possible, use ModuleShim to ensure that a deprecation warning is emitted at import time, as it can easily be used with pure Python modules.

However, if you are dealing with a C++ module (and are writing code inside of _{module}_extra.py), you should use this approach.

Example as decorator:

@deprecated_callable(“Please use func_y instead”, date=”2038-01-19”) def func_x():

Example for alias:

my_alias = deprecated_callable(
“Please use my_original instead”, date=”2038-01-19”

)(my_original)

exception pydrake.common.deprecation.DrakeDeprecationWarning

Bases: DeprecationWarning

Extends DeprecationWarning to permit Drake-specific warnings to be filtered by default, without having side effects on other libraries.

pydrake.common.deprecation.install_numpy_warning_filters(force=False)

Install warnings filters specific to NumPy.

class pydrake.common.deprecation.ModuleShim(orig_module, handler)

Bases: object

Provides a shim for automatically resolving extra variables.

This can be used to deprecate import alias in modules to simplify dependencies.

Note

This is not necessary in Python >= 3.7 due to PEP 562.

Warning

This will not work if called on a cc module during import (e.g. using ExecuteExtraPythonCode). Instead, you should rename the module from {name} to _{name}, and import the symbols into the new module using _import_cc_module_vars.

__init__(orig_module, handler)