o

�
bl�@s�
dZgd
�
Z
ddlZddlZddlmZ
ddlmZ
ddlm	Z	
ddl
mZmZm
Z
mZmZmZ
ddlmamZ
dd	lmZmZ
d
Zdd�Zd
e_de_de_dd�Zd<dd�
Zd=dd�
Zd=dd�
Zdd�Z d<dd�
Z!d<dd�
Z"dd�Z#dd �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<d6ed7e/d8ee/d9ee.g
e.ffd:d;�Z0dS)>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
Cslz|j}
Wnt
y


|j}
Yn
wt�|�
st�|�
r&|j}|�d
|
��St�|�
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�_fullyQualifiedNameos




�





r%ztwisted.python.reflect�fullyQualifiedNamec

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
urt}||t
|
�
d�}|rd�|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,r1r)�
warningStringr#r#r$�_getDeprecationWarningString�s




�r3cCstt
|�
|
||�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}
    )r3r%)�
callableThingr,r1r)r#r#r$r�s
�rcCsx|jr	|j�
�}ng}t|�
d
kr|�|
�

nt|�
dkr&|�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)�thingWithDoc�textToAppend�docstringLines�spacesr#r#r$�_appendToDocstring�s	





rCcs��
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.
        Nc�t�
t
d
d�
�|i|
�
�
S�N��
�
stacklevel�r�DeprecationWarning��args�kwargs��functionr2r#r$�deprecatedFunction
�
zDdeprecated.<locals>.deprecationDecorator.<locals>.deprecatedFunction)rrrCr.�deprecatedVersion)rOrP�r)r,rNr$�deprecationDecorator
s
�


�
z(deprecated.<locals>.deprecationDecoratorr#�r,r)rTr#rSr$r

sr
cs$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@� 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�
�|i|
�
�
SrE)rr2rJrK�rO�selfr#r$rPJ
s


�z^deprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrapper.<locals>.deprecatedFunctionr
)rXrOrPr#rWr$�_deprecatedWrapperI
s

zBdeprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrappercSst�
||�|
�
�S�
N)�property�setterrY)rXrOr#r#r$r\U
�
z6deprecatedProperty.<locals>._DeprecatedProperty.setterN)rrrr8rYr\r#r#r#r$�_DeprecatedPropertyD
s
r^c
sLt��d���
t
��
��
fd
d��
}
t|
t����
�|
_�|
�
}�
|_|S)NcrDrErIrKrNr#r$rP]
rQzLdeprecatedProperty.<locals>.deprecationDecorator.<locals>.deprecatedFunction)rrrCr.rRr2)rOrP�result�r^r)r,rNr$rTX
s

�


�

z0deprecatedProperty.<locals>.deprecationDecorator)
r[rUr#r`r$r-
src
CstS)
zR
    Return the warning method currently used to record deprecation warnings.
    �
rr#r#r#r$rn
src


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.
    Nra)
�	newMethodr#r#r$ru
src@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__)rXrer#r#r$�__init__�
r]z_InternalState.__init__cCst�
t�
|d
�|
�Srd)rf�__getattribute__)rXr!r#r#r$ri�
s
z_InternalState.__getattribute__cCst�
t�|d
�|
|�Srd)rfrgri)rXr!�valuer#r#r$rg�
s
z_InternalState.__setattr__N)rrrr8rhrirgr#r#r#r$rc�
s

rcc@s6eZ
dZd
Zdd�Zdefdd�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)rc�_module�_deprecatedAttributes�_lastWasPath)rX�module�stater#r#r$rh�
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=�
>)rc�typerrl)rXrpr#r#r$�__repr__�
s
z_ModuleProxy.__repr__cCs t|�
}d
|_
t|j|
|�
dS)z@
        Set an attribute on the wrapped module object.
        FN)rcrn�setattrrl)rXr!rjrpr#r#r$rg�
s

z_ModuleProxy.__setattr__cCsZt|�
}|j
r
d
}n|j�|
�
}|d
u
r|��}nt|j|
�}|
dkr(d|_
|Sd|_
|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)rcrnrm�get�getattrrl)rXr!rp�deprecatedAttributerjr#r#r$ri�
s	




