Go to the latest version of this document.

# ``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])