˔j\dZddlZddlZddlZddlZddlZddlmZmZddl m Z m Z m Z m Z mZddlmZGddZeZd Zd Zd Zd!d ZGddeZd!dZdZdZefeddZdZejdZdddZdddZ d"ddddZ!d"ddddZ"ddd Z#dS)#z=Utilities for monkey patching and wrapping object attributes.N)BaseObjectProxyFunctionWrapper)PathResolutionErrorTargetModuleNotFoundErrorWrapperChainTooDeepErrorWrapperNotFoundErrorWrapperNotOutermostError)register_post_import_hookc2eZdZdZdZfdZdZdZxZS) _MissingTypezThe type of the MISSING sentinel, which marks the absence of a value or attribute definition where None is itself meaningful.Ncl|j&t||_|jSN) _instancesuper__new__)cls __class__s ;C:\Projects\DSCons\.venv\Lib\site-packages\wrapt/patches.pyrz_MissingType.__new__ s* = !GGOOC00CM}cdS)Nzselfs r__repr__z_MissingType.__repr__%s  rctdfS)Nr)r rs r __reduce__z_MissingType.__reduce__(sb!!r) __name__ __module__ __qualname____doc__rrrr __classcell__rs@rr r si@@I !!!"""""""rr cNttr> tjn(#t$r}t dd|d}~wwxYw}d}|d}fd}|||}|ddD]}|}|||}|||fS)a Resolves the dotted path supplied as `name` to an attribute on a target object. The `target` can be a module, class, or instance of a class. If the `target` argument is a string, it is assumed to be the name of a module, which will be imported if necessary and then used as the target object. Returns a tuple containing the parent object holding the attribute lookup resolved to, the attribute name (path prefix removed if present), and the original attribute value. If the module cannot be imported, raises `TargetModuleNotFoundError`, and if the attribute path cannot be resolved, raises `PathResolutionError`, in both cases with the original exception preserved as the `__cause__` attribute. zunable to import module z while resolving the target for N.rc B tj|rOtj|D]*}|t|vrt||cS+t ||St ||S#t $r}t d|dd|d}~wwxYw)Nzunable to resolve attribute z in path z on )inspectisclassgetmrovarsgetattrAttributeErrorr)parent attributerexcnametargets rlookup_attributez&resolve_path..lookup_attributebs v&& 2">&1166C DII--#Cyy3333.#69555vy111   %*y****%**  s$AA6A6&A66 BBBr) isinstancestr importlib import_moduleModuleNotFoundErrorrsplit)r1r0r/r-pathr.r2originals`` r resolve_pathr;3s&#  ,V44FF"   ++6++"&++   F ::c??DQI   22H!""X77 ##FI66 Ix ((s. AAAct||\}}}tj|rtj|}nJtj|r|f}n2|ft tjt |z}|D]+} |t|vr|||fcS#t$rY(wxYwtd|d|d)a Sibling of the `resolve_path()` function, resolving the dotted path supplied as `name` on a target object in the same way and returning a tuple of the same shape, with one difference: the first element is the object whose `__dict__` actually defines the attribute, rather than the object the path resolved to. The two answer different questions. `resolve_path()` answers where to write so that lookups through the named object are affected, which is the correct location for installing a wrapper, and shadowing an inherited definition is legitimate there. `resolve_owner()` answers where the attribute physically lives, which is the correct location for removing a wrapper, since restoring anywhere other than the defining location would leave a shadowing copy behind. For a class target the owner is the defining class found by walking the MRO, for an instance target it is the instance itself if the attribute is in its `__dict__` and otherwise the defining class, and for a module target it is the module. For dotted paths the owner logic applies to the final segment only. An attribute served dynamically, such as by a module level or metaclass `__getattr__`, exists in no `__dict__`, and rather than guess, `PathResolutionError` is raised, where `resolve_path()` would return the value happily. Failures resolving the path itself raise exactly as for `resolve_path()`. z attribute z of zb is not defined in any __dict__; it is served dynamically, so there is no owning location to patch) r;r'r(r)ismoduletupletyper* TypeErrorr)r1r0r-r.r: candidates candidates r resolve_ownerrC{s2#/vt"<"<FIxvE^F++  & ! !EY Yw~d6ll'C'C!D!DD   DOO++!9h7777,    H   Y  f     s B&& B32B3c(t|||dS)zv Convenience function for applying a patch to an attribute. This maps to the standard setattr() function. N)setattr)r-r. replacements r apply_patchrGs  FI{+++++rrc |i}t||\}}} |t|v}n#t$rd}YnwxYw||g|Ri|} | d|n#t$rYnwxYwt ||| | S)a Wraps an object which is the attribute of a target object with a wrapper object created by the `factory` function. The `target` can be a module, class, or instance of a class. In the special case of `target` being a string, it is assumed to be the name of a module, with the module being imported if necessary and then used as the target object. The `name` is a string representing the dotted path to the attribute. The `factory` function should accept the original object and may accept additional positional and keyword arguments which will be set by unpacking input arguments using `*args` and `**kwargs` calling conventions. The factory function should return a new object that will replace the original object, and should ordinarily be a `BaseObjectProxy` subclass or return an instance of one, so that the replacement can carry the installation details which `unwrap_object()` later relies upon to restore things faithfully. NF"__wrapt_wrap_object_created_slot__)r;r*r@__self_setattr__r,rG) r1r0factoryargskwargsr-r.r:createdwrappers r wrap_objectrPs"~".vt"<"<FIx4<</ gh000000G   !EwOOOO       7+++ Ns, ;; A"" A/.A/c8eZdZdZdfd Zd dZdZdZxZS) AttributeWrapperamA descriptor that intercepts access to an instance attribute to apply a wrapper factory. The descriptor is an object proxy whose wrapped object is whatever previously occupied the class attribute, or the MISSING sentinel when nothing did, so stacked applications compose and a prior descriptor keeps executing its own logic beneath the interception.rNctt||||_||_||_||ni|_dSr)rrR__init___self_attribute _self_factory _self_args _self_kwargs)rwrappedr.rKrLrMrs rrTzAttributeWrapper.__init__sP %%..w777($&,&8FFbrc||S|j}t|}t|dr7t|dst|dr|||}n|j|jvr|j|j}n^t|dr|||}n7|t ur|}n+tt|jd|j|j |g|j Ri|j S)N__get____set__ __delete__ object has no attribute ) __wrapped__r?hasattrr[rU__dict__MISSINGr,rrVrWrX)rinstanceownerprior prior_typevalues rr[zAttributeWrapper.__get__s/  K %[[ :y ) )  J * * .5j,.O.O MM(E22EE  !X%6 6 6%d&:;EE Z + + MM(E22EE ' ! !EE >>*,,',,  "t!%O$/OOOT=NOOOrc|j}tt|dr|||dS||j|j<dS)Nr\)r_r`r?r\rarU)rrcrgres rr\zAttributeWrapper.__set__%sT   4;; * * < MM(E * * * * *6;H d2 3 3 3rc |j}tt|dr||dS |j|j=dS#t $r-tt|jd|jdwxYw)Nr]r^) r_r`r?r]rarUKeyErrorr,r)rrcres rr]zAttributeWrapper.__delete__1s  4;; - -    X & & & & &  %d&:;;;   $H~~.00+00 s A 7BrNr) rrr r!rTr[r\r]r"r#s@rrRrRsJJ AAAAAA"P"P"P"PH < < <rrRc|i}|dd\}}t||d}t||t}t |||||} t ||| | S)av Wraps an object which is the attribute of a class instance with a wrapper object created by the `factory` function. It does this by patching the class, not the instance, with a descriptor that intercepts access to the instance attribute. The `module` can be a module, class, or instance of a class. In the special case of `module` being a string, it is assumed to be the name of a module, with the module being imported if necessary and then used as the target object. The `name` is a string representing the dotted path to the attribute. The `factory` function should accept the original object and may accept additional positional and keyword arguments which will be set by unpacking input arguments using `*args` and `**kwargs` calling conventions. The factory function should return a new object that will replace the original object. Returns the `AttributeWrapper` descriptor installed on the class, which wraps whatever previously occupied the class attribute, or the `MISSING` sentinel when nothing did, so repeated applications compose rather than replace one another. Nr%r)rsplitr;r*getrbrRrG) moduler0rKrLrMr9r.r-rerOs rwrap_object_attributerqDs&~kk#q))OD) &$ ' ' *F LL  Y 0 0Eui$GGG 7+++ Nrc.fd}t|S)a Creates a decorator for wrapping a function with a `wrapper` function. The decorator which is returned may also be applied to any other callable objects such as lambda functions, methods, classmethods, and staticmethods, or objects which implement the `__call__()` method. The `wrapper` function should accept the `wrapped` function, `instance`, `args`, and `kwargs`, arguments and return the result of calling the wrapped function or some other appropriate value. c|d}|}nNtj|rd|}n#|t|}t ||S)Nrr'r(r[r?r)rYrcrLrMtarget_wrappedtarget_wrapperrOs r_wrapperz"function_wrapper.._wrapperssja  $NN _X & & G$__T8<>>rr)rOrws` rfunction_wrapperryhs.????? 7H - --rc:t|trm|drX|dd}|tjvr(t tj|t fSfd}t||dSt |t fS)a Wraps a function which is the attribute of a target object with a `wrapper` function. The `target` can be a module, class, or instance of a class. In the special case of `target` being a string, it is assumed to be the name of a module, with the module being imported if necessary. If the `target` is a string with a trailing ``?``, the wrapping will be deferred until the module is imported. If the module is already imported, the wrapping will be applied immediately. The `name` is a string representing the dotted path to the attribute. The `wrapper` function should accept the `wrapped` function, `instance`, `args`, and `kwargs` arguments, and would return the result of calling the wrapped attribute or some other appropriate value. Returns the wrapped target function if the wrapping was applied immediately, or ``None`` if the wrapping was deferred. ?Nc8t|tfdSrrPr)rpr0rOs rcallbackz'wrap_function_wrapper..callbacks oz B B B B Brr3r4endswithsysmodulesrPrr )r1r0rOrs `` rwrap_function_wrapperrs &# 6??3#7#7  S[ s{62D/G:VV V C C C C C C "(F333t vt_wj A AAr)enabledc|tur6turtdtjdtd|turdfd}|S)at Creates a decorator which can be applied to a wrapper function, where the wrapper function will be used to wrap a function which is the attribute of a target object. The decorator returns the original wrapper function. The `target` can be a module, class, or instance of a class. In the special case of `target` being a string, it is assumed to be the name of a module, with the module being imported if necessary. If the `target` is a string with a trailing ``?``, the wrapping will be deferred until the module is imported. If the module is already imported, the wrapping will be applied immediately. The `name` is a string representing the dotted path to the attribute. The `enabled` argument is keyword only and can be a boolean or a callable that returns a boolean. When a callable is provided, it will be called each time the wrapper is invoked to determine if the wrapper function should be executed or whether the wrapped function should be called directly. If `enabled` is not provided, or an explicit value of `None` is supplied, the wrapper is enabled by default. zCpatch_function_wrapper() got multiple values for argument 'enabled'zPassing 'enabled' positionally to patch_function_wrapper() is deprecated and will be an error in a future version of wrapt; pass it as a keyword argument.rm) stacklevelNcHttrqdr\dd}|tjvr+t tj|t fSfd}t||St t fS)Nr{r|c:t|tfdSrr~)rprr0rOs rrz:patch_function_wrapper.._wrapper..callbacks"FD/GW;MNNNNNrr)rO_targetrrr0r1s` rrwz(patch_function_wrapper.._wrappers fc " " vs';'; SbSkG#+%%K($'7AS O O O O O O O &h 8 8 8NFD/GW3EFFFr)rbr@warningswarnDeprecationWarning)r1r0_enabledrrws`` ` rpatch_function_wrapperrs&w ' ! !X    -      '& Orcfd}|S)aQCreates a decorator that patches a target function with a wrapper function, but only for the duration of the call that the decorator was applied to. The `target` can be a module, class, or instance of a class. In the special case of `target` being a string, it is assumed to be the name of a module, with the module being imported if necessary. The `name` is a string representing the dotted path to the attribute. The patch is applied to the object the path resolves to, so patching an attribute reached through inheritance, or through an instance, only affects lookups made through that object and not the class where the attribute is defined. In that case the temporary attribute which shadowed the inherited definition is removed again when the call exits, restoring the original lookup. The temporary wrapper is removed using `unwrap_object()`, so if code called within the scope of the patch wrapped over the top of the temporary wrapper with a wrapt wrapper and left it there, the temporary wrapper is spliced out beneath it, with the other wrapper left in place. If something removed or replaced the temporary wrapper during the call, `WrapperNotFoundError` is raised, and if what was applied on top of it is not a wrapt wrapper and so cannot be spliced past, `WrapperNotOutermostError` is raised. Both are loud deliberately, as they indicate the surrounding code, typically a test harness, is not managing its own patches properly, and the leaked patch state would otherwise surface as hard to diagnose failures later. c4fd}t|S)Nc|d}| nNtj|r d|n# |t|fd}t ||S)Nrcttf} ||i|t|S#t|wxYwr)rPr unwrap_object)rYrcrLrMrFr0r1rvs r_executezRtransient_function_wrapper.._decorator.._wrapper.._executesd*D/N3D ="7D3F33!&$ <<<._decorator.._wrappers!!WN!(** K!(x!@!@!(4>>!J!J = = = = = = =,#>8<< ._decorators: = = = = = = =Bw111rr)r1r0rs`` rtransient_function_wrapperrs+4"2"2"2"2"2"2H rc#Kt|tr$|drtdt |||} dVt |||dS#t |||wxYw)aReturns a context manager which patches a target function with a wrapper function for the duration of a with statement, the block scoped counterpart of the `transient_function_wrapper()` decorator. The arguments take the same form as for `wrap_function_wrapper()`: the `target` can be a module, class, or instance of a class, or the name of a module as a string, the `name` is a string representing the dotted path to the attribute, and the `wrapper` function should accept the `wrapped`, `instance`, `args`, and `kwargs` arguments. The deferred form of the `target` with a trailing ``?`` is not supported, since the patch must be applied at the point the with statement is entered. The context manager yields nothing, is single use, and removes the wrapper using `unwrap_object()` when the block exits, with the same behaviour as `transient_function_wrapper()` when something interfered with the patch during the block: a wrapt wrapper applied on top of the temporary wrapper and left there is tolerated, with the temporary wrapper spliced out beneath it, while the temporary wrapper having been removed or replaced raises `WrapperNotFoundError`, and a non wrapt wrapper left applied on top raises `WrapperNotOutermostError`. r{zbdeferred wrapping using a target with a trailing '?' cannot be used with scoped_function_wrapper()N)r3r4r ValueErrorrr)r1r0rOhandles rscoped_function_wrapperrs,&# 6??3#7#7  5   #64 9 9F, fdF+++++ fdF++++s A%%A8@limitc#PKg}t}|} t||vrdSt||krtd|d|d|||t||V |j}n#t$rYdSwxYw)aa Returns an iterator yielding `obj`, then each successive object found by following the `__wrapped__` attribute, outermost wrapper first. The final item yielded is the innermost object of the chain, which is not itself a wrapper. Traversal ends cleanly at an object with no `__wrapped__` attribute, or upon returning to an object already seen. If the `limit` on the number of items yielded is reached with a further chain link still pending, `WrapperChainTooDeepError` is raised, as a truncated scan would otherwise be indistinguishable from a complete one. A chain of exactly `limit` items which ends naturally is not an error. Note that reading `__wrapped__` from a lazy object proxy will cause it to materialize, and an exception raised by a broken proxy or a lazy object factory will propagate to the caller. TNzwrapper chain of z exceeded z levels)setidlenrappendaddr_r,)objrseenseen_idscurrents r wrapper_chainrDs. DuuHG g;;( " " F t99  *CCCCUCCC  G R[[!!!  )GG    FF !sB B$#B$c2|}t||D]}|S)a| Returns the innermost object of the chain of wrappers followed from `obj` by the `wrapper_chain()` function, or `obj` itself when it is not wrapped. Shares the full contract of `wrapper_chain()`, including raising `WrapperChainTooDeepError` when the scan is indeterminate, rather than returning a mid chain wrapper as if it were the innermost object. r)r)rrresults r unwrappedrts-F5111   Mr predicaterc||tdt||D]}|||ur | ||s|cSdS)a- Scans the chain of wrappers followed from `obj` by the `wrapper_chain()` function for a specific wrapper and returns it, or `None` when it is not present. The `handle` argument is the wrapper object to look for, as returned by the wrap functions when the wrapper was installed, and is matched by object identity only, never equality, which proxies delegate to the wrapped object. Alternatively a `predicate` function may be supplied, in which case the first chain entry for which it returns true is returned, and is itself usable as a handle thereafter. When both are supplied, both must match. At least one of the two must be supplied, since testing for the mere presence of any wrapper is fragile: were the target library to adopt wrapt for its own purposes, such a test would wrongly conclude a wrapper of yours was installed. Shares the full contract of `wrapper_chain()`, including raising `WrapperChainTooDeepError` when the scan is indeterminate, rather than returning `None` as a false negative. Nz7find_wrapper() requires a wrapper handle or a predicater)r@r)rrrrentrys r find_wrapperrsz&~)+ E   s%000  %v"5"5   5)9)9  4rc,t||||duS)a% Boolean convenience form of the `find_wrapper()` function, returning whether the wrapper is present in the chain of wrappers followed from `obj`. With a `handle`, this answers whether the wrapper it was returned for when installed is still in place, which is the check to run when a third party may have replaced the attribute wholesale. Shares the full contract of `find_wrapper()`, including raising `WrapperChainTooDeepError` when the scan is indeterminate, rather than returning `False` as a false negative. rN)r)rrrrs r is_wrapped_byrs  Vy F F Fd RRrF) missing_okc D t||\}}n#t$r} t||d}n#t$rd}YnwxYw|z unwrap_object..s4  "eU%5..E....  rrc6g|]}t|jSr)r?r)rrs r z!unwrap_object..s!HHHeT%[[)HHHrz : wrapped by rIc3dK|]*}t|vt|V+dSr)r*)rrr.s rrz unwrap_object..GsK  S ))S )$))))  r)rCrr;rr r?rr r_r,listrnext enumerate issubclassrrbdelattr __self_dict__rorGr'r(r))r1r0rrrdrr/restoredchainposition neighbouraboverN inheritedr.rs @@rrrsN$1&$$?$?!y''  "64003GG"   GGG   <#@#@#L*9f!69999"999    44444" ?f ? ?f ? ? ? ?   -4 & ) )E  (HH   EEE    }  4" ?f ? ?f ? ? ? ?    G]7++,,     &/&6&6     (Q,' $y//?;; HHuYhY7GHHHE*9e!59999"991699  !)  7y!!! %))*NOO   4 E9 % % % % y( 3 3 3 u     ">%004         E9 % % %Ly(+++ LsZ B1;B, A B, A  AB,B,,B1C CCG55 HHrkr)$r! contextlibr5r'rr __wrapt__rr exceptionsrrrr r importerr r rbr;rCrGrPrRrqryrrrcontextmanagerrrrrrrrrrrsCC 777777770/////""""""""( ,.. E)E)E)P---`,,,1111~NNNNNNNNbH...0BBB>3:7g77777t>>>B  , , ,R!#-----`$BD SR S S S S S7<\\\\\\\r