raWdZdZdZddlZddlmZddlZddlZddl m Z e jZ ejjdkDZGd d eZGd d eZGd deZGddeZdZdZdZdZdZy)z-Small framework for asynchronous programming.z%Sebastian Heinlein )DeferredAlreadyCalledDeferredDeferredExceptiondeferinline_callbacks return_valueNwraps)versionceZdZdZdZy)_DefGen_Returnz5Exception to return a result from an inline callback.c||_yN)value)selfrs 0/usr/lib/python3/dist-packages/defer/__init__.py__init__z_DefGen_Return.__init__Ss  N)__name__ __module__ __qualname____doc__rrrrrQs ?rrceZdZdZy)rz+The Deferred is already running a callback.N)rrrrrrrrrWs5rrc$eZdZdZddZdZdZy)rzAllows to defer exceptions.Nc||_||_||_t|tr|j |_||_y|r|s(t j\|_|_|_yy)aReturn a new DeferredException instance. If type, value and traceback are not specified the infotmation will be retreieved from the last caught exception: >>> try: ... raise Exception("Test") ... except: ... deferred_exc = DeferredException() >>> deferred_exc.raise_exception() Traceback (most recent call last): ... Exception: Test Alternatively you can set the exception manually: >>> exception = Exception("Test 2") >>> deferred_exc = DeferredException(exception) >>> deferred_exc.raise_exception() Traceback (most recent call last): ... Exception: Test 2 N)typer traceback isinstance Exception __class__sysexc_info)rrrr s rrzDeferredException.__init__^sW0  " dI &DIDJU47LLN 1DItz4>#rctr%|jj|j|j |jj|j)zRaise the stored exception.)PY3Krwith_tracebackr rrs rraise_exceptionz!DeferredException.raise_exceptions@ **++DNN; ;))DJJ'66t~~F Frcf|D]}t|j|s|cS|jy)a8Check if the stored exception is a subclass of one of the provided exception classes. If this is the case return the matching exception class. Otherwise raise the stored exception. >>> exc = DeferredException(SystemError()) >>> exc.catch(Exception) # Will catch the exception and return it >>> exc.catch(OSError) # Won't catch and raise the stored exception Traceback (most recent call last): ... SystemError This method can be used in errbacks of a Deferred: >>> def dummy_errback(deferred_exception): ... '''Error handler for OSError''' ... deferred_exception.catch(OSError) ... return "catched" The above errback can handle an OSError: >>> deferred = Deferred() >>> deferred.add_errback(dummy_errback) >>> deferred.errback(OSError()) >>> deferred.result 'catched' But fails to handle a SystemError: >>> deferred2 = Deferred() >>> deferred2.add_errback(dummy_errback) >>> deferred2.errback(SystemError()) >>> deferred2.result #doctest: +ELLIPSIS >>> deferred2.result.value SystemError() N) issubclassrr*)rerrorserrs rcatchzDeferredException.catchs5L C$))S)   r)NNN)rrrrrr*r/rrrrr[s%CBG)rrcLeZdZdZdZ d dZdZdZd dZd dZ d Z d Z y) raThe Deferred allows to chain callbacks. There are two type of callbacks: normal callbacks and errbacks, which handle an exception in a normal callback. The callbacks are processed in pairs consisting of a normal callback and an errback. A normal callback will return its result to the callback of the next pair. If an exception occurs, it will be handled by the errback of the next pair. If an errback doesn't raise an error again, the callback of the next pair will be called with the return value of the errback. Otherwise the exception of the errback will be returned to the errback of the next pair:: CALLBACK1 ERRBACK1 | \ / | result failure result failure | \ / | | \ / | | X | | / \ | | / \ | | / \ | CALLBACK2 ERRBACK2 | \ / | result failure result failure | \ / | | \ / | | X | | / \ | | / \ | | / \ | CALLBACK3 ERRBACK3 cJg|_g|_d|_d|_d|_y)zReturn a new Deferred instance.FN) callbackserrbackscalledpaused_runningr)s rrzDeferred.__init__s%    rNc`t|tjjsJ|&t|tjjsJ|t}|j j ||xsg|xsif|xst|xsg|xsiff|jr|jyy)aAAdd a pair of callables (function or method) to the callback and errback chain. Keyword arguments: callback -- the next chained challback errback -- the next chained errback callback_args -- list of additional arguments for the callback callback_kwargs -- dict of additional arguments for the callback errback_args -- list of additional arguments for the errback errback_kwargs -- dict of additional arguments for the errback In the following example the first callback pairs raises an exception that is catched by the errback of the second one and processed by the third one. >>> def callback(previous): ... '''Return the previous result.''' ... return "Got: %s" % previous >>> def callback_raise(previous): ... '''Fail and raise an exception.''' ... raise Exception("Test") >>> def errback(error): ... '''Recover from an exception.''' ... #error.catch(Exception) ... return "catched" >>> deferred = Deferred() >>> deferred.callback("start") >>> deferred.result 'start' >>> deferred.add_callbacks(callback_raise, errback) >>> deferred.result #doctest: +ELLIPSIS >>> deferred.add_callbacks(callback, errback) >>> deferred.result 'catched' >>> deferred.add_callbacks(callback, errback) >>> deferred.result 'Got: catched' N) r! collectionsabcCallable _passthroughr2appendr4_next)rcallbackerrback callback_argscallback_kwargs errback_argserrback_kwargss r add_callbackszDeferred.add_callbackssT(KOO$<$<===*Wkoo6N6N"OOO ?"G  - 5" / 7B 9!( 9L , 4 . 62 89 : ;; JJL rc6|jt|||y)a~Add a callable (function or method) to the errback chain only. If there isn't any exception the result will be passed through to the callback of the next pair. The first argument is the callable instance followed by any additional argument that will be passed to the errback. The errback method will get the most recent DeferredException and and any additional arguments that was specified in add_errback. If the errback can catch the exception it can return a value that will be passed to the next callback in the chain. Otherwise the errback chain will not be processed anymore. See the documentation of defer.DeferredException.catch for further information. >>> def catch_error(deferred_error, ignore=False): ... if ignore: ... return "ignored" ... deferred_error.catch(Exception) ... return "catched" >>> deferred = Deferred() >>> deferred.errback(SystemError()) >>> deferred.add_errback(catch_error, ignore=True) >>> deferred.result 'ignored' )rBrCNrDr;rfuncargskwargss r add_errbackzDeferred.add_errbacks < <D*0  2rc6|j|t||y)aAdd a callable (function or method) to the callback chain only. An error would be passed through to the next errback. The first argument is the callable instance followed by any additional argument that will be passed to the callback. The callback method will get the result of the previous callback and any additional arguments that was specified in add_callback. >>> def callback(previous, counter=False): ... if counter: ... return previous + 1 ... return previous >>> deferred = Deferred() >>> deferred.add_callback(callback, counter=True) >>> deferred.callback(1) >>> deferred.result 2 )r@rANrFrGs r add_callbackzDeferred.add_callback5s * 4T+1  3rc|jr t|s t}n9t|ts)t|tsJt|j |d}d|_||_|jy)aStart processing the errorback chain starting with the provided exception or DeferredException. If an exception is specified it will be wrapped into a DeferredException. It will be send to the first errback or stored as finally result if not any further errback has been specified yet. >>> deferred = Deferred() >>> deferred.errback(Exception("Test Error")) >>> deferred.result #doctest: +ELLIPSIS >>> deferred.result.raise_exception() Traceback (most recent call last): ... Exception: Test Error NT)r4rrr!r"r#resultr=)rerrors rr?zDeferred.errbackMsc" ;;') )%'EE#45eY/ //%eooudCE   rcl|jr td|_||_|jy)aOStart processing the callback chain starting with the provided result. It will be send to the first callback or stored as finally one if not any further callback has been specified yet. >>> deferred = Deferred() >>> deferred.callback("done") >>> deferred.result 'done' TN)r4rrOr=rrOs rr>zDeferred.callbackis+ ;;') )   rcZ||_d|_|jr|jyy)z7Continue processing the Deferred with the given result.FN)rOr5r4r=rRs r _continuezDeferred._continue{s%  ;; JJL rc|js |jry|jr|jjd}|t |j t \}}} ||j g|i||_d|_t |j tr@|j j|j|j|jdk(n |jrt |j t rTtj|j j|j j|j jyy#t |_YxYw#d|_wxYw)zProcess the next callback.NrFT)r6r5r2popr!rOrrrDrTr$ excepthookrrr )r next_pairr>rIrJs rr=zDeferred._nexts! ==DKK nn**1-I%.z$++:K0M&N "HdF &&t{{DTDVD !& $++x0  ))$..$..I t#'nn* dkk#4 5 NN4;;++T[[->->;;00 2 6 2/1 % s#EE.,E11 E:)NNNNNr) rrrrrrDrKrMr?r>rTr=rrrrrs=  D/3:>8<5n2B308$rrct|tjjsJ ||i|}t|t r|St }|j ||S#t }Y=xYw)aInvoke the given function that may or not may be a Deferred. If the return object of the function call is a Deferred return, it. Otherwise wrap it into a Deferred. >>> defer(lambda x: x, 10) #doctest: +ELLIPSIS >>> deferred = defer(lambda x: x, "done") >>> deferred.result 'done' >>> deferred = Deferred() >>> defer(lambda: deferred) == deferred True )r!r8r9r:rrr>)rHrIrJrOdeferreds rrrsl" dKOO44 55 5%t&v&&(# zH f O %"$s A A-c|Srr)args rr;r;s Jrct|)a Return val from a inline_callbacks generator. Note: this is currently implemented by raising an exception derived from BaseException. You might want to change any 'except:' clauses to an 'except Exception:' clause so as not to catch this exception. Also: while this function currently will work when called from within arbitrary functions called from within the generator, do not rely upon this behavior. )r)vals rrrs  rc ddg t|t}|rtr7|jj |j }j |}nUj |j|jj |j }nj|}t|t0r4 fd} |j3| |  d rd d <S d}d d <d d<#t$rjdcYSt$r>}tjdj}r |j}|jr|jjr|}|jjr#|j}|jjr#|jj j"}|j$} t'j(d|jj j*d|jj j*dt,|| j|jcYd}~Sd}~wj/cYSxYw) z See inlineCallbacks. TNr r zreturnValue() in z causing zX to exit: returnValue should only be invoked by functions decorated with inlineCallbacksc@dr dd<|d<yt|y)NrFr )_inline_callbacks)resrZgenwaitings r gotResultz$_inline_callbacks..gotResults(1:!&GAJ!$GAJ%c39rrF)r!rr'rr(r throwrsend StopIterationr>rr$r%tb_nexttb_framef_code co_filename tb_linenowarnings warn_explicitco_nameDeprecationWarningr?rrD) rOrcrZ is_failureexcepr. appCodeTrace ultimateTracefilenamelinenorerds `` @rraras$G 9 #F,=>J"LL778H8HIE YYu-F YYv{{6<<'@'O'OPVP`P`'abF&)b fh ' :  I 6qz# QZF GAJGAJe     d #O' <<>!,44L ,33 ## (<(<(D(D !- #++33$1$9$9M$++33(1188DD&00&&&..55==$--44<< > '& :   cii (O     Os,B$C33I, I,B I&B'I I,I,c.tfd}|S)ainline_callbacks helps you write Deferred-using code that looks like a regular sequential function. For example:: def thingummy(): thing = yield makeSomeRequestResultingInDeferred() print thing #the result! hoorj! thingummy = inline_callbacks(thingummy) When you call anything that results in a Deferred, you can simply yield it; your generator will automatically be resumed when the Deferred's result is available. The generator will be sent the result of the Deferred with the 'send' method on generators, or if the result was a failure, 'throw'. Your inline_callbacks-enabled generator will return a Deferred object, which will result in the return value of the generator (or will fail with a failure object if your generator raises an unhandled exception). Note that you can't use return result to return a value; use return_value(result) instead. Falling off the end of the generator, or simply using return will cause the Deferred to have a result of None. The Deferred returned from your deferred generator may errback if your generator raised an exception:: def thingummy(): thing = yield makeSomeRequestResultingInDeferred() if thing == 'I love Twisted': # will become the result of the Deferred return_value('TWISTED IS GREAT!') else: # will trigger an errback raise Exception('DESTROY ALL LIFE') thingummy = inline_callbacks(thingummy) c:td|i|tSr)rar)rIrJrHs runwind_generatorz*inline_callbacks..unwind_generatorSs tT'rs4x6  8 oo  !] 6I6TTnnvn`8 _B%r