twisted.python.deprecate
module documentationtwisted.python
View Source
Deprecation framework for Twisted.
To mark a method, function, or class as being deprecated do this:
from incremental import Version from twisted.python.deprecate import deprecated @deprecated(Version("Twisted", 8, 0, 0)) def badAPI(self, first, second): ''' Docstring for badAPI. ''' ... @deprecated(Version("Twisted", 16, 0, 0)) class BadClass(object): ''' Docstring for BadClass. '''
The newly-decorated badAPI will issue a warning when called, and BadClass will issue a warning when instantiated. Both will also have a deprecation notice appended to their docstring.
To deprecate properties you can use:
from incremental import Version from twisted.python.deprecate import deprecatedProperty class OtherwiseUndeprecatedClass(object): @deprecatedProperty(Version('Twisted', 16, 0, 0)) def badProperty(self): ''' Docstring for badProperty. ''' @badProperty.setter def badProperty(self, value): ''' Setter sill also raise the deprecation warning. '''
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 incremental.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. To deprecate a
property, see deprecatedProperty . |
Function | deprecatedProperty | Return a decorator that marks a property as deprecated. To deprecate a
regular callable or class, see 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. |
Function | _passedArgSpec | Take an inspect.ArgSpec, a tuple of positional arguments, and a dict of keyword arguments, and return a mapping of arguments that were actually passed to their passed values. |
Function | _passedSignature | Take an inspect.Signature ,
a tuple of positional arguments, and a dict of keyword arguments, and
return a mapping of arguments that were actually passed to their passed
values. |
Function | _mutuallyExclusiveArguments | Decorator which causes its decoratee to raise a TypeError
if two of the given arguments are passed at the same time. |
str
)
Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative.
Returns | a string like "please use twisted.python.modules.getModule instead". |
Generate an addition to a deprecated object's docstring that explains its deprecation.
Parameters | version | the version it was deprecated. (type: incremental.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." |
Return a string indicating that the Python name was deprecated in the given version.
Parameters | fqpn | Fully qualified Python name of the thing being deprecated (type: str ) |
version | Version that fqpn was deprecated in. (type: incremental.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 ) |
Return a string indicating that the callable was deprecated in the given version.
Parameters | callableThing | Callable object to be deprecated (type: callable ) |
version | Version that callableThing was deprecated in (type: incremental.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 incremental.Version
that the callable was deprecated in. (type: incremental.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 ) |
Append the given text to the docstring of 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.
Return a decorator that marks callables as deprecated. To deprecate a
property, see deprecatedProperty
.
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: incremental.Version ) |
version | the version that the callable was deprecated in. (type: incremental.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) |
Return a decorator that marks a property as deprecated. To deprecate a
regular callable or class, see deprecated
.
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: incremental.Version ) |
version | the version that the callable was deprecated in. (type: incremental.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 new property with deprecated setter and getter. (type: property ) | |
Present Since | 16.1.0 |
Return the warning method currently used to record deprecation warnings.
Set the warning method to use to record deprecation warnings.
The callable should take message, category and stacklevel. The return value is ignored.
Mark a module-level attribute as being deprecated.
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: incremental.Version ) | |
message | Deprecation message (type: str ) |
Declare a module-level attribute as being deprecated.
Parameters | version | Version that the attribute was deprecated in (type: incremental.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 ) |
Issue a warning string, identifying 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 |
Take an inspect.ArgSpec, a tuple of positional arguments, and a dict of keyword arguments, and return a mapping of arguments that were actually passed to their passed values.
Parameters | argspec | The argument specification for the function to inspect. (type: inspect.ArgSpec) |
positional | The positional arguments that were passed. (type: tuple ) | |
keyword | The keyword arguments that were passed. (type: dict ) | |
Returns | A dictionary mapping argument names (those declared in
argspec ) to values that were passed explicitly by the user. (type: dict
mapping str
to object ) |
Take an inspect.Signature
,
a tuple of positional arguments, and a dict of keyword arguments, and
return a mapping of arguments that were actually passed to their passed
values.
Parameters | signature | The signature of the function to inspect. (type: inspect.Signature ) |
positional | The positional arguments that were passed. (type: tuple ) | |
keyword | The keyword arguments that were passed. (type: dict ) | |
Returns | A dictionary mapping argument names (those declared in
signature ) to values that were passed explicitly by the user. (type: dict
mapping str
to object ) |
Decorator which causes its decoratee to raise a TypeError
if two of the given arguments are passed at the same time.
Parameters | argumentPairs | pairs of argument identifiers, each pair indicating an argument that may
not be passed in conjunction with another. (type: sequence of 2-sequences of str ) |
Returns | A decorator, used like so:
@_mutuallyExclusiveArguments([["tweedledum", "tweedledee"]]) def function(tweedledum=1, tweedledee=2): "Don't pass tweedledum and tweedledee at the same time."(type: 1-argument callable taking a callable and returning a callable.) |