twisted.python.deprecate

module documentation

(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", 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	`deprecatedKeywordParameter`	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	`deprecatedModuleAttribute`	Declare a module-level attribute as being deprecated.
Function	`deprecatedProperty`	Return a decorator that marks a property as deprecated. To deprecate a regular callable or class, see `deprecated`.
Function	`getDeprecationWarningString`	Return a string indicating that the callable was deprecated in the given version.
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	`warnAboutFunction`	Issue a warning string, identifying `offender` as the responsible code.
Constant	`DEPRECATION_WARNING_FORMAT`	The default deprecation warning string format to use when one is not provided by the user.
Class	`_DeprecatedAttribute`	Wrapper for deprecated attributes.
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.
Function	`_appendToDocstring`	Append the given text to the docstring of `thingWithDoc`.
Function	`_deprecateAttribute`	Mark a module-level attribute as being deprecated.
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	`_getReplacementString`	Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative.
Function	`_mutuallyExclusiveArguments`	Decorator which causes its decoratee to raise a `TypeError` if two of the given arguments are passed at the same time.
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.
Constant	`_P`	Undocumented
Type Variable	`_R`	Undocumented
Type Variable	`_Tc`	Undocumented

def deprecated(version: 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[[Callable[_P, _R]], Callable[_P, _R]]`	Undocumented

def deprecatedKeywordParameter(version: Version, name: str, replacement: str | None = 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[[_Tc], _Tc]`	Undocumented

Present Since
Twisted 21.2.0

def deprecatedModuleAttribute(version, message, moduleName, name): (source) ¶

Declare a module-level attribute as being deprecated.

Parameters
version:`incremental.Version`	Version that the attribute was deprecated in
message:`str`	Deprecation message
moduleName:`str`	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

def deprecatedProperty(version: Version, replacement: str | Callable[..., object] | None = None) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]: (source) ¶

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

def getDeprecationWarningString(callableThing, version, format=None, replacement=None): (source) ¶

Return a string indicating that the callable was deprecated in the given version.

Parameters
callableThing:`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.

def getWarningMethod(): (source) ¶

Return the warning method currently used to record deprecation warnings.

def setWarningMethod(newMethod): (source) ¶

Set the warning method to use to record deprecation warnings.

The callable should take message, category and stacklevel. The return value is ignored.

def warnAboutFunction(offender, warningString): (source) ¶

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:`str`	The string that should be emitted by this warning.

Present Since
11.0

DEPRECATION_WARNING_FORMAT: str = (source) ¶

The default deprecation warning string format to use when one is not provided by the user.

Value

'%(fqpn)s was deprecated in %(version)s'

def _appendToDocstring(thingWithDoc, textToAppend): (source) ¶

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.

def _deprecateAttribute(proxy, name, version, message): (source) ¶

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

def _getDeprecationDocstring(version, replacement=None): (source) ¶

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."

def _getDeprecationWarningString(fqpn, version, format=None, replacement=None): (source) ¶

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

def _getReplacementString(replacement): (source) ¶

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".

def _mutuallyExclusiveArguments(argumentPairs): (source) ¶

Decorator which causes its decoratee to raise a TypeError if two of the given arguments are passed at the same time.

Parameters
argumentPairs:sequence of 2-sequences of `str`	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."

def _passedArgSpec(argspec, positional, keyword): (source) ¶

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.

def _passedSignature(signature, positional, keyword): (source) ¶

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.

_P = (source) ¶

Undocumented

Value

ParamSpec('_P')

_R = (source) ¶

Undocumented

Value

TypeVar('_R')

_Tc = (source) ¶

Undocumented

Value

TypeVar('_Tc',
        bound=Callable[..., Any])