Your IP : 172.28.240.42

Current Path : /usr/lib/python2.7/dist-packages/twisted/python/
Upload File :
Current File : //usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyc


6Nc@sUdZdddddgZddlZddlZddlmamZdd	lmZdd
l	m
Z
ddlmZdZ
d
Zde_de_dZdZddZdZdddZdddZddZdZdefdYZdefdYZdefdYZdZdZd Z dS(!s
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
L{deprecatedModuleAttribute} call is being made from, the C{__name__} global
can be used as the C{moduleName} parameter.

See also L{Version}.

@type DEPRECATION_WARNING_FORMAT: C{str}
@var DEPRECATION_WARNING_FORMAT: The default deprecation warning string format
    to use when one is not provided by the user.
t
deprecatedtgetDeprecationWarningStringtgetWarningMethodtsetWarningMethodtdeprecatedModuleAttributeiN(twarnt
warn_explicit(tfindlinestarts(tgetVersionString(tmergeFunctionMetadatas&%(fqpn)s was deprecated in %(version)scCsn|j}tj|s'tj|r>|j}d||fStj|rjt|j}d||fS|S(s
    Return the fully qualified name of a module, class, method or function.
    Classes and functions need to be module level ones to be correctly
    qualified.

    @rtype: C{str}.
    s%s.%s(t__name__tinspecttisclasst
isfunctiont
__module__tismethodt_fullyQualifiedNametim_class(tobjtnamet
moduleNamet	className((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRHs		stwisted.python.reflecttfullyQualifiedNamecCstS(sR
    Return the warning method currently used to record deprecation warnings.
    (R(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR^scCs
|adS(s
    Set the warning method to use to record deprecation warnings.

    The callable should take message, category and stacklevel. The return
    value is ignored.
    N(R(t	newMethod((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRfscCs:dt|f}|r2d|t|f}n|dS(s
    Generate an addition to a deprecated object's docstring that explains its
    deprecation.

    @param version: the version it was deprecated.
    @type version: L{Version}

    @param replacement: The replacement, if specified.
    @type replacement: C{str} or callable

    @return: a string like "Deprecated in Twisted 27.2.0; please use
        twisted.timestream.tachyon.flux instead."
    sDeprecated in %ss%s; %st.(Rt_getReplacementString(tversiontreplacementtdoc((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt_getDeprecationDocstringrscCs&t|rt|}nd|fS(s

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

    @type replacement: C{str} or callable

    @return: a string like "please use twisted.python.modules.getModule
        instead".
    splease use %s instead(tcallableR(R((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRs
cCsV|dkrt}n|i|d6t|d6}|rRd|t|f}n|S(ss
    Return a string indicating that the Python name was deprecated in the given
    version.

    @param fqpn: Fully qualified Python name of the thing being deprecated
    @type fqpn: C{str}

    @param version: Version that C{fqpn} was deprecated in.
    @type version: L{twisted.python.versions.Version}

    @param format: A user-provided format to interpolate warning values into, or
        L{DEPRECATION_WARNING_FORMAT
        <twisted.python.deprecate.DEPRECATION_WARNING_FORMAT>} if C{None} is
        given.
    @type format: C{str}

    @param replacement: what should be used in place of C{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 replacement: C{str} or callable

    @return: A textual description of the deprecation
    @rtype: C{str}
    tfqpnRs%s; %sN(tNonetDEPRECATION_WARNING_FORMATRR(RRtformatRt
warningString((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt_getDeprecationWarningStrings	cCstt||||S(s
    Return a string indicating that the callable was deprecated in the given
    version.

    @type callableThing: C{callable}
    @param callableThing: Callable object to be deprecated

    @type version: L{twisted.python.versions.Version}
    @param version: Version that C{callableThing} was deprecated in

    @type format: C{str}
    @param format: A user-provided format to interpolate warning values into,
        or L{DEPRECATION_WARNING_FORMAT
        <twisted.python.deprecate.DEPRECATION_WARNING_FORMAT>} if C{None} is
        given

    @param callableThing: A callable to be deprecated.

    @param version: The L{twisted.python.versions.Version} that the callable
        was deprecated in.

    @param 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 replacement: C{str} or callable

    @return: A string describing the deprecation.
    @rtype: C{str}
    (R$R(t
callableThingRR"R((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRscsfd}|S(s
    Return a decorator that marks callables as deprecated.

    @type version: L{twisted.python.versions.Version}
    @param 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 C{deprecatedVersion}
        attribute.

    @param version: the version that the callable was deprecated in.
    @type version: L{twisted.python.versions.Version}

    @param 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 replacement: C{str} or callable
    csYtdfd}t|}t|t|_|S(sA
        Decorator that marks C{function} as deprecated.
        cs ttdd||S(Nt
stackleveli(RtDeprecationWarning(targstkwargs(tfunctionR#(s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pytdeprecatedFunctions
N(RR R	t_appendToDocstringRtdeprecatedVersion(R*R+(RR(R*R#s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pytdeprecationDecorators	((RRR.((RRs</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRscCs|jr|jj}ng}t|dkrC|j|nQt|dkrn|jd|dgn&|j}|jd|||gdj||_dS(sv
    Append the given text to the docstring of C{thingWithDoc}.

    If C{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.
    iits
N(t__doc__t
splitlinestlentappendtextendtpoptjoin(tthingWithDocttextToAppendtdocstringLinestspaces((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR,s			
t_InternalStatecBs)eZdZdZdZdZRS(s
    An L{_InternalState} is a helper object for a L{_ModuleProxy}, so that it
    can easily access its own attributes, bypassing its logic for delegating to
    another object that it's proxying for.

    @ivar proxy: a L{ModuleProxy}
    cCstj|d|dS(Ntproxy(tobjectt__setattr__(tselfR<((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt__init__.scCstjtj|d|S(NR<(R=t__getattribute__(R?R((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRA2scCstjtj|d||S(NR<(R=R>RA(R?Rtvalue((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR>7s(R
RR0R@RAR>(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR;&s		t_ModuleProxycBs2eZdZdZdZdZdZRS(s
    Python module wrapper to hook module-level attribute access.

    Access to deprecated attributes first checks
    L{_ModuleProxy._deprecatedAttributes}, if the attribute does not appear
    there then access falls through to L{_ModuleProxy._module}, the wrapped
    module object.

    @ivar _module: Module on which to hook attribute access.
    @type _module: C{module}

    @ivar _deprecatedAttributes: Mapping of attribute names to objects that
        retrieve the module attribute's original value.
    @type _deprecatedAttributes: C{dict} mapping C{str} to
        L{_DeprecatedAttribute}

    @ivar _lastWasPath: Heuristic guess as to whether warnings about this
        package should be ignored for the next call.  If the last attribute
        access of this module was a C{getattr} of C{__path__}, we will assume
        that it was the import system doing it and we won't emit a warning for
        the next access, even if it is to a deprecated attribute.  The CPython
        import system always tries to access C{__path__}, then the attribute
        itself, then the attribute itself again, in both successful and failed
        cases.
    @type _lastWasPath: C{bool}
    cCs+t|}||_i|_t|_dS(N(R;t_modulet_deprecatedAttributestFalset_lastWasPath(R?tmoduletstate((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR@Xs		cCs&t|}dt|j|jfS(s
        Get a string containing the type of the module proxy and a
        representation of the wrapped module object.
        s<%s module=%r>(R;ttypeR
RD(R?RI((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt__repr___scCs,t|}t|_t|j||dS(s@
        Set an attribute on the wrapped module object.
        N(R;RFRGtsetattrRD(R?RRBRI((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR>hs	cCst|}|jrd}n|jj|}|dk	rK|j}nt|j|}|dkrut|_n	t|_|S(sG
        Get an attribute from the module object, possibly emitting a warning.

        If the specified name has been deprecated, then a warning is issued.
        (Unless certain obscure conditions are met; see
        L{_ModuleProxy._lastWasPath} for more information about what might quash
        such a warning.)
        t__path__N(	R;RGR REtgettgetattrRDtTrueRF(R?RRItdeprecatedAttributeRB((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRAqs				(R
RR0R@RKR>RA(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRC=s
					t_DeprecatedAttributecBs eZdZdZdZRS(sQ
    Wrapper for deprecated attributes.

    This is intended to be used by L{_ModuleProxy}. Calling
    L{_DeprecatedAttribute.get} will issue a warning and retrieve the
    underlying attribute's value.

    @type module: C{module}
    @ivar module: The original module instance containing this attribute

    @type fqpn: C{str}
    @ivar fqpn: Fully qualified Python name for the deprecated attribute

    @type version: L{twisted.python.versions.Version}
    @ivar version: Version that the attribute was deprecated in

    @type message: C{str}
    @ivar message: Deprecation message
    cCs<||_||_|jd||_||_||_dS(s7
        Initialise a deprecated name wrapper.
        RN(RHR
RRtmessage(R?RHRRRS((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR@s
			cCsOt|j|j}t|j|jtd|j}t|t	dd|S(sU
        Get the underlying attribute value and issue a deprecation warning.
        s: R&i(
RORHR
R$RRR!RSRR'(R?tresultRS((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRNs
(R
RR0R@RN(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRRs	cCsGtj|d}t||||}tj|d}|||<dS(s
    Mark a module-level attribute as being deprecated.

    @type proxy: L{_ModuleProxy}
    @param proxy: The module proxy instance proxying the deprecated attributes

    @type name: C{str}
    @param name: Attribute name

    @type version: L{twisted.python.versions.Version}
    @param version: Version that the attribute was deprecated in

    @type message: C{str}
    @param message: Deprecation message
    RDREN(R=RARR(R<RRRSRDtattrRE((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt_deprecateAttributes
cCsOtj|}t|ts8t|}|tj|<nt||||dS(sQ
    Declare a module-level attribute as being deprecated.

    @type version: L{twisted.python.versions.Version}
    @param version: Version that the attribute was deprecated in

    @type message: C{str}
    @param message: Deprecation message

    @type moduleName: C{str}
    @param 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 C{__name__} global can
        be helpful

    @type name: C{str}
    @param name: Attribute name to deprecate
    N(tsystmodulest
isinstanceRCRV(RRSRRRH((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRs

c
Cstj|j}tj|}tt|j}|dd}|j}t	dt
d|d|d|jd|jdid	d}tjd
 d
kr|jd	nt||dS(s
    Issue a warning string, identifying C{offender} as the responsible code.

    This function is used to deprecate some behavior of a function.  It differs
    from L{warnings.warn} in that it is not limited to deprecating the behavior
    of a function currently on the call stack.

    @param function: The function that is being deprecated.

    @param warningString: The string that should be emitted by this warning.
    @type warningString: C{str}

    @since: 11.0
    iitcategorytfilenametlinenoRHtregistryt__warningregistry__tmodule_globalsiiN(ii(RWRXRRt
getabsfiletlistRt	func_codetfunc_globalstdictR'R
t
setdefaultR tversion_infoR5R(toffenderR#toffenderModuleR[t
lineStartst
lastLineNotglobalsR)((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pytwarnAboutFunctions			(!R0t__all__RWRtwarningsRRtdisRttwisted.python.versionsRttwisted.python.utilR	R!RRR
RRR RRR$RRR,R=R;RCRRRVRRl(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt<module>-s:							%#+	S/