twisted.python.deprecate : API documentation

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.

Variables DEPRECATION_WARNING_FORMAT The default deprecation warning string format to use when one is not provided by the user. (type: str )

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	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	deprecatedModuleAttribute	Declare a module-level attribute as being deprecated.
Function	warnAboutFunction	Issue a warning string, identifying `offender` as the responsible code.
Function	_getDeprecationDocstring	Generate an addition to a deprecated object's docstring that explains its deprecation.
Function	_getReplacementString	Surround a replacement for a deprecated API with some polite text exhorting the user to consider it as an alternative.
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	_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.

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

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

Parameters	version	the version it was deprecated. (type: `Version` )
	replacement	The replacement, if specified. (type: `str` or callable )
Returns	a string like "Deprecated in Twisted 27.2.0; please use twisted.timestream.tachyon.flux instead."

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	(type: `str` or callable )
Returns	a string like "please use twisted.python.modules.getModule 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	Fully qualified Python name of the thing being deprecated (type: `str` )
	version	Version that `fqpn` was deprecated in. (type: `twisted.python.versions.Version` )
	format	A user-provided format to interpolate warning values into, or `DEPRECATION_WARNING_FORMAT` if `None` is given. (type: `str` )
	replacement	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. (type: `str` or callable )
Returns	A 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.

Parameters	callableThing	Callable object to be deprecated (type: `callable` )
	version	Version that `callableThing` was deprecated in (type: `twisted.python.versions.Version` )
	format	A user-provided format to interpolate warning values into, or `DEPRECATION_WARNING_FORMAT` if `None` is given (type: `str` )
	callableThing	A callable to be deprecated.
	version	The `twisted.python.versions.Version` that the callable was deprecated in.
	replacement	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. (type: `str` or callable )
Returns	A string describing the deprecation. (type: `str` )

def deprecated(version, replacement=None): (source)

Return a decorator that marks callables as deprecated.

Parameters	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. (type: `twisted.python.versions.Version` )
	version	the version that the callable was deprecated in. (type: `twisted.python.versions.Version` )
	replacement	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. (type: `str` or callable )

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	The module proxy instance proxying the deprecated attributes (type: `_ModuleProxy` )
	name	Attribute name (type: `str` )
	version	Version that the attribute was deprecated in (type: `twisted.python.versions.Version` )
	message	Deprecation message (type: `str` )

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

Declare a module-level attribute as being deprecated.

Parameters	version	Version that the attribute was deprecated in (type: `twisted.python.versions.Version` )
	message	Deprecation message (type: `str` )
	moduleName	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 (type: `str` )
	name	Attribute 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.

Parameters	function	The function that is being deprecated.
	warningString	The string that should be emitted by this warning. (type: `str` )
Present Since	11.0

t.p.deprecate : module documentation