deprecations#

Tools to aid in deprecating code.

Classes#

DeprecationHandler

Attributes#

T

deprecated

T#
exception DeprecatedError#

Bases: RuntimeError

Unspecified run-time error.

class DeprecationHandler(version: str)#
_version: str | None#
_version_tuple: tuple[int, Ellipsis] | None#
_version_object: packaging.version.Version | None#
static _get_version_tuple(version: str) → tuple[int, Ellipsis] | None#

Return version as non-empty tuple of ints if possible, else None.

Parameters:

version -- Version string to parse.

_version_less_than(version: str) → bool#

Test whether own version is less than the given version.

Parameters:

version -- Version string to compare against.

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

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[P, T]], Callable[P, T]]#

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: ActionType, *, addendum: str | None = None, stack: int = 0) → ActionType#

Wraps any argparse.Action to issue a deprecation warning.

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, *, deprecation_type: type[Warning] = DeprecationWarning) → tuple[type[Warning] | None, str]#

Generate the standardized deprecation message and determine whether the deprecation is pending, active, or past.

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.

  • deprecation_type -- The warning type to use for active deprecations.

Returns:

The warning category (if applicable) and the message.

deprecated#