o
    bl                     @   s  d Z g dZddlZddlZddlmZ ddlmZ ddlm	Z	 ddl
mZmZmZmZmZmZ ddlmamZ dd	lmZmZ d
Zdd Zde_de_de_dd Zd<ddZd=ddZd=ddZdd Z d<ddZ!d<ddZ"dd Z#dd  Z$G d!d" d"Z%G d#d$ d$Z&G d%d& d&Z'd'd( Z(d)d* Z)d+d, Z*d-d. Z+d/d0 Z,d1d2 Z-ed3ed4ef d5Z.	d<d6ed7e/d8ee/ d9ee.ge.f fd:d;Z0dS )>aa  
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:
        '''
        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:

        @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.


To mark an optional, keyword parameter of a function or method as deprecated
without deprecating the function itself, you can use::

    @deprecatedKeywordParameter(Version("Twisted", 19, 2, 0), 'baz')
    def someFunction(foo, bar=0, baz=None):
        ...

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.
)
deprecateddeprecatedPropertygetDeprecationWarningStringgetWarningMethodsetWarningMethoddeprecatedModuleAttributedeprecatedKeywordParameter    N)findlinestartswraps)
ModuleType)AnyCallableDictOptionalTypeVarcast)warnwarn_explicit)VersiongetVersionStringz&%(fqpn)s was deprecated in %(version)sc                 C   sl   z| j }W n ty   | j}Y nw t| st| r&| j}| d| S t| r4| j d| j  S |S )z
    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}.
    .)__qualname__AttributeError__name__inspectisclass
isfunction
__module__ismethod)objname
moduleName r#   :/usr/lib/python3/dist-packages/twisted/python/deprecate.py_fullyQualifiedNameo   s   


r%   ztwisted.python.reflectfullyQualifiedNamec                 C   s   t | rt| } d|  dS )a
  
    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".
    zplease use z instead)callabler%   replacementr#   r#   r$   _getReplacementString   s   
r*   c                 C   s,   dt |  }|r| dt| }|d S )a  
    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."
    zDeprecated in ; r   )r   r*   )versionr)   docr#   r#   r$   _getDeprecationDocstring   s   r.   c                 C   s6   |du rt }|| t|d }|rd|t|}|S )ag  
    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}
    N)fqpnr,   z{}; {})DEPRECATION_WARNING_FORMATr   formatr*   )r/   r,   r1   r)   warningStringr#   r#   r$   _getDeprecationWarningString   s   r3   c                 C   s   t t| |||S )ak  
    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 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}
    )r3   r%   )callableThingr,   r1   r)   r#   r#   r$   r      s   r   c                 C   sx   | j r	| j  }ng }t|dkr|| nt|dkr&|d|dg n| }|d|| |g d|| _ dS )av  
    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.
    r       
N)__doc__
splitlineslenappendextendpopjoin)thingWithDoctextToAppenddocstringLinesspacesr#   r#   r$   _appendToDocstring   s   	rC   c                    s    fdd}|S )a  
    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 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                    s>   t  dt  fdd}t|t |_|S )zA
        Decorator that marks C{function} as deprecated.
        Nc                        t tdd  | i |S N   
stacklevelr   DeprecationWarningargskwargsfunctionr2   r#   r$   deprecatedFunction     zDdeprecated.<locals>.deprecationDecorator.<locals>.deprecatedFunction)r   r   rC   r.   deprecatedVersion)rO   rP   r)   r,   rN   r$   deprecationDecorator  s   
z(deprecated.<locals>.deprecationDecoratorr#   r,   r)   rT   r#   rS   r$   r     s   r   c                    s$   G dd dt   fdd}|S )a  
    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 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
    c                   @       e Zd ZdZdd Zdd ZdS )z/deprecatedProperty.<locals>._DeprecatedPropertyzQ
        Extension of the build-in property to allow deprecated setters.
        c                    s   t   fdd}|S )Nc                     s   t jtdd  | i |S rE   )r   r2   rJ   rK   rO   selfr#   r$   rP   J  s   z^deprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrapper.<locals>.deprecatedFunctionr
   )rX   rO   rP   r#   rW   r$   _deprecatedWrapperI  s   zBdeprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrapperc                 S   s   t | | |S N)propertysetterrY   )rX   rO   r#   r#   r$   r\   U     z6deprecatedProperty.<locals>._DeprecatedProperty.setterN)r   r   r   r8   rY   r\   r#   r#   r#   r$   _DeprecatedPropertyD  s    r^   c                    sL   t  d t  fdd}t|t |_|}|_|S )Nc                     rD   rE   rI   rK   rN   r#   r$   rP   ]  rQ   zLdeprecatedProperty.<locals>.deprecationDecorator.<locals>.deprecatedFunction)r   r   rC   r.   rR   r2   )rO   rP   resultr^   r)   r,   rN   r$   rT   X  s   
z0deprecatedProperty.<locals>.deprecationDecorator)r[   rU   r#   r`   r$   r   -  s   r   c                   C   s   t S )zR
    Return the warning method currently used to record deprecation warnings.
    r   r#   r#   r#   r$   r   n  s   r   c                 C   s   | a dS )z
    Set the warning method to use to record deprecation warnings.

    The callable should take message, category and stacklevel. The return
    value is ignored.
    Nra   )	newMethodr#   r#   r$   r   u  s   r   c                   @   s(   e Zd ZdZdd Zdd Zdd ZdS )	_InternalStatez
    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 | d| d S Nproxy)object__setattr__)rX   re   r#   r#   r$   __init__  r]   z_InternalState.__init__c                 C   s   t t | d|S rd   )rf   __getattribute__)rX   r!   r#   r#   r$   ri     s   z_InternalState.__getattribute__c                 C   s   t t | d||S rd   )rf   rg   ri   )rX   r!   valuer#   r#   r$   rg     s   z_InternalState.__setattr__N)r   r   r   r8   rh   ri   rg   r#   r#   r#   r$   rc     s
    rc   c                   @   s6   e Zd ZdZdd ZdefddZdd Zd	d
 ZdS )_ModuleProxya  
    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 |_d|_d S )NF)rc   _module_deprecatedAttributes_lastWasPath)rX   modulestater#   r#   r$   rh     s   
z_ModuleProxy.__init__returnc                 C   s"   t | }dt| j d|jdS )z
        Get a string containing the type of the module proxy and a
        representation of the wrapped module object.
        <z module=>)rc   typer   rl   )rX   rp   r#   r#   r$   __repr__  s   z_ModuleProxy.__repr__c                 C   s    t | }d|_t|j|| dS )z@
        Set an attribute on the wrapped module object.
        FN)rc   rn   setattrrl   )rX   r!   rj   rp   r#   r#   r$   rg     s   z_ModuleProxy.__setattr__c                 C   sZ   t | }|jr
d}n|j|}|dur| }nt|j|}|dkr(d|_|S d|_|S )aG  
        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.)
        N__path__TF)rc   rn   rm   getgetattrrl   )rX   r!   rp   deprecatedAttributerj   r#   r#   r$   ri     s   	
z_ModuleProxy.__getattribute__N)	r   r   r   r8   rh   strru   rg   ri   r#   r#   r#   r$   rk     s    rk   c                   @   rV   )_DeprecatedAttributeaE  
    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 )z7
        Initialise a deprecated name wrapper.
        r   N)ro   r   r/   r,   message)rX   ro   r!   r,   r}   r#   r#   r$   rh     s
   
z_DeprecatedAttribute.__init__c                 C   s:   t | j| j}t| j| jtd | j }t|t	dd |S )zU
        Get the underlying attribute value and issue a deprecation warning.
        z:    rG   )
ry   ro   r   r3   r/   r,   r0   r}   r   rJ   )rX   r_   r}   r#   r#   r$   rx     s   z_DeprecatedAttribute.getN)r   r   r   r8   rh   rx   r#   r#   r#   r$   r|     s    
r|   c                 C   s2   t | d}t||||}t | d}|||< dS )a  
    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
    rl   rm   N)rf   ri   r|   )re   r!   r,   r}   rl   attrrm   r#   r#   r$   _deprecateAttribute  s   r   c                 C   s>   t j| }t|tsttt|}|t j|< t||| | dS )aE  
    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)sysmodules
isinstancerk   r   r   r   )r,   r}   r"   r!   ro   r#   r#   r$   r   *  s
   


r   c              
   C   sL   t j| j }t|tt|tdd t| j	D |j
| jdi dd dS )a  
    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 offender: The function that is being deprecated.

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

    @since: 11.0
    c                 s   s    | ]\}}|V  qd S rZ   r#   ).0_
lineNumberr#   r#   r$   	<genexpr>[  s    z$warnAboutFunction.<locals>.<genexpr>__warningregistry__N)categoryfilenamelinenoro   registrymodule_globals)r   r   r   r   rJ   r   
getabsfilemaxr	   __code__r   __globals__
setdefault)offenderr2   offenderModuler#   r#   r$   warnAboutFunctionE  s   
r   c                 C   s   i }t | jt | }| jduri  }|| j< |dk r0| jdu r$td|t | jd || j< t| j|D ]\}}|||< q6| D ]#\}}|| jv rY||v rTtd|||< qC| jdurc|||< qCtd|S )a  
    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}
    Nr   Too many arguments.Already passed.no such param)r:   rL   keywordsvarargs	TypeErrorzipitems)argspec
positionalkeywordr_   unpassedrM   r!   rj   r#   r#   r$   _passedArgSpecb  s&   






r   c           
      C   sh  i }d}d}t | j D ]q\}\}}|jtjjkr+||d ||< t|| d }q|jtjjkr9i  }||< q|jtjj	tjj
fv rU|t|k rT|| ||< |d7 }q|jtjjkrt||vrs|jtjjkrntd| |j||< qtd| d|j t||krtd| D ]$\}}	|| j v r||v rtd|	||< q|dur|	||< qtd	|S )
a  
    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}
    Nr   r5   zmissing keyword arg 'z' parameter is invalid kind: r   r   r   )	enumerate
parametersr   kindr   	ParameterVAR_POSITIONALr:   VAR_KEYWORDPOSITIONAL_OR_KEYWORDPOSITIONAL_ONLYKEYWORD_ONLYdefaultemptyr   keys)
	signaturer   r   r_   rM   numPositionalnr!   paramrj   r#   r#   r$   _passedSignature  sF   


r   c                    s    fdd}|S )a  
    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                    s,   t t t fdd}|S )Nc                     sN    | |}D ]\}}||v r||v rt d||tf q| i |S )Nz5The %r and %r arguments to %s are mutually exclusive.)r   r%   )rL   rM   	argumentsthisthat)_passedargumentPairsspecwrappeer#   r$   wrapped  s   z=_mutuallyExclusiveArguments.<locals>.wrapper.<locals>.wrapped)r   r   r   r   )r   r   r   )r   r   r   r$   wrapper  s
   

z,_mutuallyExclusiveArguments.<locals>.wrapperr#   )r   r   r#   r   r$   _mutuallyExclusiveArguments  s   r   _Tc.)boundr,   r!   r)   rq   c                    s   dt dt f fdd}|S )aw  
    Return a decorator that marks a keyword parameter of a callable
    as deprecated. A warning will be emitted if a caller supplies
    a value for the parameter, whether the caller uses a keyword or
    positional syntax.

    @type version: L{incremental.Version}
    @param version: The version in which the parameter will be marked as
        having been deprecated.

    @type name: L{str}
    @param name: The name of the deprecated parameter.

    @type replacement: L{str}
    @param replacement: Optional text indicating what should be used in
        place of the deprecated parameter.

    @since: Twisted 21.2.0
    r   rq   c                    s   t ddt ddt}r!|d t }|d7 }tj}|v rI| jtj	j
krIt|  fdd}nfd	d}ttt|}t|| |S )
NzThe z parameter to r(   z'The {!r} parameter was deprecated in {}r+   r   c                     s0   t | ks
 |v rttdd | i |S rE   )r:   r   rJ   rK   )r!   parameterIndexr2   r   r#   r$   checkDeprecatedParameter  s   zMdeprecatedKeywordParameter.<locals>.wrapper.<locals>.checkDeprecatedParameterc                     s$    |v rt tdd | i |S rE   rI   rK   )r!   r2   r   r#   r$   r   %  s   )r3   r%   r1   r   r*   r   r   r   r   r   r   listindexr   r   r   rC   )r   r-   paramsr   	decoratedr!   r)   r,   )r   r2   r   r$   r     s*   
z+deprecatedKeywordParameter.<locals>.wrapper)r   )r,   r!   r)   r   r#   r   r$   r     s   &r   rZ   )NN)1r8   __all__r   r   disr	   	functoolsr   typesr   typingr   r   r   r   r   r   warningsr   r   incrementalr   r   r0   r%   r   r   r   r*   r.   r3   r   rC   r   r   r   r   rc   rk   r|   r   r   r   r   r   r   r   r{   r   r#   r#   r#   r$   <module>   sX   N 


#

'AP/*<&