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")  # noqa
def func_x():
    ...

# As alias
deprecated_alias = deprecated_callable(
    "Please use `real_callable` instead", date="2038-01-19"
)(real_callable)

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.