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", 22, 10, 0)) def badAPI(self, first, second): ''' Docstring for badAPI. ''' ... @deprecated(Version("Twisted", 22, 10, 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", 22, 10, 0)) def badProperty(self): ''' Docstring for badProperty. ''' @badProperty.setter def badProperty(self, value): ''' Setter sill also raise the deprecation warning. '''
While it's best to avoid this as it adds performance overhead to *any* usage of the module, to mark module-level attributes as being deprecated you can use:
badAttribute = "someValue" ... deprecatedModuleAttribute( Version("Twisted", 22, 10, 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", 22, 10, 0), "baz") def someFunction(foo, bar=0, baz=None): ...
See also incremental.Version
.
Function | deprecated |
Return a decorator that marks callables as deprecated. To deprecate a property, see deprecatedProperty . |
Function | deprecated |
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. |
Function | deprecated |
Declare a module-level attribute as being deprecated. |
Function | deprecated |
Return a decorator that marks a property as deprecated. To deprecate a regular callable or class, see deprecated . |
Function | get |
Return a string indicating that the callable was deprecated in the given version. |
Function | get |
Return the warning method currently used to record deprecation warnings. |
Function | set |
Set the warning method to use to record deprecation warnings. |
Function | warn |
Issue a warning string, identifying offender as the responsible code. |
Constant | DEPRECATION |
The default deprecation warning string format to use when one is not provided by the user. |
Class | _ |
Wrapper for deprecated attributes. |
Class | _ |
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 | _ |
Python module wrapper to hook module-level attribute access. |
Function | _append |
Append the given text to the docstring of thingWithDoc. |
Function | _deprecate |
Mark a module-level attribute as being deprecated. |
Function | _get |
Generate an addition to a deprecated object's docstring that explains its deprecation. |
Function | _get |
Return a string indicating that the Python name was deprecated in the given version. |
Function | _get |
Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative. |
Function | _mutually |
Decorator which causes its decoratee to raise a TypeError if two of the given arguments are passed at the same time. |
Function | _passed |
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 | _passed |
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. |
Constant | _P |
Undocumented |
Type Variable | _R |
Undocumented |
Type Variable | _ |
Undocumented |
Version
, replacement: str|Callable[ ..., object]|None
= None) -> Callable[ [ Callable[ _P, _R]], Callable[ _P, _R]]
:
(source)
¶
Return a decorator that marks callables as deprecated. To deprecate a property, see deprecatedProperty
.
Parameters | |
version:incremental.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. |
replacement:str or callable | 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. |
Returns | |
Callable[ | Undocumented |
Version
, name: str
, replacement: Optional[ str]
= None) -> Callable[ [ _Tc], _Tc]
:
(source)
¶
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:incremental.Version | The version in which the parameter will be marked as having been deprecated. |
name:str | The name of the deprecated parameter. |
replacement:str | Optional text indicating what should be used in place of the deprecated parameter. |
Returns | |
Callable[ | Undocumented |
Present Since | |
Twisted 21.2.0 |
Declare a module-level attribute as being deprecated.
Parameters | |
version:incremental.Version | Version that the attribute was deprecated in |
message:str | Deprecation message |
module | 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 |
name:str | Attribute name to deprecate |
Return a decorator that marks a property as deprecated. To deprecate a regular callable or class, see deprecated
.
Parameters | |
version:incremental.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. |
replacement:str or callable | 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. |
Returns | |
property | A new property with deprecated setter and getter. |
Present Since | |
16.1.0 |
Return a string indicating that the callable was deprecated in the given version.
Parameters | |
callable | Callable object to be deprecated |
version:incremental.Version | Version that callableThing was deprecated in. |
format:str | A user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT if None is given |
replacement:str or callable | 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. |
Returns | |
str | A string describing the deprecation. |
Set the warning method to use to record deprecation warnings.
The callable should take message, category and stacklevel. The return value is ignored.
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. |
warning | The string that should be emitted by this warning. |
Present Since | |
11.0 |
The default deprecation warning string format to use when one is not provided by the user.
Value |
|
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.
Mark a module-level attribute as being deprecated.
Parameters | |
proxy:_ModuleProxy | The module proxy instance proxying the deprecated attributes |
name:str | Attribute name |
version:incremental.Version | Version that the attribute was deprecated in |
message:str | Deprecation message |
Generate an addition to a deprecated object's docstring that explains its deprecation.
Parameters | |
version:incremental.Version | the version it was deprecated. |
replacement:str or callable | The replacement, if specified. |
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:str | Fully qualified Python name of the thing being deprecated |
version:incremental.Version | Version that fqpn was deprecated in. |
format:str | A user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT if None is given. |
replacement:str or callable | 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. |
Returns | |
str | A textual description of the deprecation |
Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative.
Parameters | |
replacement:str or callable | Undocumented |
Returns | |
a string like "please use twisted.python.modules.getModule instead". |
Decorator which causes its decoratee to raise a TypeError
if two of the given arguments are passed at the same time.
Parameters | |
argumentstr | pairs of argument identifiers, each pair indicating an argument that may not be passed in conjunction with another. |
Returns | |
1-argument callable taking a callable and returning a callable. | A decorator, used like so: @_mutuallyExclusiveArguments([["tweedledum", "tweedledee"]]) def function(tweedledum=1, tweedledee=2): "Don't pass tweedledum and tweedledee at the same time." |
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:inspect.ArgSpec | The argument specification for the function to inspect. |
positional:tuple | The positional arguments that were passed. |
keyword:dict | The keyword arguments that were passed. |
Returns | |
dict mapping str to object | A dictionary mapping argument names (those declared in argspec) to values that were passed explicitly by the user. |
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:inspect.Signature | The signature of the function to inspect. |
positional:tuple | The positional arguments that were passed. |
keyword:dict | The keyword arguments that were passed. |
Returns | |
dict mapping str to object | A dictionary mapping argument names (those declared in signature) to values that were passed explicitly by the user. |