xotl.tools.deprecation
- Utils for marking deprecated elements¶
-
xotl.tools.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.
-
xotl.tools.deprecation.
deprecated_alias
(f, **kwargs)[source]¶ Declare a deprecated alias.
This is roughly the same as
deprecated(f)(f)
; which is makes it convenient to give a better name to an already released function f, while keeping the old name as a deprecated alias.New in version 2.1.0.
-
xotl.tools.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 xotl.tools.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 asfrom 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.
-
xotl.tools.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 xotl.tools.deprecation import deprecate_module >>> deprecate_module('xotl.tools.symbols') >>> del deprecate_module
-
xotl.tools.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 ‘xotl.tools.future’ is assumed. For example:
>>> from xotl.tools.deprecation import deprecate_linked >>> deprecate_linked() >>> del deprecate_linked