module documentation

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.VersionThe 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 callablewhat 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: 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.VersionThe version in which the parameter will be marked as having been deprecated.
name:strThe name of the deprecated parameter.
replacement:strOptional 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.VersionVersion that the attribute was deprecated in
message:strDeprecation message
moduleName:strFully-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:strAttribute name to deprecate
def deprecatedProperty(version, replacement=None): (source)

Return a decorator that marks a property as deprecated. To deprecate a regular callable or class, see deprecated.

Parameters
version:incremental.VersionThe 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 callablewhat 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
propertyA 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:callableCallable object to be deprecated
version:incremental.VersionVersion that callableThing was deprecated in.
format:strA user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT if None is given
replacement:str or callablewhat 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
strA 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
offenderThe function that is being deprecated.
warningString:strThe 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:_ModuleProxyThe module proxy instance proxying the deprecated attributes
name:strAttribute name
version:incremental.VersionVersion that the attribute was deprecated in
message:strDeprecation message
def _getDeprecationDocstring(version, replacement=None): (source)

Generate an addition to a deprecated object's docstring that explains its deprecation.

Parameters
version:incremental.Versionthe version it was deprecated.
replacement:str or callableThe 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:strFully qualified Python name of the thing being deprecated
version:incremental.VersionVersion that fqpn was deprecated in.
format:strA user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT if None is given.
replacement:str or callablewhat 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
strA 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 callableUndocumented
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 strpairs 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.ArgSpecThe argument specification for the function to inspect.
positional:tupleThe positional arguments that were passed.
keyword:dictThe keyword arguments that were passed.
Returns
dict mapping str to objectA 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.SignatureThe signature of the function to inspect.
positional:tupleThe positional arguments that were passed.
keyword:dictThe keyword arguments that were passed.
Returns
dict mapping str to objectA dictionary mapping argument names (those declared in signature) to values that were passed explicitly by the user.

Undocumented

Value
ParamSpec('_P')

Undocumented

Value
TypeVar('_R')

Undocumented

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