�
z_ModuleProxy.__getattribute__N)	rrrr8rh�strrurgrir#r#r#r$rk�
s
rkc@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
    cCs,|
|_||_
|
j
d
||_||_||_dS)z7
        Initialise a deprecated name wrapper.
        rN)rorr/r,�message)rXror!r,r}r#r#r$rh�
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: �rG)
ryrorr3r/r,r0r}rrJ)rXr_r}r#r#r$rxs

�
z_DeprecatedAttribute.getN)rrrr8rhrxr#r#r#r$r|�
s

r|cCs2t�
|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
    rlrmN)rfrir|)rer!r,r}rl�attrrmr#r#r$�_deprecateAttributes

r�cCs>tj
|}t|t�sttt|�
�}|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�
isinstancerkrrr�)r,r}r"r!ror#r#r$r*s






rc
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
qdSrZr#)�.0�
_�
lineNumberr#r#r$�	<genexpr>[s�z$warnAboutFunction.<locals>.<genexpr>�__warningregistry__N)�category�filename�linenoro�registry�module_globals)
r�r�rrrJr�
getabsfile�maxr	�__code__r�__globals__�
setdefault)�offenderr2�offenderModuler#r#r$�warnAboutFunctionEs








�r�cCs�i}t|j
�
t|
�
}|jd
u
ri}||j<|dkr0|jd
ur$td�
�
|
t|j
�
d
�||j<t|j
|
�D]\}}|||<q6|��D]#\}}||j
vrY||vrTtd�
�
|||<qC|jd
u
rc|||<qCtd�
�
|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_�unpassedrMr!rjr#r#r$�_passedArgSpecbs&






















r�c
Csh
i}d
}d}t|j
���
D]q\}\}}|jtjjkr+|
|d
�||<t||�
d}q
|jtjjkr9i}||<q
|jtjj	tjj
fvrU|t|
�
krT|
|||<|d7}q
|jtjjkrt||v
rs|jtjj
krntd|���
�
|j||<q
td|�d|j���
�
t|
�
|kr�td�
�
|��D]$\}}	||j
��vr�||vr�td�
�
|	||<q�|d
u
r�|	||<q�td	�
�
|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}
    Nrr5zmissing 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!�paramrjr#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��
���
�fd
d��
}
|
S)NcsN��||
�}�
D]\}}||vr||vrtd
||t
��
f�
�
q�|i|
�
�
S)Nz5The %r and %r arguments to %s are mutually exclusive.)r�r%)rLrM�	arguments�this�that)�_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.)
�boundr,r!r)rqcsd
tdtf��
�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�rqc
s�td
��dt
��
����d��
d��t��
�}
�r!|
dt��
}
|
d7}
t���
j}�|vrI|�jtj	j
krIt|�
���
����
�fdd�}n��
�fd	d�}t
tt��
|�
�}t||
�
|S)
NzThe z parameter to r(z'The {!r} parameter was deprecated in {}r+rcs0t|�
�
ks
�|
vrt
�td
d�
�|i|
�
�
SrE)r:rrJrK)r!�parameterIndexr2r�r#r$�checkDeprecatedParameters


zMdeprecatedKeywordParameter.<locals>.wrapper.<locals>.checkDeprecatedParametercs$�|
vrt�
t
d
d�
�|i|
�
�
SrErIrK)r!r2r�r#r$r�%s


)r3r%r1rr*rr�r�r�r�r��list�indexrr�rrC)r�r-�paramsr��	decorated�r!r)r,)r�r2r�r$r�s*



�

�





z+deprecatedKeywordParameter.<locals>.wrapper)
r�)r,r!r)r�r#r�r$r�s&rrZ)NN)1r8�__all__rr��disr	�	functoolsr�typesr�typingr
rrrrr�warningsrr�incrementalrrr0r%rrrr*r.r3rrCr
rrrrcrkr|r�rr�r�r�r�r�r{rr#r#r#r$�<module>
sXN



 






#

'AP/*<&�
�
�
��