tfFodZddlmZgdZddlZddlZddlmZddlm Z ddl m Z ddl m Z mZmZmZmZmZdd lmamZdd lmZmZdd lmZed Zed ZdZdZde_de_ de_!dZ"d5dZ#d6dZ$d6dZ%dZ& d5d7dZ'd5dZ(dZ)d Z*Gd!d"Z+Gd#d$Z,Gd%d&Z-d'Z.d(Z/d)Z0d*Z1d+Z2d,Z3ed-ed.e f/Z4 d5d8d4Z5dS)9a 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)sc |j}n#t$r |j}YnwxYwtj|stj|r|j}|d|Stj|r|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}. .) __qualname__AttributeError__name__inspectisclass isfunction __module__ismethod)objname moduleNames W/var/www/surfInsights/venv3-11/lib/python3.11/site-packages/twisted/python/deprecate.py_fullyQualifiedNamer*ts |s6w1#666^ %%t%%%  #  6.553#3555 Ks  ztwisted.python.reflectfullyQualifiedNamecJt|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 instead)callabler* replacements r)_getReplacementStringr0s2 7)+66 . . . ..c\dt|}|r|dt|}|dzS)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)rr0)versionr/docs r)_getDeprecationDocstringr6sH 7+G44 6 6C=<<-k::<< 9r1c|t}||t|dz}|r#d|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)fqpnr4z{}; {})DEPRECATION_WARNING_FORMATrformatr0)r8r4r:r/ warningStrings r)_getDeprecationWarningStringr<sZ2~+d7G7P7PQQQM   0==   r1c@tt||||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} )r<r*) callableThingr4r:r/s r)rrs'2 (M**GV[  r1c|jr|j}ng}t|dkr||nt|dkr|d|dgnY|d}d}|s|}|d||z|gd|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. rc8g|]}|dS) )lstrip).0ls r) z&_appendToDocstring.. s"@@@A!((3--@@@r1 N)__doc__ splitlineslenappendextendstrippopjoin) thingWithDoc textToAppenddocstringLinestrailerspacess r)_appendToDocstringrWs%-88:: >al++++ ^   ! !r<45555 $}} *#''))Fr6L#8&ABBB@@@@@99^44Lr1r4rr/"str | Callable[..., object] | Nonereturn.Callable[[Callable[_P, _R]], Callable[_P, _R]]cdfd }|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]rYctdtd fd }t|t|_|S) zA Decorator that marks C{function} as deprecated. Nargs_P.argskwargs _P.kwargsrYrcBttd|i|SN stacklevelrDeprecationWarningr_rar\r;s r)deprecatedFunctionzDdeprecated..deprecationDecorator..deprecatedFunction+.  2q A A A A8T,V,, ,r1)r_r`rarbrYr)rr rWr6deprecatedVersion)r\rkr;r/r4s` @r)deprecationDecoratorz(deprecated..deprecationDecorator#s4 gt[   x - - - - - -  -   8+ N N   07,!!r1)r\r]rYr])r4r/rns`` r)rrs/&"""""""& r1c@Gddtfd}|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 ceZdZdZdZdZdS)/deprecatedProperty.._DeprecatedPropertyzQ Extension of the build-in property to allow deprecated setters. c@tfd}|S)NcLtjtd|i|Srd)rr;ri)r_rar\selfs r)rkz^deprecatedProperty.._DeprecatedProperty._deprecatedWrapper..deprecatedFunctionVs=&&   x0000r1r )rur\rks`` r)_deprecatedWrapperzBdeprecatedProperty.._DeprecatedProperty._deprecatedWrapperUs: 8__ 1 1 1 1 1_ 1& %r1c^t|||SN)propertysetterrv)rur\s r)rzz6deprecatedProperty.._DeprecatedProperty.setteras$??4)@)@)J)JKK Kr1N)r r$rrJrvrzror1r)_DeprecatedPropertyrrPsA   & & & L L L L Lr1r{ctdtfd}t|t|_|}|_|S)NcBttd|i|Srdrhrjs r)rkzLdeprecatedProperty..deprecationDecorator..deprecatedFunctionirlr1)rr rWr6rmr;)r\rkresultr;r{r/r4s` @r)rnz0deprecatedProperty..deprecationDecoratords3 gt[   x - - - - -  -   8+ N N   07,$$%788, r1)ry)r4r/rnr{s`` @r)rr9sb.LLLLLhLLL(& r1ctS)zR Return the warning method currently used to record deprecation warnings. rror1r)rrzs  Kr1c |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. Nr) newMethods r)rrs  DDDr1c$eZdZdZdZdZdZdS)_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>t|d|dSNproxy)object __setattr__)rurs r)__init__z_InternalState.__init__s 4%00000r1cjtt|d|Sr)r__getattribute__)rur's r)rz_InternalState.__getattribute__s(&&v'>'>tW'M'MtTTTr1cltt|d||Sr)rrr)rur'values r)rz_InternalState.__setattr__s+!!&"9"9$"H"H$PUVVVr1N)r r$rrJrrrror1r)rrsS111UUUWWWWWr1rc,eZdZdZdZd dZdZdZdS) _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} cNt|}||_i|_d|_dS)NF)r_module_deprecatedAttributes _lastWasPath)rumodulestates r)rz_ModuleProxy.__init__s,t$$ &(#"r1rYstrc`t|}dt|jd|jdS)z Get a string containing the type of the module proxy and a representation of the wrapped module object. )rtyper r)rurs r)__repr__z_ModuleProxy.__repr__s5 t$$B4::&BB BBBBr1c^t|}d|_t|j||dS)z@ Set an attribute on the wrapped module object. FN)rrsetattrr)rur'rrs r)rz_ModuleProxy.__setattr__s3t$$" tU+++++r1ct|}|jrd}n|j|}||}nt |j|}|dkrd|_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)rrrgetgetattrr)rur'rdeprecatedAttributers r)rz_ModuleProxy.__getattribute__st$$   H"&  "'"="A"A$"G"G   *(++--EEEM400E :  !%E  !&E  r1N)rYr)r r$rrJrrrrror1r)rrsc6### CCCC,,,r1rceZdZdZdZdZdS)_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 cb||_||_|jdz|z|_||_||_dS)z7 Initialise a deprecated name wrapper. rN)rr r8r4message)rurr'r4rs r)rz_DeprecatedAttribute.__init__s7  Oc)D0   r1ct|j|j}t|j|jt dz|jz}t|td|S)zU Get the underlying attribute value and issue a deprecation warning. z: rf) rrr r<r8r4r9rrri)rur~rs r)rz_DeprecatedAttribute.gets[dm44. It|%?$%F%U   W(Q7777 r1N)r r$rrJrrror1r)rrs<(     r1rct|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 rrN)rrr)rr'r4rrattrrs r)_deprecateAttributersV %%eY77G w @ @D#33E;RSS"&$r1ctj|}t|ts1t t 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)sysmodules isinstancerrrr)r4rr(r'rs r)r r 6s_&[ $F fl + +)j,v"6"677"( Jgw77777r1c tj|j}t|tt j|tdt|j D|j |j diddS)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 c3$K|] \}}||V dSrxro)rF_ lineNumbers r) z$warnAboutFunction..js8  :% %%%%  r1__warningregistry__N)categoryfilenamelinenorregistrymodule_globals) rrr$rrir! getabsfilemaxr __code__r __globals__ setdefault)offenderr;offenderModules r)warnAboutFunctionrQs([!45N##N33  !/0A!B!B     &%001FKK      r1ci}t|jt|z }|j ix}||j<|dkr:|jt d|t|jd||j<t |j|D] \}}|||< |D]B\}}||jvr||vrt d|||<'|j|||<4t d|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)rLr_keywordsvarargs TypeErrorzipitems)argspec positionalkeywordr~unpassedrar'rs r)_passedArgSpecrus&!#F7<  3z??2H#,..()!|| ? "122 2&0W\1B1B1D1D&EF7? #7<44 et }}-- e 7<  v~~ 1222 F4LL   ) F4LLO,, , Mr1ci}d}d}t|jD]&\}\}}|jtjjkr&||d||<t||dz}I|jtjjkrix}||<k|jtjj tjj fvr$|t|kr||||<|dz }|jtjj kr<||vr6|j tjj krtd||j ||<td|d|jt||krtd|D]O\}} ||jvr||vrtd| ||<9|| ||<Atd |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: rrr) enumerate parametersrkindr! ParameterVAR_POSITIONALrL VAR_KEYWORDPOSITIONAL_OR_KEYWORDPOSITIONAL_ONLY KEYWORD_ONLYdefaultemptyrkeys) signaturerrr~ra numPositionalnr'paramrs r)_passedSignaturers&F FM%i&:&@&@&B&BCCQQ=D% :*9 9 9%abb>F4Lt --1MM Z7,8 8 8$& &FVD\\ Z   3   -   3z??"")!}t " Z7,9 9 97""=G$5$;;;#$A4$A$ABBB#(=F4LOOO5:OOPP P :&&-...}}-- e 9',,.. . .v~~ 1222 F4LL   F4LLO,, , Mr1cfd}|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~tjttfd}|S)Nc ||}D]3\}}||vr*||vr&td|d|dtd4|i|S)NThe z and z arguments to z are mutually exclusive.)rr*) r_ra argumentsthisthat_passed argumentPairsspecwrappees r)wrappedz=_mutuallyExclusiveArguments..wrapper..wrappedsdF33I+   d9$$):):#)44':7'C'C'C'CE7D+F++ +r1)r!rrr )rrrrrs` @@r)wrapperz,_mutuallyExclusiveArguments..wrappersZ ))" w , , , , , , ,  ,r1ro)rrs` r)_mutuallyExclusiveArgumentsrs#$" Nr1_Tc.)boundr'r Optional[str]Callable[[_Tc], _Tc]cdfd }|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 rrrYc*tddt dt }r|dzt z}|dz }t jj}|vrK|jt j j kr+t| fd}nfd}ttt|}t!|||S) Nrz parameter to r.z'The {!r} parameter was deprecated in {}r3rcpt|ks|vrttd|i|Srd)rLrri)r_rar'parameterIndexr;rs r)checkDeprecatedParameterzMdeprecatedKeywordParameter..wrapper..checkDeprecatedParameter1sGt99~--(:qIIIIw////r1cJ|vrttd|i|Srdrh)r_rar'r;rs r)rzMdeprecatedKeywordParameter..wrapper..checkDeprecatedParameter8s76>>(:qIIIIw////r1)r<r*r:rr0r!rrrrrlistindexrrr rW) rr5paramsr decoratedrr;r'r/r4s ` @@r)rz+deprecatedKeywordParameter..wrappersa4 G4 G G)>  W % %    B*4[AAAC s "7++6 FNNt !W%6%LLL!&\\//55N 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 neGnn-EFFGG 9c***r1)rrrYrro)r4r'r/rs``` r)r r s5.$$$$$$$$L Nr1rx)NN)r4rr/rXrYrZ)r4rr'rr/rrYr)6rJ __future__r__all__r!rdisr functoolsr typesrtypingrrrrrrwarningsrr incrementalrrtyping_extensionsrrrr9r*r$r rr0r6r<rrWrrrrrrrrr rrrrrr ror1r)r s LLZ#"""""    ????????????????((((((((11111111''''''Yt__ WT]]E,":3#7  / / /(    F<555<IM& & & & & R> > > > BWWWWWWWW&MMMMMMMM`,,,,,,,,^'''08886!!!H'''T999x###Lge8CH-...?C=======r1