HEX
Server: Apache
System: Linux scp1.abinfocom.com 5.4.0-216-generic #236-Ubuntu SMP Fri Apr 11 19:53:21 UTC 2025 x86_64
User: confeduphaar (1010)
PHP: 8.1.33
Disabled: exec,passthru,shell_exec,system
$ pwd: /lib/python3/dist-packages/twisted/python/__pycache__/
Upload Files
File: //lib/python3/dist-packages/twisted/python/__pycache__/deprecate.cpython-38.pyc
U


W[�h�@sHdZddlmZmZddddddgZdd	lZdd	lZdd
lmam	Z	ddl
mZddlm
Z
dd
lmZddlmZdZdd�Zde_de_de_dd�Zd2dd�Zd3dd�Zd4dd�Zdd�Zd5dd�Zd6dd�Zdd�Zd d�ZGd!d"�d"e �Z!Gd#d$�d$e �Z"Gd%d&�d&e �Z#d'd(�Z$d)d�Z%d*d+�Z&d,d-�Z'd.d/�Z(d0d1�Z)d	S)7am
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.
�)�division�absolute_import�
deprecated�deprecatedProperty�getDeprecationWarningString�getWarningMethod�setWarningMethod�deprecatedModuleAttributeN)�warn�
warn_explicit)�findlinestarts��wraps)�getVersionString)�_PY3z&%(fqpn)s was deprecated in %(version)scCs�z
|j}Wntk
r$|j}YnXt�|�s:t�|�rL|j}d||fSt�|�r�z
|j}Wn$tk
r�d|j|jfYSXt	|�}d||fS|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}.
    z%s.%s)
�__qualname__�AttributeError�__name__�inspectZisclassZ
isfunction�
__module__ZismethodZim_class�_fullyQualifiedName)�obj�name�
moduleName�cls�	className�r�:/usr/lib/python3/dist-packages/twisted/python/deprecate.pyrcs


rztwisted.python.reflectZfullyQualifiedNamecCst|�rt|�}d|fS)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 %s instead)�callabler)�replacementrrr�_getReplacementString�s
r cCs*dt|�f}|r"d|t|�f}|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 %s�%s; %s�.)rr )�versionr�docrrr�_getDeprecationDocstring�sr%cCs6|dkrt}||t|�d�}|r2d|t|�f}|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#r!)�DEPRECATION_WARNING_FORMATrr )r&r#�formatr�
warningStringrrr�_getDeprecationWarningString�s��r*cCstt|�|||�S)a�
    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)Z
callableThingr#r(rrrrr�s�cCsx|jr|j��}ng}t|�dkr.|�|�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textToAppendZdocstringLinesZspacesrrr�_appendToDocstring�s	�r5cs��fdd�}|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 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
    cs>t��d���t����fdd��}t|t�����|_|S)zA
        Decorator that marks C{function} as deprecated.
        Ncst�tdd��||�S�N���
stacklevel�r
�DeprecationWarning��args�kwargs��functionr)rr�deprecatedFunction's�zDdeprecated.<locals>.deprecationDecorator.<locals>.deprecatedFunction)rrr5r%�deprecatedVersion)r@rA�rr#r?r�deprecationDecorator s��z(deprecated.<locals>.deprecationDecoratorr�r#rrDrrCrr
scs$Gdd�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 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
    c@s eZdZdZdd�Zdd�ZdS)z/deprecatedProperty.<locals>._DeprecatedPropertyzQ
        Extension of the build-in property to allow deprecated setters.
        cst����fdd��}|S)Ncst�jtdd��||�Sr6)r
r)r;r<�r@�selfrrrAXs�z^deprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrapper.<locals>.deprecatedFunctionr
)rGr@rArrFr�_deprecatedWrapperWszBdeprecatedProperty.<locals>._DeprecatedProperty._deprecatedWrappercSst�||�|��S)N)�property�setterrH)rGr@rrrrJbsz6deprecatedProperty.<locals>._DeprecatedProperty.setterN)rrrr.rHrJrrrr�_DeprecatedPropertyRsrKcs�trt��d���n8�j}t��dd}�j}d|||f}t|�d���t����fdd��}t|t	�����|_
�|�}�|_|S)Nr+�z%s.%s.%scst�tdd��||�Sr6r:r<r?rrrAws�zLdeprecatedProperty.<locals>.deprecationDecorator.<locals>.deprecatedFunction)rrrr�stackrr*rr5r%rBr))r@ZfunctionNamerrZfqdnrA�result�rKrr#r?rrDfs4���z0deprecatedProperty.<locals>.deprecationDecorator)rIrErrOrr8s!cCstS)zR
    Return the warning method currently used to record deprecation warnings.
    �r
