xoutil.deprecation - Utils for marking deprecated elements

xoutil.deprecation.deprecated(replacement, msg=None, deprecated_module=None, removed_in_version=None, check_version=False)[source]

Small decorator for deprecated functions.

Usage:

@deprecated(new_function)
def deprecated_function(...):
    ...
Parameters:
  • replacement – Either a string or the object that replaces the deprecated.
  • msg

    A deprecation warning message template. You should provide keyword arguments for the format() function. Currently we pass the current keyword arguments: replacement (after some processing), funcname with the name of the currently deprecated object and in_version with the version this object is going to be removed if removed_in_version argument is not None.

    Defaults to: “{funcname} is now deprecated and it will be removed{in_version}. Use {replacement} instead.”

  • removed_in_version – The version the deprecated object is going to be removed.
  • check_version

    If True and removed_in_version is not None, then declarations of obseleted objects will raise a DeprecationError. This helps the release manager to keep the release clean.

    Note

    Currently only works with setuptools’ installed distributions.

  • deprecated_module – If provided, the name of the module the deprecated object resides. Not needed if the deprecated object is a function or class.
  • new_name – If provided, it’s used as the name of the deprecated object. Needed to allow renaming in import_deprecated() helper function.

Note

Deprecating some classes in Python 3 could fail. This is because those classes do not declare a ‘__new__’ par of the declared ‘__init__’. The problem is solved if the ‘__new__’ of the super-class has no arguments. This doesn’t happen in Python 2.

To solve these cases mark the deprecation in a comment and issue the warning directly in the constructor code.

Changed in version 1.4.1: Introduces removed_in_version and check_version.

xoutil.deprecation.import_deprecated(module, *names, **aliases)[source]

Import functions deprecating them in the target module.

The target module is the caller of this function (only intended to be called in the global part of a module).

Parameters:
  • module – The module from which functions will be imported. Could be a string, or an imported module.
  • names – The names of the functions to import.
  • aliases – Keys are the new names, values the old names.

For example:

>>> from xoutil.deprecation import import_deprecated
>>> import math
>>> import_deprecated(math, 'sin', new_cos='cos')
>>> sin is not math.sin
True

Next examples are all True, but them print the deprecation warning when executed:

>>> sin(math.pi/2) == 1.0
>>> new_cos(2*math.pi) == math.cos(2*math.pi)

If no identifier is given, it is assumed equivalent as from module import *.

The statement import_deprecated('math', 'sin', new_cos='cos') has the same semantics as from math import sin, cos as new_cos, but deprecating current module symbols.

This function is provided for easing the deprecation of whole modules and should not be used to do otherwise.

xoutil.deprecation.deprecate_module(replacement, msg=None)[source]

Deprecate an entire module.

This function must be called in the global context of the deprecated module.

Parameters:replacement – The name of replacement module.

For example:

>>> from xoutil.deprecation import deprecate_module
>>> deprecate_module('xoutil.symbols')
>>> del deprecate_module
xoutil.deprecation.deprecate_linked(check=None, msg=None)[source]

Deprecate an entire module if used through a link.

This function must be called in the global context of the new module.

Parameters:check – Must be a module name to check, it must be part of the actual module name. If not given ‘xoutil.future’ is assumed.

For example:

>>> from xoutil.deprecation import deprecate_linked
>>> deprecate_linked()
>>> del deprecate_linked