0x1949 Team - FAZEMRX - MANAGER
Edit File: deprecate.cpython-310.pyc
o �bl � @ s� d Z g d�ZddlZddlZddlmZ ddlmZ ddlm Z ddl m Z m Z m Z mZmZmZ ddlmamZ dd lmZmZ d Zd d � Zd e_de_de_dd� Z d<dd�Z d=dd�Z d=dd�Z dd� Z d<dd�Z!d<dd �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-ed3e d4e f d5�Z. d<d6ed7e/d8ee/ d9e e.ge.f fd: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 C sl z| j }W n ty | j}Y nw 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% ztwisted.python.reflect�fullyQualifiedNamec C s t | �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". z please use z instead)�callabler% �� replacementr# r# r$ �_getReplacementString� s r* c C s, dt | �� �}|r|� dt|�� �}|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." zDeprecated in �; r )r r* )�versionr) �docr# r# r$ �_getDeprecationDocstring� s r. c C s6 |du rt }|| 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, 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 �� }ng }t|�dkr|�|� n t|�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 rC c s � �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 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 �tdd� � | 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 dd� 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 @ � e Zd ZdZdd� Zdd� ZdS )z/deprecatedProperty.<locals>._DeprecatedPropertyzQ Extension of the build-in property to allow deprecated setters. c s t � �� �fdd��}|S )Nc s t �jtdd� � | 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� �� �fdd��}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 dS )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 Zd ZdZdd� 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} 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 Zd ZdZdd� Zdefdd�Zdd� Zd d � 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} 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 | �}dt| �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||� dS )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 | �}|jr d}n|j�|�}|dur|�� }nt|j|�}|dkr(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, || _ || _|jd | | _|| _|| _dS )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| jtd | j �}t|t dd� |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�}|||< 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 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�sttt|��}|t j|< 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� isinstancerk r r r� )r, r} r" r! ro r# r# r$ r * s r c C sL t j| j }t|tt�|�tdd� 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 s s � | ]\}}|V qd 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 |� }| jduri }|| j< |dk r0| jdu r$td��|t | j�d� || j< t| j|�D ]\}}|||< q6|�� D ]#\}}|| jv rY||v rTtd��|||< qC| jdurc|||< 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_ �unpassedrM r! rj r# r# r$ �_passedArgSpecb s& r� c C sh i }d}d}t | j�� �D ]q\}\}}|jtjjkr+||d� ||< t|| �d }q |jtjjkr9i }||< q |jtjj tjj fv rU|t|�k rT|| ||< |d7 }q |jtjj krt||vrs|j tjj krntd|� ���|j ||< q td|� d|j� ���t|�|kr�td��|�� D ]$\}} || j�� v r�||v r�td��| ||< q�|dur�| ||< 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} Nr r5 zmissing 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 � 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. c s, t ����t� t��� ���fdd��}|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 dt dt f� ��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� rq c s� t d��dt��� ���d��d��t���}�r!|d t�� }|d7 }t���j}�|v rI|� jtj j krIt |�� ��� �� ��fdd�}n���fd d�}t tt��|��}t||� |S ) NzThe z parameter to r( z'The {!r} parameter was deprecated in {}r+ r c s0 t | ��ks � |v rt�tdd� �| i |��S rE )r: r rJ rK )r! �parameterIndexr2 r� r# r$ �checkDeprecatedParameter s zMdeprecatedKeywordParameter.<locals>.wrapper.<locals>.checkDeprecatedParameterc s$ � |v r t �tdd� �| 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/ *<&���� �