CMc@s?dZdddddgZddlZddlZddlmamZdd lmZdd l m Z dd l m Z d Z d Zde_de_dZdZddZdZdddZdddZddZdZdefdYZdefdYZdZdZdZdS(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(tversiont replacementtdoc((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 } 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 } 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 _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. @type _module: C{module} @ivar _module: Module on which to hook attribute access. @type _deprecatedAttributes: C{dict} mapping C{str} to L{_DeprecatedAttribute} @ivar _deprecatedAttributes: Mapping of attribute names to objects that retrieve the module attribute's original value. cCs*tj|d|tj|didS(Nt_modulet_deprecatedAttributes(tobjectt __setattr__(tselftmodule((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt__init__7scCs)tj|d}dt|j|fS(s Get a string containing the type of the module proxy and a representation of the wrapped module object. R<s<%s module=%r>(R>t__getattribute__ttypeR (R@R<((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt__repr__<s cCs&tj|d}t|||dS(s@ Set an attribute on the wrapped module object. R<N(R>RCtsetattr(R@RtvalueR<((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR?GscCsatj|d}tj|d}|j|}|dk rN|j}nt||}|S(s Get an attribute on the wrapped module object. If the specified name has been deprecated then a warning is issued. R<R=N(R>RCtgetR tgetattr(R@RR<R=tgetterRG((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRCOs  (R RR0RBRER?RC(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyR;&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(RAR RRtmessage(R@RARRRL((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRBvs    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( RIRAR R$RRR!RLRR'(R@tresultRL((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRHs (R RR0RBRH(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyRKbs cCsGtj|d}t||||}tj|d}|||RCRK(tproxyRRRLR<tattrR=((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt_deprecateAttributes  cCsOtj|}t|ts8t|}|tj|R;RKRPRRf(((s</usr/lib/python2.7/dist-packages/twisted/python/deprecate.pyt-s8       % # + </