OwlCyberSecurity - MANAGER
Edit File: deprecate.pyc
� `��ac @` s� d Z d d l m Z m Z d d d d d d g Z d d l Z d d l Z d d l m a m Z d d l m Z d d l m Z d d l m Z d d l m Z d Z d � Z d e _ d e _ d e _ d � Z d d � Z d d d � Z d d d � Z d � Z d d � Z d d � Z d � Z d � Z d e! f d � � YZ" d e! f d � � YZ# d e! f d! � � YZ$ d" � Z% d# � Z& d$ � Z' d% � Z( d& � Z) d' � Z* d S(( sm Deprecation framework for Twisted. To mark a method, function, or class as being deprecated do this:: from incremental import Version from twisted.python.deprecate import deprecated @deprecated(Version("Twisted", 8, 0, 0)) def badAPI(self, first, second): ''' Docstring for badAPI. ''' ... @deprecated(Version("Twisted", 16, 0, 0)) class BadClass(object): ''' Docstring for BadClass. ''' The newly-decorated badAPI will issue a warning when called, and BadClass will issue a warning when instantiated. Both will also have a deprecation notice appended to their docstring. To deprecate properties you can use:: from incremental import Version from twisted.python.deprecate import deprecatedProperty class OtherwiseUndeprecatedClass(object): @deprecatedProperty(Version('Twisted', 16, 0, 0)) def badProperty(self): ''' Docstring for badProperty. ''' @badProperty.setter def badProperty(self, value): ''' Setter sill also raise the deprecation warning. ''' 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{incremental.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 ( t divisiont absolute_importt deprecatedt deprecatedPropertyt getDeprecationWarningStringt getWarningMethodt setWarningMethodt deprecatedModuleAttributeN( t warnt warn_explicit( t findlinestarts( t wraps( t getVersionString( t _PY3s& %(fqpn)s was deprecated in %(version)sc C` s� y | j } Wn t k r) | j } n Xt j | � sH t j | � r_ | j } d | | f St j | � r� y | j } Wn" t k r� d | j | j f SXt | � } d | | f Sn | 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__t AttributeErrort __name__t inspectt isclasst isfunctiont __module__t ismethodt im_classt _fullyQualifiedName( t objt namet moduleNamet clst className( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR c s s twisted.python.reflectt fullyQualifiedNamec C` s& t | � r t | � } n d | f S( 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". s please use %s instead( t callableR ( t replacement( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _getReplacementString� s c C` s: d t | � f } | r2 d | t | � f } n | d S( s� Generate an addition to a deprecated object's docstring that explains its deprecation. @param version: the version it was deprecated. @type version: L{incremental.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." s Deprecated in %ss %s; %st .( R R ( t versionR t doc( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _getDeprecationDocstring� s c C` sV | d k r t } n | i | d 6t | � d 6} | rR d | t | � f } n | S( sg 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{incremental.Version} @param format: A user-provided format to interpolate warning values into, or L{DEPRECATION_WARNING_FORMAT <twisted.python.deprecate.DEPRECATION_WARNING_FORMAT>} if L{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} t fqpnR" s %s; %sN( t Nonet DEPRECATION_WARNING_FORMATR R ( R% R" t formatR t warningString( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _getDeprecationWarningString� s c C` s t t | � | | | � 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{incremental.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 L{None} is given @param callableThing: A callable to be deprecated. @param version: The L{incremental.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 ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR � s c C` s� | j r | j j � } n g } t | � d k rC | j | � nQ t | � d k rn | j d | d g � n& | j � } | j d | | | g � d j | � | _ d S( 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. i i t s N( t __doc__t splitlinest lent appendt extendt popt join( t thingWithDoct textToAppendt docstringLinest spaces( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _appendToDocstring� s c ` s � � f d � } | S( s Return a decorator that marks callables as deprecated. To deprecate a property, see L{deprecatedProperty}. @type version: L{incremental.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{incremental.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 ` sV t � � d � � � t � � � � f d � � } t | t � � � � � | _ | S( sA Decorator that marks C{function} as deprecated. c ` s t � t d d �� | | � S( Nt stackleveli ( R t DeprecationWarning( t argst kwargs( t functionR) ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt deprecatedFunction' s N( R R& R R8 R$ t deprecatedVersion( R= R> ( R R" ( R= R) s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt deprecationDecorator s ( ( R" R R@ ( ( R R" s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR s c ` s/ d t f d � � Y� � � � f d � } | S( s� Return a decorator that marks a property as deprecated. To deprecate a regular callable or class, see L{deprecated}. @type version: L{incremental.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{incremental.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 @return: A new property with deprecated setter and getter. @rtype: C{property} @since: 16.1.0 t _DeprecatedPropertyc B` s e Z d Z d � Z d � Z RS( sQ Extension of the build-in property to allow deprecated setters. c ` s" t � � � � f d � � } | S( Nc ` s# t � j t d d �� | | � S( NR9 i ( R R) R: ( R; R< ( R= t self( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR> X s ( R ( RB R= R> ( ( R= RB s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _deprecatedWrapperW s c S` s t j | | j | � � S( N( t propertyt setterRC ( RB R= ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRE b s ( R R R- RC RE ( ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRA R s c ` s� t r t � � d � � � nN � j } t j � d d } � j } d | | | f } t | � d � � � t � � � � f d � � } t | t � � � � � | _ � | � } � | _ | S( Ni i s %s.%s.%sc ` s t � t d d �� | | � S( NR9 i ( R R: ( R; R< ( R= R) ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR> w s ( R R R& R R t stackR R* R R8 R$ R? R) ( R= t functionNameR R t fqdnR> t result( RA R R" ( R= R) s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR@ f s ( RD ( R" R R@ ( ( RA R R" s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR 8 s !c C` s t S( sR Return the warning method currently used to record deprecation warnings. ( R ( ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR � s c C` s | a d S( 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[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR � s t _InternalStatec B` s) e Z d Z d � Z d � Z d � Z RS( 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} c C` s t j | d | � d S( Nt proxy( t objectt __setattr__( RB RL ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt __init__� s c C` s t j t j | d � | � S( NRL ( RM t __getattribute__( RB R ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRP � s c C` s t j t j | d � | | � S( NRL ( RM RN RP ( RB R t value( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRN � s ( R R R- RO RP RN ( ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRK � s t _ModuleProxyc B` s2 e Z d Z d � Z d � Z d � Z d � Z RS( 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} c C` s+ t | � } | | _ i | _ t | _ d S( N( RK t _modulet _deprecatedAttributest Falset _lastWasPath( RB t modulet state( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRO � s c C` s& t | � } d t | � j | j f S( s� Get a string containing the type of the module proxy and a representation of the wrapped module object. s <%s module=%r>( RK t typeR RS ( RB RX ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt __repr__� s c C` s, t | � } t | _ t | j | | � d S( s@ Set an attribute on the wrapped module object. N( RK RU RV t setattrRS ( RB R RQ RX ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRN � s c C` s� t | � } | j r d } n | j j | � } | d k rK | j � } n t | j | � } | d k ru t | _ 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( RK RV R& RT t gett getattrRS t TrueRU ( RB R RX t deprecatedAttributeRQ ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRP � s ( R R R- RO RZ RN RP ( ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRR � s t _DeprecatedAttributec B` s e Z d Z d � Z d � Z RS( sE 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{incremental.Version} @ivar version: Version that the attribute was deprecated in @type message: C{str} @ivar message: Deprecation message c C` s< | | _ | | _ | j d | | _ | | _ | | _ d S( s7 Initialise a deprecated name wrapper. R! N( RW R R% R" t message( RB RW R R" Rb ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRO s c C` sO t | j | j � } t | j | j t d | j � } t | t d d �| S( sU Get the underlying attribute value and issue a deprecation warning. s : R9 i ( R^ RW R R* R% R" R' Rb R R: ( RB RI Rb ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR] ( s ( R R R- RO R] ( ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyRa s c C` sG t j | d � } t | | | | � } t j | d � } | | | <d S( 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{incremental.Version} @param version: Version that the attribute was deprecated in @type message: C{str} @param message: Deprecation message RS RT N( RM RP Ra ( RL R R" Rb RS t attrRT ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _deprecateAttribute8 s c C` sO t j | } t | t � s8 t | � } | t j | <n t | | | | � d S( sE Declare a module-level attribute as being deprecated. @type version: L{incremental.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( t syst modulest isinstanceRR Rd ( R" Rb R R RW ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyR R s c C` s� t j | j } t j | � } t t | j � � } | d d } | j } t d t d | d | d | j d | j d i � d d � } t | | � 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 i����i t categoryt filenamet linenoRW t registryt __warningregistry__t module_globalsN( Re Rf R R t getabsfilet listR t __code__t __globals__t dictR: R t setdefaultR& R ( t offenderR) t offenderModuleRi t lineStartst lastLineNot globalsR< ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt warnAboutFunctionm s c C` s6 i } t | j � t | � } | j d k rB i } | | j <n | d k r� | j d k rl t d � � q� | t | j � | | j <n x* t | j | � D] \ } } | | | <q� Wxy | j � D]k \ } } | | j k r| | k r� t d � � n | | | <q� | j d k r"| | | <q� t d � � q� W| S( s� Take an I{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. @param argspec: The argument specification for the function to inspect. @type argspec: I{inspect.ArgSpec} @param positional: The positional arguments that were passed. @type positional: L{tuple} @param keyword: The keyword arguments that were passed. @type keyword: L{dict} @return: A dictionary mapping argument names (those declared in C{argspec}) to values that were passed explicitly by the user. @rtype: L{dict} mapping L{str} to L{object} i s Too many arguments.s Already passed.s no such paramN( R/ R; t keywordsR& t varargst TypeErrort zipt items( t argspect positionalt keywordRI t unpassedR< R RQ ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _passedArgSpec� s& c C` s i } d } d } xVt | j j � � D]?\ } \ } } | j t j j k rt | | | | <t | | � d } q( | j t j j k r� i } | | <q( | j t j j t j j f k r� | t | � k rg| | | | <| d 7} qgq( | j t j j k rL| | k rg| j t j j k r9t d j | � � � qI| j | | <qgq( t d j | | j � � � q( Wt | � | k r�t d � � n x| | j � D]n \ } } | | j j � k r�| | k r�t d � � n | | | <q�| d k r�| | | <q�t d � � q�W| S( s� Take an L{inspect.Signature}, 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. @param signature: The signature of the function to inspect. @type signature: L{inspect.Signature} @param positional: The positional arguments that were passed. @type positional: L{tuple} @param keyword: The keyword arguments that were passed. @type keyword: L{dict} @return: A dictionary mapping argument names (those declared in C{signature}) to values that were passed explicitly by the user. @rtype: L{dict} mapping L{str} to L{object} i i s missing keyword arg {}s" '{}' parameter is invalid kind: {}s Too many arguments.s Already passed.s no such paramN( R& t enumeratet parametersR~ t kindR t Parametert VAR_POSITIONALR/ t VAR_KEYWORDt POSITIONAL_OR_KEYWORDt POSITIONAL_ONLYt KEYWORD_ONLYt defaultt emptyR| R( t keys( t signatureR� R� RI R< t numPositionalt nR t paramRQ ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _passedSignature� s@ ( c ` s � f d � } | S( s� Decorator which causes its decoratee to raise a L{TypeError} if two of the given arguments are passed at the same time. @param argumentPairs: pairs of argument identifiers, each pair indicating an argument that may not be passed in conjunction with another. @type argumentPairs: sequence of 2-sequences of L{str} @return: A decorator, used like so:: @_mutuallyExclusiveArguments([["tweedledum", "tweedledee"]]) def function(tweedledum=1, tweedledee=2): "Don't pass tweedledum and tweedledee at the same time." @rtype: 1-argument callable taking a callable and returning a callable. c ` sg t t d d � r* t j � � � t � n t j � � � t � t � � � � � � f d � � } | S( NR� c ` sp � � | | � } xN � D]F \ } } | | k r | | k r t d | | t � � f � � q q W� | | � S( Ns5 The %r and %r arguments to %s are mutually exclusive.( R| R ( R; R< t argumentst thist that( t _passedt argumentPairst spect wrappee( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt wrapped s ( R^ R R& R� R� t getargspecR� R ( R� R� ( R� ( R� R� R� s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt wrapper s $ ( ( R� R� ( ( R� s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt _mutuallyExclusiveArguments� s (+ R- t __future__R R t __all__Re R t warningsR R t disR t functoolsR t incrementalR t twisted.python.compatR R' R R R R R R& R$ R* R R8 R R R R RM RK RR Ra Rd R Ry R� R� R� ( ( ( s[ /opt/cpanel-ccs/.develop/virtualenv/lib/python2.7/site-packages/twisted/python/deprecate.pyt <module>H sJ % # + S S/ # + <