o io@sdZddlmZgdZddlZddlZddlmZddlm Z ddl m Z ddl m Z mZmZmZmZmZdd lmamZdd lmZmZdd lmZed Zed ZdZddZde_de_ de_!ddZ"dFddZ#dGddZ$dGddZ%ddZ& dFdHd#d$Z' dFdHd%d&Z(d'd(Z)d)d*Z*Gd+d,d,Z+Gd-d.d.Z,Gd/d0d0Z-d1d2Z.d3d4Z/d5d6Z0d7d8Z1d9d:Z2d;d<Z3ed=ed>e fd?Z4 dFdIdDdEZ5dS)Ja 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", 22, 10, 0)) def badAPI(self, first, second): ''' Docstring for badAPI. ''' ... @deprecated(Version("Twisted", 22, 10, 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", 22, 10, 0)) def badProperty(self): ''' Docstring for badProperty. ''' @badProperty.setter def badProperty(self, value): ''' Setter sill also raise the deprecation warning. ''' While it's best to avoid this as it adds performance overhead to *any* usage of the module, to mark module-level attributes as being deprecated you can use:: badAttribute = "someValue" ... deprecatedModuleAttribute( Version("Twisted", 22, 10, 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", 22, 10, 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. ) annotations) deprecateddeprecatedPropertygetDeprecationWarningStringgetWarningMethodsetWarningMethoddeprecatedModuleAttributedeprecatedKeywordParameterN)findlinestartswraps) ModuleType)AnyCallableDictOptionalTypeVarcast)warn warn_explicit)VersiongetVersionString) ParamSpec_P_Rz&%(fqpn)s was deprecated in %(version)scCslz|j}Wn ty|j}Ynwt|st|r&|j}|d|St|r4|jd|jS|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}. .N) __qualname__AttributeError__name__inspectisclass isfunction __module__ismethod)objname moduleNamer'^C:\Users\psant\Downloads\PAF backend\school\venv\Lib\site-packages\twisted/python/deprecate.py_fullyQualifiedNamets    r)ztwisted.python.reflectZfullyQualifiedNamecCst|rt|}d|dS)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 insteadN)callabler) replacementr'r'r(_getReplacementStrings  r-cCs,dt|}|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 ; rN)rr-)versionr,docr'r'r(_getDeprecationDocstringsr1cCs6|durt}||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 } 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_FORMATrformatr-)r2r/r4r, warningStringr'r'r(_getDeprecationWarningStringsr6cCstt||||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 } 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} N)r6r))Z callableThingr/r4r,r'r'r(rs rcCs|jr |j}ng}t|dkr||n.t|dkr&|d|dgn|d}d}|s4|}|d|||gdd|D}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. rcSsg|]}|dqS) )lstrip).0lr'r'r( sz&_appendToDocstring.. N)__doc__ splitlineslenappendextendstrippopjoin)Z thingWithDocZ textToAppendZdocstringLinestrailerspacesr'r'r(_appendToDocstrings    rJr/rr,"str | Callable[..., object] | Nonereturn.Callable[[Callable[_P, _R]], Callable[_P, _R]]csdfdd }|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 functionCallable[_P, _R]rLcs@tdtd fdd }t|t|_|S) zA Decorator that marks C{function} as deprecated. Nargs_P.argskwargs _P.kwargsrLrcttdd|i|SN stacklevelrDeprecationWarningrPrRrNr5r'r(deprecatedFunction+zDdeprecated..deprecationDecorator..deprecatedFunction)rPrQrRrSrLr)rr rJr1deprecatedVersion)rNr]r,r/r\r(deprecationDecorator#s z(deprecated..deprecationDecoratorN)rNrOrLrOr'r/r,rar'r`r(rsrcs$Gdddtfdd}|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@ eZdZdZddZddZdS)z/deprecatedProperty.._DeprecatedPropertyzQ Extension of the build-in property to allow deprecated setters. cstfdd}|S)Ncstjtdd|i|SrU)rr5rZr[rNselfr'r(r]Xs z^deprecatedProperty.._DeprecatedProperty._deprecatedWrapper..deprecatedFunctionr )rerNr]r'rdr(_deprecatedWrapperWszBdeprecatedProperty.._DeprecatedProperty._deprecatedWrappercSst|||SN)propertysetterrf)rerNr'r'r(ricz6deprecatedProperty.._DeprecatedProperty.setterN)rr"rr@rfrir'r'r'r(_DeprecatedPropertyRs rkcsLtdtfdd}t|t|_|}|_|S)NcrTrUrYr[r\r'r(r]kr^zLdeprecatedProperty..deprecationDecorator..deprecatedFunction)rr rJr1r_r5)rNr]resultrkr,r/r\r(rafs z0deprecatedProperty..deprecationDecoratorN)rhrbr'rmr(r9srcCstS)zR Return the warning method currently used to record deprecation warnings. Nrr'r'r'r(r|srcCs|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. Nrn)Z newMethodr'r'r(rsrc@s(eZdZdZddZddZddZdS) _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|dSNproxy)object __setattr__)rerqr'r'r(__init__rjz_InternalState.__init__cCstt|d|Srp)rr__getattribute__)rer%r'r'r(rusz_InternalState.__getattribute__cCstt|d||Srp)rrrsru)rer%valuer'r'r(rssz_InternalState.__setattr__N)rr"rr@rtrursr'r'r'r(ros  roc@s2eZdZdZddZd ddZdd 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} cCst|}||_i|_d|_dS)NF)ro_module_deprecatedAttributes _lastWasPath)remodulestater'r'r(rts z_ModuleProxy.__init__rLstrcCs"t|}dt|jd|jdS)z Get a string containing the type of the module proxy and a representation of the wrapped module object. N)rotyperrx)rer|r'r'r(__repr__sz_ModuleProxy.__repr__cCs t|}d|_t|j||dS)z@ Set an attribute on the wrapped module object. FN)rorzsetattrrx)rer%rvr|r'r'r(rssz_ModuleProxy.__setattr__cCsZt|}|jr d}n|j|}|dur|}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)rorzrygetgetattrrx)rer%r|ZdeprecatedAttributervr'r'r(rus    z_ModuleProxy.__getattribute__N)rLr})rr"rr@rtrrsrur'r'r'r(rws   rwc@rc)_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. rN)r{rr2r/message)rer{r%r/rr'r'r(rts  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: rWN) rr{rr6r2r/r3rrrZ)rerlrr'r'r(rs z_DeprecatedAttribute.getN)rr"rr@rtrr'r'r'r(rs rcCs2t|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 rxryN)rrrur)rqr%r/rrxattrryr'r'r(_deprecateAttribute s   rcCs>tj|}t|tsttt|}|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)sysmodules isinstancerwrr r)r/rr&r%r{r'r'r(r8s   rc CsLtj|j}t|tt|tddt|j D|j |j didddS)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 css |] \}}|dur|VqdSrgr')r<_Z lineNumberr'r'r( ls z$warnAboutFunction..__warningregistry__N)categoryfilenamelinenor{registrymodule_globals) rrr"rrZr getabsfilemaxr __code__r __globals__ setdefault)Zoffenderr5ZoffenderModuler'r'r(warnAboutFunctionSs   rcCsi}t|jt|}|jduri}||j<|dkr0|jdur$td|t|jd||j<t|j|D]\}}|||<q6|D]#\}}||jvrY||vrTtd|||<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} NrToo many arguments.Already passed. no such param)rBrPkeywordsvarargs TypeErrorzipitems)Zargspec positionalkeywordrlZunpassedrRr%rvr'r'r(_passedArgSpecws&       rc Cshi}d}d}t|jD]q\}\}}|jtjjkr+||d||<t||d}q |jtjjkr9i}||<q |jtjj tjj fvrU|t|krT||||<|d7}q |jtjj krt||vrs|j tjj krntd||j ||<q td|d|jt||krtd|D]$\}} ||jvr||vrtd| ||<q|dur| ||<qtd |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} Nrr7zmissing keyword arg 'z' parameter is invalid kind: rrr) enumerate parametersrkindr ParameterVAR_POSITIONALrB VAR_KEYWORDPOSITIONAL_OR_KEYWORDPOSITIONAL_ONLY KEYWORD_ONLYdefaultemptyrkeys) signaturerrrlrRZ numPositionalnr%paramrvr'r'r(_passedSignaturesF      rcsfdd}|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. cs,tttfdd}|S)NcsN||}D]\}}||vr||vrtd||tfq|i|S)Nz5The %r and %r arguments to %s are mutually exclusive.)rr))rPrR argumentsthisthat)_passed argumentPairsspecwrappeer'r(wrappeds   z=_mutuallyExclusiveArguments..wrapper..wrapped)rrrr )rrr)rrrr(wrappers  z,_mutuallyExclusiveArguments..wrapperNr')rrr'rr(_mutuallyExclusiveArgumentss r_Tc.)boundr%r} Optional[str]Callable[[_Tc], _Tc]csdfdd }|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 rrrLcstddtddt}r!|dt}|d7}tj}|vrI|jtj j krIt | fdd}nfd d}t tt|}t|||S) NzThe z parameter to r+z'The {!r} parameter was deprecated in {}r.rcs0t|ks |vrttdd|i|SrU)rBrrZr[)r%parameterIndexr5rr'r(checkDeprecatedParameter3szMdeprecatedKeywordParameter..wrapper..checkDeprecatedParametercs$|vr ttdd|i|SrUrYr[)r%r5rr'r(r:s)r6r)r4rr-rrrrrrlistindexrrr rJ)rr0paramsrZ decoratedr%r,r/)rr5rr(rs.  z+deprecatedKeywordParameter..wrapperN)rrrLrr')r/r%r,rr'rr(r s&r rg)NN)r/rr,rKrLrM)r/rr%r}r,rrLr)6r@ __future__r__all__rrdisr functoolsr typesr typingrrrrrrwarningsrr incrementalrrZtyping_extensionsrrrr3r)r"rrr-r1r6rrJrrrrrorwrrrrrrrrr r'r'r'r(sT M         # * C P/$*<&