Part of twisted.python View Source
To mark a method or function as being deprecated do this:
from twisted.python.versions import Version from twisted.python.deprecate import deprecated @deprecated(Version("Twisted", 8, 0, 0)) def badAPI(self, first, second): ''' Docstring for badAPI. ''' ...
The newly-decorated badAPI will issue a warning when called. It will also have a deprecation notice appended to its docstring.
To mark module-level attributes as being deprecated you can use:
badAttribute = "someValue" ... deprecatedModuleAttribute( Version("Twisted", 8, 0, 0), "Use goodAttribute instead.", "your.full.module.name", "badAttribute")
The deprecated attributes will issue a warning whenever they are
accessed. If the attributes being deprecated are in the same module as the
deprecatedModuleAttribute
call is being made from, the __name__
global can be used as
the moduleName
parameter.
See also Version
.
Variable | DEPRECATION_WARNING_FORMAT | The default deprecation warning string format to use when one is not
provided by the user. (type: str ) |
Function | getDeprecationWarningString | Return a string indicating that the callable was deprecated in the given version. |
Function | deprecated | Return a decorator that marks callables as deprecated. |
Function | getWarningMethod | Return the warning method currently used to record deprecation warnings. |
Function | setWarningMethod | Set the warning method to use to record deprecation warnings. |
Function | deprecatedModuleAttribute | Declare a module-level attribute as being deprecated. |
Function | warnAboutFunction | Issue a warning string, identifying offender as the
responsible code. |
Function | _getReplacementString | Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative. |
Function | _getDeprecationDocstring | Generate an addition to a deprecated object's docstring that explains its deprecation. |
Function | _getDeprecationWarningString | Return a string indicating that the Python name was deprecated in the given version. |
Function | _appendToDocstring | Append the given text to the docstring of thingWithDoc . |
Class | _InternalState | An _InternalState
is a helper object for a _ModuleProxy ,
so that it can easily access its own attributes, bypassing its logic for
delegating to another object that it's proxying for. |
Class | _ModuleProxy | Python module wrapper to hook module-level attribute access. |
Class | _DeprecatedAttribute | Wrapper for deprecated attributes. |
Function | _deprecateAttribute | Mark a module-level attribute as being deprecated. |
str
)
Returns | a string like "please use twisted.python.modules.getModule instead". |
Parameters | version | the version it was deprecated. (type: Version ) |
replacement | The replacement, if specified. (type: str or callable) | |
Returns | a string like "Deprecated in Twisted 27.2.0; please use twisted.timestream.tachyon.flux instead." |
Parameters | fqpn | Fully qualified Python name of the thing being deprecated (type: str ) |
version | Version that fqpn was deprecated in. (type: twisted.python.versions.Version ) | |
format | A user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT
if None is given. (type: str ) | |
replacement | what should be used in place of fqpn . Either pass in a string,
which will be inserted into the warning message, or a callable, which will
be expanded to its full import path. (type: str or callable) | |
Returns | A textual description of the deprecation (type: str ) |
Parameters | callableThing | Callable object to be deprecated (type: callable ) |
version | Version that callableThing was deprecated in (type: twisted.python.versions.Version ) | |
format | A user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT
if None is given (type: str ) | |
callableThing | A callable to be deprecated. (type: callable ) | |
version | The twisted.python.versions.Version
that the callable was deprecated in. (type: twisted.python.versions.Version ) | |
replacement | what should be used in place of the callable. Either pass in a string,
which will be inserted into the warning message, or a callable, which will
be expanded to its full import path. (type: str or callable) | |
Returns | A string describing the deprecation. (type: str ) |
thingWithDoc
.
If thingWithDoc
has no docstring, then the text just
replaces the docstring. If it has a single-line docstring then it appends a
blank line and the message text. If it has a multi-line docstring, then in
appends a blank line a the message text, and also does the indentation
correctly.
Parameters | version | The version in which the callable will be marked as having been deprecated.
The decorated function will be annotated with this version, having it set
as its deprecatedVersion attribute. (type: twisted.python.versions.Version ) |
version | the version that the callable was deprecated in. (type: twisted.python.versions.Version ) | |
replacement | what should be used in place of the callable. Either pass in a string,
which will be inserted into the warning message, or a callable, which will
be expanded to its full import path. (type: str or callable) |
The callable should take message, category and stacklevel. The return value is ignored.
Parameters | proxy | The module proxy instance proxying the deprecated attributes (type: _ModuleProxy ) |
name | Attribute name (type: str ) | |
version | Version that the attribute was deprecated in (type: twisted.python.versions.Version ) | |
message | Deprecation message (type: str ) |
Parameters | version | Version that the attribute was deprecated in (type: twisted.python.versions.Version ) |
message | Deprecation message (type: str ) | |
moduleName | Fully-qualified Python name of the module containing the deprecated
attribute; if called from the same module as the attributes are being
deprecated in, using the __name__ global can be helpful (type: str ) | |
name | Attribute name to deprecate (type: str ) |
offender
as the
responsible code.
This function is used to deprecate some behavior of a function. It
differs from warnings.warn
in that it is not limited to deprecating the behavior of a function
currently on the call stack.
Parameters | function | The function that is being deprecated. |
warningString | The string that should be emitted by this warning. (type: str ) | |
Present Since | 11.0 |