Deprecation framework for Twisted.

To mark a method or function as being deprecated do this:

   from twisted.python.versions import Version
   from twisted.python.deprecate import deprecated

   @deprecated(Version("Twisted", 8, 0, 0))
   def badAPI(self, first, second):
       '''
       Docstring for badAPI.
       '''
       ...

The newly-decorated badAPI will issue a warning when called. It will also have a deprecation notice appended to its docstring.

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.

See also Version.

Variable DEPRECATION_WARNING_FORMAT The default deprecation warning string format to use when one is not provided by the user. (type: str)
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.
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 _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 _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 _mutuallyExclusiveArguments Decorator which causes its decoratee to raise a TypeError if two of the given arguments are passed at the same time.
DEPRECATION_WARNING_FORMAT =
The default deprecation warning string format to use when one is not provided by the user. (type: str)
def _getReplacementString(replacement): (source)

Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative.

Returnsa string like "please use twisted.python.modules.getModule instead".
def _getDeprecationDocstring(version, replacement=None): (source)

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

Parametersversionthe version it was deprecated. (type: Version)
replacementThe replacement, if specified. (type: str or callable)
Returnsa 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.

ParametersfqpnFully qualified Python name of the thing being deprecated (type: str)
versionVersion that fqpn was deprecated in. (type: twisted.python.versions.Version)
formatA user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT if None is given. (type: str)
replacementwhat 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)
ReturnsA textual description of the deprecation (type: str)
def getDeprecationWarningString(callableThing, version, format=None, replacement=None): (source)

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

ParameterscallableThingCallable object to be deprecated (type: callable)
versionVersion that callableThing was deprecated in (type: twisted.python.versions.Version)
formatA user-provided format to interpolate warning values into, or DEPRECATION_WARNING_FORMAT if None is given (type: str)
callableThingA callable to be deprecated. (type: callable)
versionThe twisted.python.versions.Version that the callable was deprecated in. (type: twisted.python.versions.Version)
replacementwhat 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)
ReturnsA string describing the deprecation. (type: str)
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 deprecated(version, replacement=None): (source)

Return a decorator that marks callables as deprecated.

ParametersversionThe 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: twisted.python.versions.Version)
versionthe version that the callable was deprecated in. (type: twisted.python.versions.Version)
replacementwhat 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)
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 _deprecateAttribute(proxy, name, version, message): (source)

Mark a module-level attribute as being deprecated.

ParametersproxyThe module proxy instance proxying the deprecated attributes (type: _ModuleProxy)
nameAttribute name (type: str)
versionVersion that the attribute was deprecated in (type: twisted.python.versions.Version)
messageDeprecation message (type: str)
def deprecatedModuleAttribute(version, message, moduleName, name): (source)

Declare a module-level attribute as being deprecated.

ParametersversionVersion that the attribute was deprecated in (type: twisted.python.versions.Version)
messageDeprecation message (type: str)
moduleNameFully-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)
nameAttribute name to deprecate (type: str)
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.

ParametersfunctionThe function that is being deprecated.
warningStringThe string that should be emitted by this warning. (type: str)
Present Since11.0
def _passed(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.

ParametersargspecThe argument specification for the function to inspect. (type: inspect.ArgSpec)
positionalThe positional arguments that were passed. (type: tuple)
keywordThe keyword arguments that were passed. (type: dict)
ReturnsA dictionary mapping argument names (those declared in argspec) to values that were passed explicitly by the user. (type: dict mapping str to object)
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.

ParametersargumentPairspairs of argument identifiers, each pair indicating an argument that may not be passed in conjunction with another. (type: sequence of 2-sequences of str)
ReturnsA 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.)
API Documentation for Twisted, generated by pydoctor at 2015-11-29 11:40:45.