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: ''' 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: @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.
To mark an optional, keyword parameter of a function or method as deprecated without deprecating the function itself, you can use:
@deprecatedKeywordParameter(Version("Twisted", 19, 2, 0), 'baz') def someFunction(foo, bar=0, baz=None): ...
See also incremental.Version
.
Variable | DEPRECATION_WARNING_FORMAT |
The default deprecation warning string format to use when one is not provided by the user. |
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 | deprecatedKeywordParameter |
No summary |
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. |
Variable | _Tc |
Undocumented |
str
)
Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative.
Parameters | replacement | Undocumented (type: str or callable) |
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 ) | |
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 ) |
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 ) |
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 |
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 | offender | 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.) |
Return a decorator that marks a keyword parameter of a callable as deprecated. A warning will be emitted if a caller supplies a value for the parameter, whether the caller uses a keyword or positional syntax.
Parameters | version | The version in which the parameter will be marked as having been deprecated. (type: incremental.Version ) |
name | The name of the deprecated parameter. (type: str ) | |
replacement | Optional text indicating what should be used in place of the deprecated parameter. (type: str ) | |
Returns | Undocumented (type: Callable[[_Tc], _Tc] ) | |
Present Since | Twisted 21.2.0 |