qlPc@`stdZddlmZmZdddddgZddlZddlZdd lmam Z dd l m Z dd l m Z dd lmZd ZdZde_de_de_dZddZdddZdddZdZddZdZdZdefdYZdefdYZ defdYZ!dZ"d Z#d!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. i(tdivisiontabsolute_importt deprecatedtgetDeprecationWarningStringtgetWarningMethodtsetWarningMethodtdeprecatedModuleAttributeN(twarnt warn_explicit(tfindlinestarts(twraps(tgetVersionStrings&%(fqpn)s was deprecated in %(version)scC`sy |j}Wntk r)|j}nXtj|sHtj|r_|j}d||fStj|ry |j}Wn"tk rd|j|jfSXt |}d||fSn|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 __qualname__tAttributeErrort__name__tinspecttisclasst isfunctiont __module__tismethodtim_classt_fullyQualifiedName(tobjtnamet moduleNametclst className((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRFs       stwisted.python.reflecttfullyQualifiedNamecC`s&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(t replacement((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyt_getReplacementStringgs cC`s: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.(R R(tversionRtdoc((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyt_getDeprecationDocstringwscC`sV|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 } 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} tfqpnR s%s; %sN(tNonetDEPRECATION_WARNING_FORMATR R(R#R tformatRt warningString((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyt_getDeprecationWarningStrings  cC`stt||||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 } 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 callableThingR R&R((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRscC`s|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((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyt_appendToDocstrings    c`sfd}|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 c`sVtdtfd}t|t|_|S(sA Decorator that marks C{function} as deprecated. c`s ttdd||S(Nt stackleveli(RtDeprecationWarning(targstkwargs(tfunctionR'(sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pytdeprecatedFunction s N(RR$R R6R"tdeprecatedVersion(R;R<(RR (R;R'sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pytdeprecationDecorators ((R RR>((RR sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRscC`stS(sR Return the warning method currently used to record deprecation warnings. (R(((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRscC`s |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((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyR"st_InternalStatecB`s)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} cC`stj|d|dS(Ntproxy(tobjectt __setattr__(tselfRA((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyt__init__6scC`stjtj|d|S(NRA(RBt__getattribute__(RDR((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRF:scC`stjtj|d||S(NRA(RBRCRF(RDRtvalue((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRC?s(RRR+RERFRC(((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyR@.s  t _ModuleProxycB`s2eZdZdZdZdZdZRS(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} cC`s+t|}||_i|_t|_dS(N(R@t_modulet_deprecatedAttributestFalset _lastWasPath(RDtmoduletstate((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRE`s   cC`s&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@ttypeRRI(RDRN((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyt__repr__gs cC`s,t|}t|_t|j||dS(s@ Set an attribute on the wrapped module object. N(R@RKRLtsetattrRI(RDRRGRN((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRCps  cC`st|}|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@RLR$RJtgettgetattrRItTrueRK(RDRRNtdeprecatedAttributeRG((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRFys       (RRR+RERPRCRF(((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRHEs   t_DeprecatedAttributecB`s 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 cC`s<||_||_|jd||_||_||_dS(s7 Initialise a deprecated name wrapper. RN(RMRR#R tmessage(RDRMRR RX((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyREs    cC`sOt|j|j}t|j|jtd|j}t|t dd|S(sU Get the underlying attribute value and issue a deprecation warning. s: R7i( RTRMRR(R#R R%RXRR8(RDtresultRX((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRSs (RRR+RERS(((sJ/var/www/html/hlstest/hls-proxy/Twisted-13.2.0/twisted/python/deprecate.pyRWs cC`sGtj|d}t||||}tj|d}|||-s>       % #  *  S/