The currently documented publicly exposed API’s for usage in your project are defined below.
Warning
External usage of internal utility functions and modules should be kept to a minimum as they may be altered, refactored or moved to other locations without notice (and without the typical deprecation cycle).
debtcollector.
deprecate
(prefix, postfix=None, message=None, version=None, removal_version=None, stacklevel=3, category=<class 'DeprecationWarning'>)[source]¶Helper to deprecate some thing using generated message format.
prefix – prefix string used as the prefix of the output message
postfix – postfix string used as the postfix of the output message
message – message string used as ending contents of the deprecate message
version – version string (represents the version this deprecation was created in)
removal_version – version string (represents the version this deprecation will be removed in); a string of ‘?’ will denote this will be removed in some future unknown version
stacklevel – stacklevel used in the warnings.warn()
function
to locate where the users code is in the
warnings.warn()
call
category – the warnings
category to use, defaults to
DeprecationWarning
if not provided
debtcollector.moves.
moved_function
(new_func, old_func_name, old_module_name, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Deprecates a function that was moved to another location.
This generates a wrapper around new_func
that will emit a deprecation
warning when called. The warning message will include the new location
to obtain the function from.
debtcollector.moves.
moved_read_only_property
(old_name, new_name, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Bases: object
Descriptor for read-only properties moved to another location.
This works like the @property
descriptor but can be used instead to
provide the same functionality and also interact with the warnings
module to warn when a property is accessed, so that users of those
properties can know that a previously read-only property at a prior
location/name has moved to another location/name.
old_name – old attribute location/name
new_name – new attribute location/name
version – version string (represents the version this deprecation was created in)
removal_version – version string (represents the version this deprecation will be removed in); a string of ‘?’ will denote this will be removed in some future unknown version
stacklevel – stacklevel used in the warnings.warn()
function
to locate where the users code is when reporting the
deprecation call (the default being 3)
category – the warnings
category to use, defaults to
DeprecationWarning
if not provided
debtcollector.moves.
moved_method
(new_method_name, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Decorates an instance method that was moved to another location.
debtcollector.moves.
moved_property
(new_attribute_name, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Decorates an instance property that was moved to another location.
debtcollector.moves.
moved_class
(new_class, old_class_name, old_module_name, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Deprecates a class that was moved to another location.
This creates a ‘new-old’ type that can be used for a deprecation period that can be inherited from. This will emit warnings when the old locations class is initialized, telling where the new and improved location for the old class now is.
debtcollector.removals.
removed_property
(fget=None, fset=None, fdel=None, doc=None, stacklevel=3, category=<class 'DeprecationWarning'>, version=None, removal_version=None, message=None)[source]¶Bases: object
Property descriptor that deprecates a property.
This works like the @property
descriptor but can be used instead to
provide the same functionality and also interact with the warnings
module to warn when a property is accessed, set and/or deleted.
message – string used as ending contents of the deprecate message
version – version string (represents the version this deprecation was created in)
removal_version – version string (represents the version this deprecation will be removed in); a string of ‘?’ will denote this will be removed in some future unknown version
stacklevel – stacklevel used in the warnings.warn()
function
to locate where the users code is when reporting the
deprecation call (the default being 3)
category – the warnings
category to use, defaults to
DeprecationWarning
if not provided
debtcollector.removals.
remove
(f=None, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Decorates a function, method, or class to emit a deprecation warning
Due to limitations of the wrapt library (and python) itself, if this
is applied to subclasses of metaclasses then it likely will not work
as expected. More information can be found at bug #1520397 to see if
this situation affects your usage of this universal decorator, for
this specific scenario please use removed_class()
instead.
message (str) – A message to include in the deprecation warning
version (str) – Specify what version the removed function is present in
removal_version (str) – What version the function will be removed. If ‘?’ is used this implies an undefined future version
stacklevel (int) – How many entries deep in the call stack before ignoring
category (type) – warnings message category (this defaults to
DeprecationWarning
when none is provided)
debtcollector.removals.
removed_kwarg
(old_name, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Decorates a kwarg accepting function to deprecate a removed kwarg.
debtcollector.removals.
removed_class
(cls_name, replacement=None, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Decorates a class to denote that it will be removed at some point.
debtcollector.removals.
removed_module
(module, replacement=None, message=None, version=None, removal_version=None, stacklevel=3, category=None)[source]¶Helper to be called inside a module to emit a deprecation warning
replacment (str) – A location (or information about) of any potential replacement for the removed module (if applicable)
message (str) – A message to include in the deprecation warning
version (str) – Specify what version the removed module is present in
removal_version (str) – What version the module will be removed. If ‘?’ is used this implies an undefined future version
stacklevel (int) – How many entries deep in the call stack before ignoring
category (type) – warnings message category (this defaults to
DeprecationWarning
when none is provided)
debtcollector.fixtures.disable.
DisableFixture
[source]¶Bases: fixtures.fixture.Fixture
Fixture that disables debtcollector triggered warnings.
This does not disable warnings calls emitted by other libraries.
This can be used like:
from debtcollector.fixtures import disable
with disable.DisableFixture():
<some code that calls into depreciated code>
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.