rrrrr�scCs|adS)z�
    Set the warning method to use to record deprecation warnings.

    The callable should take message, category and stacklevel. The return
    value is ignored.
    NrP)Z	newMethodrrrr�sc@s(eZdZdZdd�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__)rGrSrrr�__init__�sz_InternalState.__init__cCst�t�|d�|�SrR)rT�__getattribute__)rGrrrrrW�s�z_InternalState.__getattribute__cCst�t�|d�||�SrR)rTrUrW)rGr�valuerrrrU�s�z_InternalState.__setattr__N)rrrr.rVrWrUrrrrrQ�srQc@s0eZdZdZdd�Zdd�Zdd�Zdd	�Zd
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}
    cCst|�}||_i|_d|_dS)NF)rQ�_module�_deprecatedAttributes�_lastWasPath)rG�module�staterrrrV�sz_ModuleProxy.__init__cCst|�}dt|�j|jfS)z�
        Get a string containing the type of the module proxy and a
        representation of the wrapped module object.
        z<%s module=%r>)rQ�typerrZ)rGr^rrr�__repr__�sz_ModuleProxy.__repr__cCs t|�}d|_t|j||�dS)z@
        Set an attribute on the wrapped module object.
        FN)rQr\�setattrrZ)rGrrXr^rrrrU�sz_ModuleProxy.__setattr__cCsXt|�}|jrd}n|j�|�}|dk	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)rQr\r[�get�getattrrZ)rGrr^ZdeprecatedAttributerXrrrrW�s	
z_ModuleProxy.__getattribute__N)rrrr.rVr`rUrWrrrrrY�s
		rYc@s eZdZdZdd�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,||_||_|jd||_||_||_dS)z7
        Initialise a deprecated name wrapper.
        r"N)r]rr&r#�message)rGr]rr#rfrrrrVs
z_DeprecatedAttribute.__init__cCs:t|j|j�}t|j|jtd|j�}t|t	dd�|S)zU
        Get the underlying attribute value and issue a deprecation warning.
        z: rLr8)
rdr]rr*r&r#r'rfr
r;)rGrNrfrrrrc(s
�z_DeprecatedAttribute.getN)rrrr.rVrcrrrrre	srecCs2t�|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
    rZr[N)rTrWre)rSrr#rfrZ�attrr[rrr�_deprecateAttribute8s�rhcCs8tj|}t|t�s&t|�}|tj|<t||||�dS)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�
isinstancerYrh)r#rfrrr]rrrr	Rs



c	Csdtj|j}t�|�}tt|j��}|dd}|j}t	t
|||j|�di�dd�}t
|f|�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 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
    ���r+Z__warningregistry__N)�category�filename�linenor]�registry�module_globals)rirjrrZ
getabsfile�listr�__code__�__globals__�dictr;r�
setdefaultr)Zoffenderr)ZoffenderModulernZ
lineStartsZ
lastLineNo�globalsr>rrr�warnAboutFunctionms

�rxcCs�i}t|j�t|�}|jdk	r.i}||j<|dkrb|jdkrJtd��n|t|j�d�||j<t|j|�D]\}}|||<qn|��D]H\}}||jkr�||kr�td��|||<q�|jdk	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)r0r=�keywordsZvarargs�	TypeError�zip�items)Zargspec�
positional�keywordrNZunpassedr>rrXrrr�_passedArgSpec�s&








r�c
Csti}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�|���q�|j||<qtd�||j���qt|�|k�rtd��|��D]R\}}	||j��k�rP||k�rFtd��|	||<n|dk	�rd|	||<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}
    Nrr+zmissing keyword arg {}z"'{}' parameter is invalid kind: {}ryrzr{)�	enumerateZ
parametersrZkindrZ	ParameterZVAR_POSITIONALr0ZVAR_KEYWORDZPOSITIONAL_OR_KEYWORDZPOSITIONAL_ONLYZKEYWORD_ONLY�default�emptyr}r(�keys)
�	signaturer�r�rNr>Z
numPositional�nrZparamrXrrr�_passedSignature�sF
�
�



r�cs�fdd�}|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.
    csHttdd�rt����t�nt����t�t������fdd��}|S)Nr�cs<��||�}�D] \}}||kr||krtd��q�||�S)NZnope)r})r=r>Z	arguments�this�that)�_passed�
argumentPairs�spec�wrappeerr�wrappeds

z=_mutuallyExclusiveArguments.<locals>.wrapper.<locals>.wrapped)rdrr�r�Z
getargspecr�r)r�r��r�)r�r�r�r�wrappers

z,_mutuallyExclusiveArguments.<locals>.wrapperr)r�r�rr�r�_mutuallyExclusiveArguments�sr�)N)NN)NN)N)N)*r.Z
__future__rr�__all__rir�warningsr
r�disr�	functoolsrZincrementalrZtwisted.python.compatrr'rrrrr r%r*rr5rrrrrTrQrYrerhr	rxr�r�r�rrrr�<module>sNE�


%�
$
+
SS/#+<
@ Telegram