deprecations#

Tools to aid in deprecating code.

Classes#

DeprecationHandler

Attributes#

deprecated

exception DeprecatedError#

Bases: RuntimeError

Unspecified run-time error.

class DeprecationHandler(version: packaging.version.Version | str)#
_version: packaging.version.Version#
__call__(deprecate_in: str, remove_in: str, *, addendum: str | None = None, stack: int = 0) → Callable[[Callable], Callable]#

Deprecation decorator for functions, methods, & classes.

Parameters:

  • deprecate_in -- Version in which code will be marked as deprecated.

  • remove_in -- Version in which code is expected to be removed.

  • addendum -- Optional additional messaging. Useful to indicate what to do instead.

  • stack -- Optional stacklevel increment.

argument(deprecate_in: str, remove_in: str, argument: str, *, rename: str | None = None, addendum: str | None = None, stack: int = 0) → Callable[[Callable], Callable]#

Deprecation decorator for keyword arguments.

Parameters:

  • deprecate_in -- Version in which code will be marked as deprecated.

  • remove_in -- Version in which code is expected to be removed.

  • argument -- The argument to deprecate.

  • rename -- Optional new argument name.

  • addendum -- Optional additional messaging. Useful to indicate what to do instead.

  • stack -- Optional stacklevel increment.

action(deprecate_in: str, remove_in: str, action: type[argparse.Action], *, addendum: str | None = None, stack: int = 0)#
module(deprecate_in: str, remove_in: str, *, addendum: str | None = None, stack: int = 0) → None#

Deprecation function for modules.

Parameters:

  • deprecate_in -- Version in which code will be marked as deprecated.

  • remove_in -- Version in which code is expected to be removed.

  • addendum -- Optional additional messaging. Useful to indicate what to do instead.

  • stack -- Optional stacklevel increment.

constant(deprecate_in: str, remove_in: str, constant: str, value: Any, *, addendum: str | None = None, stack: int = 0) → None#

Deprecation function for module constant/global.

Parameters:

  • deprecate_in -- Version in which code will be marked as deprecated.

  • remove_in -- Version in which code is expected to be removed.

  • constant --

  • value --

  • addendum -- Optional additional messaging. Useful to indicate what to do instead.

  • stack -- Optional stacklevel increment.

topic(deprecate_in: str, remove_in: str, *, topic: str, addendum: str | None = None, stack: int = 0) → None#

Deprecation function for a topic.

Parameters:

  • deprecate_in -- Version in which code will be marked as deprecated.

  • remove_in -- Version in which code is expected to be removed.

  • topic -- The topic being deprecated.

  • addendum -- Optional additional messaging. Useful to indicate what to do instead.

  • stack -- Optional stacklevel increment.

_get_module(stack: int) → tuple[types.ModuleType, str]#

Detect the module from which we are being called.

Parameters:

stack -- The stacklevel increment.

Returns:

The module and module name.

_generate_message(deprecate_in: str, remove_in: str, prefix: str, addendum: str | None) → tuple[type[Warning] | None, str]#

Deprecation decorator for functions, methods, & classes.

Parameters:

  • deprecate_in -- Version in which code will be marked as deprecated.

  • remove_in -- Version in which code is expected to be removed.

  • prefix -- The message prefix, usually the function name.

  • addendum -- Additional messaging. Useful to indicate what to do instead.

Returns:

The warning category (if applicable) and the message.

deprecated#