+ joRt^RIHt.R,Ot^RIt^RIt^RIHt^RIH t ^RI H t ^RI H t HtHtHtHtHt^RIHsHt^RIHtHt^R I Ht]!R 4t]!R 4tR tR tR]nR]nR]n Rt!R-Rlt"R.Rlt#R.Rlt$Rt%R-RRllt&R-RRllt'Rt(Rt)!RR4t*!RR4t+!RR 4t,R!t-R"t.R#t/R$t0R%t1R&t2]!R']R(] 3,R)7t3R-R*R+llt4R#)/a 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. ) annotationsN)findlinestartswraps) ModuleType)AnyCallableDictOptionalTypeVarcast)warn warn_explicit)VersiongetVersionString) ParamSpec_P_Rz&%(fqpn)s was deprecated in %(version)sc^VPp\P!V4'g\P !V4'dVP pV RV 2#\P!V4'dVP RVP 2#V# \dTPpLi;i)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& :/usr/lib/python3/dist-packages/twisted/python/deprecate.py_fullyQualifiedNamer"tssw11#66^^ Qtf%%   #  ..!3#3#3"455 K ||s BB,+B,ztwisted.python.reflectfullyQualifiedNamecF\V4'd \V4pRV R2#)z 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!_getReplacementStringr(s( )+6  X ..c`R\V4 2pV'dV R\V4 2pVR,#)ax 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'docs&& r!_getDeprecationDocstringr.s; +G45 6CR-k:;< 9r)cVf\pVRVR\V4/,pV'dRPV\V44pV#)a 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} fqpnr,z{}; {})DEPRECATION_WARNING_FORMATrformatr()r0r,r2r' warningStrings&&&& r!_getDeprecationWarningStringr4sK2~+fdI7G7PQQM  0=  r)c.\\V4WV4#)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 } 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} )r4r") callableThingr,r2r's&&&&r!getDeprecationWarningStringr7s2 (M*G[ r)cVP'dVPP4pM.p\V4^8XdVPV4M\V4^8XdVP RVR.4MjVR,pRpVP 4'gVP 4pVP RWA,V.4VUu.uFqUPR4NK ppRPV4VnR#uupi)a^ 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.   N) __doc__ splitlineslenappendextendstrippoplstripjoin) thingWithDoc textToAppenddocstringLinestrailerspacesls&& r!_appendToDocstringrLs%--88: >al+ ^  !r<45 $}}#'')Fr6#8&AB1?@A((3-@99^4LAsC9c$V^8dQhRRRRRR/#r,rr'z"str | Callable[..., object] | Nonereturnz.Callable[[Callable[_P, _R]], Callable[_P, _R]])r2s"r! __annotate__rRs$& & & #E& 3& r)caaRVV3RllpV#)ag 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 V^8dQhRRRR/#)rOfunctionzCallable[_P, _R]rPrQ)r2s"r!rR deprecated..__annotate__#s""'7"deprecated..deprecationDecorator..__annotate__,s! - -g - -r -r)c8<\S\^R7S!V/VB#rO stacklevelr DeprecationWarningrYrZrUr3s*,r!deprecatedFunctionDdeprecated..deprecationDecorator..deprecatedFunction+  2q AT,V, ,r))r7rrLr.deprecatedVersion)rUrcr3r'r,sf @r!deprecationDecorator(deprecated..deprecationDecorator#s]4 gt[  x - -  -   8+ N 07,!!r)rQ)r,r'rgsff r! deprecatedris&""& r)c$V^8dQhRRRRRR/#rNrQ)r2s"r!rRrR9s)@ @ @ #E@ 3@ r)c:aaa!RR\4oVVV3RlpV#)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&]tRtRtRtRtRtRtR#)/deprecatedProperty.._DeprecatedPropertyiRzA Extension of the build-in property to allow deprecated setters. c 4aa\S4VV3Rl4pV#)cL<\SP\^R7S!V/VB#r])r r3ra)rYrZrUselfs*,r!rc^deprecatedProperty.._DeprecatedProperty._deprecatedWrapper..deprecatedFunctionXs,&&&   000r)r)rprUrcsff r!_deprecatedWrapperBdeprecatedProperty.._DeprecatedProperty._deprecatedWrapperWs! 8_ 1 1& %r)c J\PWPV44#N)propertysetterrr)rprUs&&r!rw6deprecatedProperty.._DeprecatedProperty.settercs??4)@)@)JK Kr)rQN)rrr__firstlineno__r=rrrw__static_attributes__rQr)r!_DeprecatedPropertyrmRs  & Lr)r{c<aa\SSRS4o\S4VV3Rl4p\V\SS44SVnS!V4pSVnV#)Nc8<\S\^R7S!V/VB#r]r`rbs*,r!rcLdeprecatedProperty..deprecationDecorator..deprecatedFunctionkrer))r7rrLr.rfr3)rUrcresultr3r{r'r,sf @r!rg0deprecatedProperty..deprecationDecoratorfsh3 gt[  x -  -   8+ N 07,$%78, r))rv)r,r'rgr{sff @r!deprecatedPropertyr9s2LhL(& r)c\#)zJ Return the warning method currently used to record deprecation warnings. r rQr)r!getWarningMethodr|s  Kr)c VsR#)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!setWarningMethodrs  Dr)c,]tRtRtRtRtRtRtRtR#)_InternalStateiz 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 4\PVRV4R#)proxyN)object __setattr__)rprs&&r!__init___InternalState.__init__s4%0r)c V\P\PVR4V4#r)r__getattribute__)rprs&&r!r_InternalState.__getattribute__s"&&v'>'>tW'MtTTr)c V\P\PVR4W4#r)rrr)rprvalues&&&r!r_InternalState.__setattr__s"!!&"9"9$"H$VVr)rQN) rrrryr=rrrrzrQr)r!rrs1UWr)rc8]tRtRtRtRtRRltRtRtRt R #) _ModuleProxyiaX 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 D\V4pWn/VnRVnR#)FN)r_module_deprecatedAttributes _lastWasPath)rpmodulestates&& r!r_ModuleProxy.__init__s!t$ &(#"r)cV^8dQhRR/#)rOrPstrrQ)r2s"r!rR_ModuleProxy.__annotate__sCC#Cr)c f\V4pR\V4P RVP: R2#)zi Get a string containing the type of the module proxy and a representation of the wrapped module object. )rtyperr)rprs& r!__repr___ModuleProxy.__repr__s3 t$4:&&'x /@BBr)c V\V4pRVn\VPW4R#)z0 Set an attribute on the wrapped module object. FN)rrsetattrr)rprrrs&&& r!r_ModuleProxy.__setattr__s$t$" t+r)c \V4pVP'dRpMVPPV4pVeVP4pM\ VP V4pVR8Xd RVnV#RVnV#)a 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)rprrdeprecatedAttributers&& r!r_ModuleProxy.__getattribute__st$    "& "'"="="A"A$"G   *(++-EEMM40E : !%E  "'E  r)rQN) rrrryr=rrrrrzrQr)r!rrs6# C,r)rc&]tRtRtRtRtRtRtR#)_DeprecatedAttributeia 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 tWnW nVPR,V,VnW0nW@nR#)z' Initialise a deprecated name wrapper. rN)rrr0r,message)rprrr,rs&&&&&r!r_DeprecatedAttribute.__init__s-  OOc)D0   r)c \VPVP4p\VPVP \ R,VP,4p\V\^R7V#)zE Get the underlying attribute value and issue a deprecation warning. z: r^) rrrr4r0r,r1rr ra)rprrs& r!r_DeprecatedAttribute.getsTdmm4. IIt||%?$%F%U  W(Q7 r))rr0rrr,N)rrrryr=rrrzrQr)r!rrs( r)rc~\PVR4p\WAW#4p\PVR4pWVV&R#)al 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)rrr,rrattrrs&&&& r!_deprecateAttributer s@ %%eY7G w @D#33E;RS"&$r)c\PV,p\V\4'g-\ \ \V44pV\PV&\ WCW4R#)a 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 isinstancerr rr)r,rr rrs&&&& r!deprecatedModuleAttributer8sH&[[ $F fl + +j,v"67"( Jg7r)c *\PVP,p\V\\ P !V4\R\VP444VPVPPR/4RR7R#)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 c36"TFwrVfK VxK R#5irurQ).0_ lineNumbers& r! $warnAboutFunction..ls !B  J!Bs __warningregistry__N)categoryfilenamelinenorregistrymodule_globals) rrrrrar getabsfilemaxr__code__r __globals__ setdefault)offenderr3offenderModules&& r!warnAboutFunctionrSsy([[!4!45N###N3 !/0A0A!B  &&%%001FK r)c/p\VP4\V4, pVPe/;qSVP&V^8d>VPf \ R4hV\VP4RW0P&\ VPV4F wrgWsV&K VP 4FJwrgW`P9dWc9d \ R4hWsV&K,VPeVXV&KA\ R4h V#)ax 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} NToo many arguments.Already passed. no such param)r?rYkeywordsvarargs TypeErrorzipitems)argspec positionalkeywordrunpassedrZrrs&&& r!_passedArgSpecrws&!#F7<< 3z?2H#,..(()!| ?? "12 2&0W\\1B1D&EF?? #7<<4 t 5}}  << ~ 122 4L    ) F4LO, ,' Mr)cX/pRp^p\VPP44EFwpwrxVP\P P 8Xd!WRW7&\W7,4^,pKRVP\P P8Xd /;qCV&KVP\P P\P P39d(V\V48dW,W7&V^, pKKVP\P P8XdRWr9dIVP\P P8Xd\RV 24hVPW7&EKdEKg\RV RVP 24h \V4V8d \R4hVP4FMwryWpPP49dWs9d \R4hWV&K:VeWV&KD\R4h V#)at 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} Nzmissing keyword arg 'z' parameter is invalid kind: rrr) enumerate parametersrkindr ParameterVAR_POSITIONALr? VAR_KEYWORDPOSITIONAL_OR_KEYWORDPOSITIONAL_ONLY KEYWORD_ONLYdefaultemptyrkeys) signaturerrrrZ numPositionalnrparamrs &&& r!_passedSignaturers&F FM%i&:&:&@&@&BC=D ::**99 9%b>FL -1M ZZ7,,88 8$& &FD\ ZZ    3 3    - -  3z?")} " #ZZ7,,99 9"==G$5$5$;$;;#&:4&$ABB#(==FL # av%B5::,OP P-D0 :&-..}}  '',,. .~ 122 4L   4LO, ,' Mr)caV3RlpV#)ak 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. ct<aaa\P!S4o\o\S4VVVV3Rl4pV#)c <S!SW4pSF4wr4W29gK WB9gK\RV: RV: R\S4: R24h S!V/VB#)The z and z arguments to z are mutually exclusive.)rr") rYrZ argumentsthisthat_passed argumentPairsspecwrappees *, r!wrapped=_mutuallyExclusiveArguments..wrapper..wrappedsXd3I+ $):#':7'CE, D+F+ +r))rrrr)rrrrrsf @@r!wrapper,_mutuallyExclusiveArguments..wrappers5  )" w ,  ,r)rQ)rrsf r!_mutuallyExclusiveArgumentsrs$" Nr)_Tc.)boundc(V^8dQhRRRRRRRR/#) rOr,rrrr'z Optional[str]rPzCallable[[_Tc], _Tc]rQ)r2s"r!rRrRs,== ==.;==r)c"aaaRVVV3RllpV#)a? 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 c V^8dQhRRRR/#)rOrrrPrQ)r2s"r!rR0deprecatedKeywordParameter..__annotate__s$$$$r)c.<aaa\RS: R\S4 2S SR7oRPS\S 44pS'dVR,\ S4,pVR, p\ P !S4PpSV9dUVS,P\ PP8Xd%\V4PS4oVVVV3RlpMVVV3Rlp\\\S4!V44p\!WA4V#)rz parameter to r&z'The {!r} parameter was deprecated in {}r+rcf<\V4S8gSV9d\S\^R7S!V/VB#r])r?r ra)rYrZrparameterIndexr3rs*,r!checkDeprecatedParameterMdeprecatedKeywordParameter..wrapper..checkDeprecatedParameter3s2t9~-(:qI///r)cF<SV9d\S\^R7S!V/VB#r]r`)rYrZrr3rs*,r!rr:s'6>(:qI///r))r4r"r2rr(rrrrrrlistindexr rrrL) rr-paramsr decoratedrr3rr'r,s f @@r!r+deprecatedKeywordParameter..wrappers44(.)>  W %  *4[AAC s ""7+66 FNt !!W%6%6%L%LL!&\//5N 0 0 0 eGn-EFG 9*r)rQ)r,rr'rsfff r!deprecatedKeywordParameterrs.$$L Nr))rirr7rrrrru)NN)5r= __future__r__all__rrdisr functoolsrtypesrtypingrrr r r r warningsr r incrementalrrrrrr1r"rrrr(r.r4r7rLrirrrrrrrrrrrrrrrQr)r!r!s  LZ#  ??(1t_ T]E,":3#7  /( F<5:& R@ FWW&MM`,,^'086!H'T9x#Le8CH-.==r)