U

�
bl�@s�
dZd
ddddddgZ
dd	lZdd	lZdd
lmZ
ddlmZ
ddlm	Z	
dd
l
mZmZm
Z
mZmZmZ
ddlmamZ
ddlmZmZ
dZdd�Zde_de_de_dd�Zd8dd�
Zd9dd�
Zd:dd�
Zdd�Z d;dd
�
Z!d<dd�
Z"d d�Z#d!d�Z$Gd"d#�d#�Z%Gd$d%�d%�Z&Gd&d'�d'�Z'd(d)�Z(d*d�Z)d+d,�Z*d-d.�Z+d/d0�Z,d1d2�Z-ed3ed4efd5�Z.d=ee/ee/ee.g
e.fd6�d7d�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
Csnz
|j}
Wnt
k
r$


|j}
YnXt�|�
s:t�|�
rN|j}|�d
|
��St�|�
rj|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__�inspectZisclassZ
isfunction�
__module__Zismethod)�obj�name�
moduleName�r �:/usr/lib/python3/dist-packages/twisted/python/deprecate.py�_fullyQualifiedNameos









r"ztwisted.python.reflectZfullyQualifiedNamec

Cst|�
rt
|�
}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".
    zplease use z instead)�callabler"�
�replacementr r r!�_getReplacementString�s


r&cCs,d
t|�
��}|
r$|�dt
|
�
��}|dS)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."
    zDeprecated in �; r)rr&)�versionr%�docr r r!�_getDeprecationDocstring�s


r*cCs6|d
krt}||t
|
�
d�}|r2d�|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(r-r%�
warningStringr r r!�_getDeprecationWarningString�s




�r/cCstt
|�
|
||�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}
    )r/r")Z
callableThingr(r-r%r r r!r�s
�cCsx|jr|j�
�}ng}t|�
d
kr.|�|
�

n:t|�
dkrL|�d|
dg�

n|��}|�d||
|g�

d�|�
|_dS)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)ZthingWithDocZtextToAppendZdocstringLinesZspacesr r r!�_appendToDocstring�s	





r:cs��
fd
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
��
��
fdd��
}
t|
t����
�|
_|
S)zA
        Decorator that marks C{function} as deprecated.
        Ncst�
t
d
d�
�||
�
S�N��
�
stacklevel�r�DeprecationWarning��args�kwargs��functionr.r r!�deprecatedFunction
s
zDdeprecated.<locals>.deprecationDecorator.<locals>.deprecatedFunction)rrr:r*�deprecatedVersion)rErF�r%r(rDr!�deprecationDecorator
s
�

�
z(deprecated.<locals>.deprecationDecoratorr �r(r%rIr rHr!r

scs$Gd
d�dt����
�fdd�}|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@s eZ
dZd
Zdd�Zdd�ZdS)z/deprecatedProperty.<locals>._DeprecatedPropertyzQ
        Extension of the build-in property to allow deprecated setters.
        cst��
��
fd
d��
}|S)Ncst�
j
td
d�
�||
�
Sr;)rr.r@rA�rE�selfr r!rFJ
s


�z^deprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrapper.<locals>.deprecatedFunctionr
)rLrErFr rKr!�_deprecatedWrapperI
s

zBdeprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrappercSst�
||�|
�
�S�
N)�property�setterrM)rLrEr r r!rPU
s
z6deprecatedProperty.<locals>._DeprecatedProperty.setterN)rrrr3rMrPr r r r!�_DeprecatedPropertyD
s
rQc
sLt��d���
t
��
��
fd
d��
}
t|
t����
�|
_�|
�
}�
|_|S)Ncst�
t
d
d�
�||
�
Sr;r?rArDr r!rF]
s
zLdeprecatedProperty.<locals>.deprecationDecorator.<locals>.deprecatedFunction)rrr:r*rGr.)rErF�result�rQr%r(rDr!rIX
s 

�

�

z0deprecatedProperty.<locals>.deprecationDecorator)
rOrJr rSr!r-
sc
CstS)
zR
    Return the warning method currently used to record deprecation warnings.
    �
rr r r r!rn
sc


Cs|ad
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.
    NrT)
Z	newMethodr r r!ru
sc@s(eZ
dZd
Zdd�Zdd�Zdd�ZdS)	�_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}
    cCst�
|d
|
�
dS�N�proxy)�object�__setattr__)rLrWr r r!�__init__�
s
z_InternalState.__init__cCst�
t�
|d
�|
�SrV)rX�__getattribute__)rLrr r r!r[�
s
z_InternalState.__getattribute__cCst�
t�|d
�|
|�SrV)rXrYr[)rLr�valuer r r!rY�
s
z_InternalState.__setattr__N)rrrr3rZr[rYr r r r!rU�
s
rUc@s6eZ
dZd
Zdd�Zed�
dd�Zdd�Zd	d
�ZdS)�_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}
    cCst|�
}|
|_
i|_d
|_dS)NF)rU�_module�_deprecatedAttributes�_lastWasPath)rL�module�stater r r!rZ�
s



z_ModuleProxy.__init__)
�returnc
Cs"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=�
>)rU�typerr^)rLrbr r r!�__repr__�
s
z_ModuleProxy.__repr__cCs t|�
}d
|_
t|j|
|�
dS)z@
        Set an attribute on the wrapped module object.
        FN)rUr`�setattrr^)rLrr\rbr r r!rY�
s

z_ModuleProxy.__setattr__cCsXt|�
}|j
rd
}n|j�|
�
}|d
k	r2|��}nt|j|
�}|
dkrNd|_
nd|_
|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)rUr`r_�get�getattrr^)rLrrbZdeprecatedAttributer\r r r!r[�
s	





z_ModuleProxy.__getattribute__N)	rrrr3rZ�strrgrYr[r r r r!r]�
s

r]c@s eZ
dZd
Zdd�Zdd�ZdS)�_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
    cCs,|
|_||_
|
j
d
||_||_||_dS)z7
        Initialise a deprecated name wrapper.
        rN)rarr+r(�message)rLrarr(rnr r r!rZ�
s




z_DeprecatedAttribute.__init__c
Cs:t|j
|j�}
t|j|jtd
|j�}t|t	dd�
|
S)zU
        Get the underlying attribute value and issue a deprecation warning.
        z: �r=)
rkrarr/r+r(r,rnrr@)rLrRrnr r r!rjs

�
z_DeprecatedAttribute.getN)rrrr3rZrjr r r r!rm�
s

rmcCs2t�
|d
�}t||
||�}t�
|d�}|||
<dS)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
    r^r_N)rXr[rm)rWrr(rnr^�attrr_r r r!�_deprecateAttributes

rqcCs>tj
|}t|t�s,ttt|�
�}|tj
|<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�
isinstancer]rrrq)r(rnrrrar r r!r*s






c
CsLtj
|j}t|
tt�|�
td
d�t|j	�
D�
�
|j
|j�di�dd�
dS)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
ss|]\}
}|V
qdSrNr )�.0�
_Z
lineNumberr r r!�	<genexpr>[sz$warnAboutFunction.<locals>.<genexpr>Z__warningregistry__N)�category�filename�linenora�registryZmodule_globals)
rrrsrrr@rZ
getabsfile�maxr	�__code__r�__globals__�
setdefault)Zoffenderr.ZoffenderModuler r r!�warnAboutFunctionEs







�r�cCs�i}t|j
�
t|
�
}|jd
k	r.i}||j<|dkrb|jd
krJtd�
�
n|
t|j
�
d
�||j<t|j
|
�D]\}}|||<qn|��D]H\}}||j
kr�||kr�td�
�
|||<q�|jd
k	r�|||<q�td�
�
q�|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)r5rB�keywordsZvarargs�	TypeError�zip�items)Zargspec�
positional�keywordrRZunpassedrCrr\r r r!�_passedArgSpecbs&
























r�c
Csx
i}d
}d}t|j
���
D]�\}\}}|jtjjkrV|
|d
�||<t||�
d}q|jtjjkrri}||<q|jtjj	tjj
fkr�|t|
�
kr�|
|||<|d7}q|jtjjkr�||kr�|jtjj
kr�td|���
�
n
|j||<qtd|�d|j���
�
qt|
�
|k�
rtd�
�
|��D]R\}}	||j
��k�
rT||k�
rJtd�
�
|	||<n|d
k	�
rh|	||<ntd	�
�
�
q |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}
    Nrr0zmissing keyword arg �
'z' parameter is invalid kind: r�r�r�)�	enumerate�
parametersr��kindr�	ParameterZVAR_POSITIONALr5ZVAR_KEYWORD�POSITIONAL_OR_KEYWORDZPOSITIONAL_ONLYZKEYWORD_ONLY�default�emptyr��keys)
�	signaturer�r�rRrCZ
numPositional�
nrZparamr\r r r!�_passedSignature�sB








�



















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��
���
�fd
d��
}
|
S)NcsJ��||
�}�
D].\}}||kr||krtd
||t
��
f�
�
q�||
�
S)Nz5The %r and %r arguments to %s are mutually exclusive.)r�r")rBrCZ	argumentsZthisZthat)�_passed�
argumentPairs�spec�wrappeer r!�wrapped�s




��z=_mutuallyExclusiveArguments.<locals>.wrapper.<locals>.wrapped)rr�r�r)r�r��
r�)r�r�r�r!�wrapper�s





z,_mutuallyExclusiveArguments.<locals>.wrapperr )r�r�r r�r!�_mutuallyExclusiveArguments�sr��_Tc.)
Zbound)r(rr%rccsttd
���
�fdd�}|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�rcc
s�td
��dt
��
����d��
d��t��
�}
�rB|
dt��
}
|
d7}
t���
j}�|kr�|�jtj	j
kr�t|�
���
����
�fdd�}n��
�fd	d�}t
tt��
|�
�}t||
�
|S)
NzThe z parameter to r$z'The {!r} parameter was deprecated in {}r'rcs,t|�
�
ks�|
kr"t
�td
d�
�||
�
Sr;)r5rr@rA)r�parameterIndexr.r�r r!�checkDeprecatedParameters


zMdeprecatedKeywordParameter.<locals>.wrapper.<locals>.checkDeprecatedParametercs �|
krt�
t
d
d�
�||
�
Sr;r?rA)rr.r�r r!r�%s


)r/r"r-rr&rr�r�r�r�r��list�indexrr�rr:)r�r)Zparamsr�Z	decorated�rr%r()r�r.r�r!r�s.



�

�

��


z+deprecatedKeywordParameter.<locals>.wrapper)
r�)r(rr%r�r r�r!r�s&)
N)NN)NN)
N)
N)
N)1r3�__all__rrrZdisr	�	functoolsr�typesr�typingr
rrrrr�warningsrr�incrementalrrr,r"rrrr&r*r/rr:r
rrrrUr]rmrqrr�r�r�r�r�rlrr r r r!�<module>s^O





�




 




#

'
AP/*<&�

