mò ¶ß•Ec@sdZdklZlZdkZdkZdklZlZdk l Z l Z de fd„ƒYZ de fd„ƒYZd „Zd „Zd fd „ƒYZed „Zd„Zd„Zd„Zd„Zd„Zd„Zdfd„ƒYZdfd„ƒYZde fd„ƒYZdefd„ƒYZdd„Zd„ZeZ e!Z"dfd „ƒYZ#d!„Z$d"„Z%ye&Wne'j o e Z&nXd#e&fd$„ƒYZ(d%„Z)d&„Z*d'„Z+d(e,fd)„ƒYZ-d*e-fd+„ƒYZ.d,e-fd-„ƒYZ/d.e fd/„ƒYZ0d0e fd1„ƒYZ1d2e,fd3„ƒYZ2ddd4d5d6d7ddd8d9dd:d;d*d,d2gZ3dS(<sŽSupport for results that aren't immediately available. API Stability: stable Maintainer: U{Glyph Lefkowitz} (s nested_scopess generatorsN(slogsfailure(s unsignedIDsmergeFunctionMetadatatAlreadyCalledErrorcBstZRS(N(t__name__t __module__(((tn/home/radix/Projects/Twisted/branches/releases/twisted-core-2.5.x-2329-2/Twisted.exp/twisted/internet/defer.pyRst TimeoutErrorcBstZRS(N(RR(((RRscCsti|ƒ|S(N(tlogterr(R((RtlogErrors cCstƒ}|i|ƒ|S(s) Return a Deferred that has already had '.callback(result)' called. This is useful when you're writing synchronous code to an asynchronous interface: i.e., some code is calling you expecting a Deferred result, but you don't actually need to do anything asynchronous. Just return defer.succeed(theResult). See L{fail} for a version of this function that uses a failing Deferred rather than a successful one. @param result: The result to give to the Deferred's 'callback' method. @rtype: L{Deferred} N(tDeferredtdtcallbacktresult(R R ((Rtsucceed s  t_nothingcBstZRS(N(RR(((RR 5scCs7|tjotiƒ}ntƒ}|i|ƒ|S(s Return a Deferred that has already had '.errback(result)' called. See L{succeed}'s docstring for rationale. @param result: The same argument that L{Deferred.errback} takes. @rtype: L{Deferred} N(R R tfailuretFailureRR terrback(R R ((Rtfail7s    cOs2y|||Ž}WntƒSn Xt|ƒSdS(sCreate a deferred from a callable and arguments. Call the given function with the given arguments. Return a deferred which has been fired with its callback as the result of that invocation or its errback with a Failure for the exception thrown. N(tcallabletargstkwR RR (RRRR ((RtexecuteGs  cOszd}y|||Ž}WnttiƒƒSnDXt |t ƒo|Sn,t |tiƒot|ƒSn t |ƒS|S(s®Invoke a function that may or may not return a deferred. Call the given function with the given arguments. If the returned object is a C{Deferred}, return it. If the returned object is a C{Failure}, wrap it with C{fail} and return it. Otherwise, wrap it in C{succeed} and return it. If an exception is raised, convert it to a C{Failure}, wrap it in C{fail}, and then return it. @type f: Any callable @param f: The callable to invoke @param args: The arguments to pass to C{f} @param kw: The keyword arguments to pass to C{f} @rtype: C{Deferred} @return: The result of the function call, wrapped in a C{Deferred} if necessary. N( tNonetdeferredtfRRR RRRt isinstanceRR (RRRRR ((Rt maybeDeferredUs cCs |ititdƒƒƒdS(NsCallback timed out(RRRRR(R((RttimeoutwscCs|S(N(targ(R((RtpassthruzscCst|ƒt_dS(s³Enable or disable Deferred debugging. When debugging is on, the call stacks from creation and invocation are recorded, and added to any AlreadyCalledErrors we raise. N(tbooltonRtdebug(R((Rt setDebugging}scCstiS(s5Determine whether Deferred debugging is enabled. N(RR (((Rt getDebugging…sRcBsÎtZdZdZdZeZeZeZ d„Z eeeeed„Z d„Z d„Z d„Zd„Zd„Zed „Zd „Zd „Zd „Zd „Zd„Zed„Zd„ZeZRS(s§This is a callback which will be put off until later. Why do we want this? Well, in cases where a function in a threaded program would block until it gets a result, for Twisted it should not block. Instead, it should return a Deferred. This can be implemented for protocols that run over the network by writing an asynchronous protocol for twisted.internet. For methods that come from outside packages that are not under our control, we use threads (see for example L{twisted.enterprise.adbapi}). For more information about Deferreds, see doc/howto/defer.html or U{http://twistedmatrix.com/projects/core/documentation/howto/defer.html} icCs=g|_|io&tƒ|_tiƒd |i_ndS(Niÿÿÿÿ(tselft callbacksR t DebugInfot _debugInfot tracebackt format_stacktcreator(R#((Rt__init__¢s   cCs†t|ƒpt‚|djpt|ƒpt‚|||f|pt||ff}|i i |ƒ|io|iƒn|S(s‰Add a pair of callbacks (success and error) to this Deferred. These will be executed when the 'master' callback is run. N(RR tAssertionErrorRRt callbackArgstcallbackKeywordsRt errbackArgsterrbackKeywordstcbsR#R$tappendtcalledt _runCallbacks(R#R RR,R-R.R/R0((Rt addCallbacks¨s!% cOs|i|d|d|ƒS(sUConvenience method for adding just a callback. See L{addCallbacks}. R,R-N(R#R4R RR(R#R RR((Rt addCallback¹scOs|it|d|d|ƒS(sUConvenience method for adding just an errback. See L{addCallbacks}. R.R/N(R#R4RRRR(R#RRR((Rt addErrbackÁs c Os(|i||d|d|d|d|ƒS(sConvenience method for adding a single callable as both a callback and an errback. See L{addCallbacks}. R,R.R-R/N(R#R4R RR(R#R RR((RtaddBothÊs  cCs|i|i|iƒS(sIChain another Deferred to this Deferred. This method adds callbacks to this Deferred to call d's callback or errback, as appropriate. It is merely a shorthand way of performing the following:: self.addCallbacks(d.callback, d.errback) When you chain a deferred d2 to another deferred d1 with d1.chainDeferred(d2), you are making d2 participate in the callback chain of d1. Thus any event that fires d1 will also fire d2. However, the converse is B{not} true; if d2 is fired d1 will not be affected. N(R#R4R R R(R#R ((Rt chainDeferredÔscCs)t|tƒ pt‚|i|ƒdS(suRun all success callbacks that have been added to this Deferred. Each callback will have its result passed as the first argument to the next; this way, the callbacks act as a 'processing chain'. Also, if the success-callback returns a Failure or raises an Exception, processing will continue on the *error*- callback chain. N(RR RR+R#t_startRunCallbacks(R#R ((RR åscCs7t|tiƒpti|ƒ}n|i|ƒdS(sÌRun all error callbacks that have been added to this Deferred. Each callback will have its result passed as the first argument to the next; this way, the callbacks act as a 'processing chain'. Also, if the error-callback returns a non-Failure or doesn't raise an Exception, processing will continue on the *success*-callback chain. If the argument that's passed to me is not a failure.Failure instance, it will be embedded in one. If no argument is passed, a failure.Failure instance will be created based on the current traceback stack. Passing a string as `fail' is deprecated, and will be punished with a warning message. N(RRRRR#R9(R#R((RRòscCs|id|_dS(sDStop processing on a Deferred until L{unpause}() is called. iN(R#tpaused(R#((RtpausescCs>|id|_|iodSn|io|iƒndS(s@Process all callbacks made since L{pause}() was called. iN(R#R:R2R3(R#((Rtunpauses   cCs||_|iƒdS(N(R R#R<(R#R ((Rt _continues cCsô|ioW|ioC|idjotƒ|_nd|iiƒ}t|ƒ‚nt‚n|io:|idjotƒ|_nt i ƒd |i_ nt |_||_ |io%y|iiƒWnnX|`n|iƒdS(Ns iþÿÿÿ(R#R2R R&RR%t_getDebugTracebackstextraRR'R(tinvokertTrueR t timeoutCalltcancelR3(R#R R?((RR9s(        cCsg|ipã|i}g|_xÎ|oÂ|idƒ}|t|iti ƒ\}}}|pf}|ph}yZ||i||Ž|_t|it ƒo+||_|iƒ|ii|iƒPnWqti ƒ|_qXqWnt|iti ƒo@|iiƒ|idjotƒ|_n|i|i_n!|idj od|i_ndS(Ni(R#R:R$tcbtpoptitemRR RRR RRRR;R7R=t cleanFailureR&RR%t failResult(R#RFRDRR R((RR32s2   "      csutidtddƒˆiodSnˆi p td‚dkl}|i |‡‡‡‡d†ƒˆ_ˆiS(sOSet a timeout function to be triggered if I am not called. @param seconds: How long to wait (from now) before firing the timeoutFunc. @param timeoutFunc: will receive the Deferred and *args, **kw as its arguments. The default timeoutFunc will call the errback with a L{TimeoutError}. sgDeferred.setTimeout is deprecated. Look for timeout support specific to the API you are using instead.t stackleveliNs1Don't call setTimeout twice on the same Deferred.(sreactorcsˆipˆˆˆˆŽS(N(R#R2t timeoutFuncRR((RJR#RR(Rtls( twarningstwarntDeprecationWarningR#R2RBR+ttwisted.internettreactort callLatertseconds(R#RRRJRRRP((R#RJRRRt setTimeoutVs      cCsZ|ii}t|dƒo$d|tt|ƒƒ|ifSnd|tt|ƒƒfS(NR s<%s at %s current result: %r>s <%s at %s>(R#t __class__Rtcnamethasattrthext unsignedIDR (R#RU((Rt__str__os $(RRt__doc__R2R:RRBR&tFalseR R*R4R5R6R7R8R RR;R<R=R9R3RRSRYt__repr__(((RRŠs,         $  R%cBs&tZdZeZd„Zd„ZRS(sDeferred debug helpercCsªd}t|dƒo@|d7}|di|iƒiƒiddƒ7}|d7}nt|dƒo@|d7}|di|iƒiƒiddƒ7}|d7}n|S( NtR)s C: Deferred was created: C:s s C:R@s I: First Invoker was: I:s I:(tinfoRVR#tjoinR)trstriptreplaceR@(R#R^((RR>{s ( (cCss|idj o_tiddtƒ|iƒ}|djotid|ddtƒnti|iƒndS(s°Print tracebacks and die. If the *last* (and I do mean *last*) callback leaves me in an error state, print a traceback (if said errback is a Failure). sUnhandled error in Deferred:tisErrorR]s(debug: t)N( R#RHRRtmsgRAR>t debugInfoR(R#Re((Rt__del__‡s  (RRRZRRHR>Rf(((RR%ws  t FirstErrorcBsDtZdZd„Zd„Zd„Zd„Zd„Zd„ZRS(sÒFirst error to occur in a DeferredList if fireOnOneErrback is set. @ivar subFailure: the L{Failure} that occurred. @ivar index: the index of the Deferred in the DeferredList where it happened. cCs||_||_dS(N(RR#t subFailuretindex(R#RRi((RR*›s cCsd|i|ifS(NsFirstError(%r, %d)(R#RhRi(R#((RR\ŸscCs t|ƒS(N(treprR#(R#((RRY¢scCs-tiddtddƒ|i|ig|S(Ns>FirstError.__getitem__ is deprecated. Use attributes instead.tcategoryRIi(RLRMRNR#RhRi(R#Ri((Rt __getitem__¥s cCs0tiddtddƒ|i|ig||!S(Ns?FirstError.__getslice__ is deprecated. Use attributes instead.RkRIi(RLRMRNR#RhRitstarttstop(R#RmRn((Rt __getslice__«s cCs_t|tƒot|ƒ|jSn8t|tƒo'|i|ijo|i|ijSntS(N(RtotherttupleR#RgRhRiR[(R#Rp((Rt__eq__±s '( RRRZR*R\RYRlRoRr(((RRg”s      t DeferredListcBs5tZdZdZdZdddd„Zd„ZRS(sgI combine a group of deferreds into one callback. I track a list of L{Deferred}s for their callbacks, and make a single callback when they have all completed, a list of (success, result) tuples, 'success' being a boolean. Note that you can still use a L{Deferred} after putting it in a DeferredList. For example, you can suppress 'Unhandled error in Deferred' messages by adding errbacks to the Deferreds *after* putting them in the DeferredList, as a DeferredList won't swallow the errors. (Although a more convenient way to do this is simply to set the consumeErrors flag) ic CsÉdgt|ƒ|_ti|ƒt|ƒdjo| o|i|iƒn||_||_ ||_ d|_ d}xF|D]>}|i|i|id|tfd|tfƒ|d}qƒWdS(s>Initialize a DeferredList. @type deferredList: C{list} of L{Deferred}s @param deferredList: The list of deferreds to track. @param fireOnOneCallback: (keyword param) a flag indicating that only one callback needs to be fired for me to call my callback @param fireOnOneErrback: (keyword param) a flag indicating that only one errback needs to be fired for me to call my errback @param consumeErrors: (keyword param) a flag indicating that any errors raised in the original deferreds should be consumed by this DeferredList. This is useful to prevent spurious warnings being logged. iR,R.iN(Rtlent deferredListR#t resultListRR*tfireOnOneCallbackR tfireOnOneErrbackt consumeErrorst finishedCountRiRR4t _cbDeferredtSUCCESStFAILURE(R#RuRwRxRyRiR((RR*Ês       cCsê||f|i|<|id7_|ip™|tjo!|io|i ||fƒqÅ|t jo-|i o#|i t it||ƒƒƒqÅ|it|iƒjo|i |iƒqÅn|t jo|io d}n|S(s@(internal) Callback for when one of my deferreds fires. iN(t succeededR R#RvRiRzR2R|RwR R}RxRRRRgRtRyR(R#R RiR~((RR{ïs # (RRRZRwRxR*R{(((RRs¹s %icCsSto)x&|D]\}}|pt‚qWng}|D]}||dq;~S(Ni(t __debug__tltsuccesstvalueR+t_[1]tx(R€RxRR‚RƒR„((Rt_parseDListResults  cCs#t|ddƒ}|itƒ|S(s×Returns list with result of given Deferreds. This builds on C{DeferredList} but is useful since you don't need to parse the result for success/failure. @type deferredList: C{list} of L{Deferred}s RxiN(RsRuR R5R…(RuR ((Rt gatherResults s twaitForDeferredcBs tZdZd„Zd„ZRS(s# See L{deferredGenerator}. cCs4t|tƒptd|fƒ‚n||_dS(Ns9You must give waitForDeferred a Deferred. You gave it %r.(RR Rt TypeErrorR#(R#R ((RR*#scCs.t|itiƒo|iiƒn|iS(N(RR#R RRtraiseException(R#((Rt getResult)s(RRRZR*RŠ(((RR‡s  csýd}tdg‰xäyˆiƒ}Wn8tj oˆi|ƒˆSnˆi ƒˆSnXt |t ƒot t dƒƒSnt |tƒo`|‡‡‡d†}|ii|ƒˆdotˆd<ˆSntˆd} deferredGenerator and waitForDeferred help you write Deferred-using code that looks like a regular sequential function. If your code has a minimum requirement of Python 2.5, consider the use of L{inlineCallbacks} instead, which can accomplish the same thing in a more concise manner. There are two important functions involved: waitForDeferred, and deferredGenerator. They are used together, like this:: def thingummy(): thing = waitForDeferred(makeSomeRequestResultingInDeferred()) yield thing thing = thing.getResult() print thing #the result! hoorj! thingummy = deferredGenerator(thingummy) waitForDeferred returns something that you should immediately yield; when your generator is resumed, calling thing.getResult() will either give you the result of the Deferred if it was a success, or raise an exception if it was a failure. Calling C{getResult} is B{absolutely mandatory}. If you do not call it, I{your program will not work}. deferredGenerator takes one of these waitForDeferred-using generator functions and converts it into a function that returns a Deferred. The result of the Deferred will be the last value that your generator yielded unless the last value is a waitForDeferred instance, in which case the result will be C{None}. If the function raises an unhandled exception, the Deferred will errback instead. Remember that 'return result' won't work; use 'yield result; return' in place of that. Note that not yielding anything from your generator will make the Deferred result in None. Yielding a Deferred from your generator is also an error condition; always yield waitForDeferred(d) instead. The Deferred returned from your deferred generator may also errback if your generator raised an exception. For example:: def thingummy(): thing = waitForDeferred(makeSomeRequestResultingInDeferred()) yield thing thing = thing.getResult() if thing == 'I love Twisted': # will become the result of the Deferred yield 'TWISTED IS GREAT!' return else: # will trigger an errback raise Exception('DESTROY ALL LIFE') thingummy = deferredGenerator(thingummy) Put succinctly, these functions connect deferred-using code with this 'fake blocking' style in both directions: waitForDeferred converts from a Deferred to the 'blocking' style, and deferredGenerator converts from the 'blocking' style to a Deferred. cstˆ||ŽtƒƒS(N(RRRtkwargsR(RR’(R(RtunwindGenerator¤sN(R“tmergeFunctionMetadataR(RR“((RRtdeferredGeneratorhs; t_DefGen_ReturncBstZd„ZRS(NcCs ||_dS(N(R‚R#(R#R‚((RR*²s(RRR*(((RR–±scCst|ƒ‚dS(s¿ Return val from a L{inlineCallbacks} 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. N(R–tval(R—((Rt returnValueµs cs1tdg‰xyHt|tiƒo"ˆi|i |i |i ƒ}nˆi |ƒ}Wn`t j oˆidƒˆSn>tj o}ˆi|i ƒˆSnˆiƒˆSnXt|tƒo^‡‡‡d†}|i|ƒˆdotˆd<ˆSnˆd}tˆd} WARNING: this function will not work in Python 2.4 and earlier! inlineCallbacks helps you write Deferred-using code that looks like a regular sequential function. This function uses features of Python 2.5 generators. If you need to be compatible with Python 2.4 or before, use the L{deferredGenerator} function instead, which accomplishes the same thing, but with somewhat more boilerplate. def thingummy(): thing = yield makeSomeRequestResultingInDeferred() print thing #the result! hoorj! thingummy = inlineCallbacks(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 inlineCallbacks-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 'returnValue(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 returnValue('TWISTED IS GREAT!') else: # will trigger an errback raise Exception('DESTROY ALL LIFE') thingummy = inlineCallbacks(thingummy) cstdˆ||ŽtƒƒS(N(R™RRRR’R(RR’(R(RR“,sN(R“R”R(RR“((RRtinlineCallbackss+ t_ConcurrencyPrimitivecBs#tZd„Zd„Zd„ZRS(NcCs g|_dS(N(R#RŒ(R#((RR*4scCs|iƒ|S(N(R#treleaseR‹(R#R‹((Rt_releaseAndReturn7s cs—tˆƒdjo8ˆptdƒ‚ntdˆdiifƒ‚nˆd \‰‰ˆd‰‡‡‡‡d†}ˆiƒ}|i |ƒ|S(s¾Acquire, run, release. This function takes a callable as its first argument and any number of other positional and keyword arguments. When the lock or semaphore is acquired, the callable will be invoked with those arguments. The callable may return a Deferred; if it does, the lock or semaphore won't be released until that Deferred fires. @return: Deferred of function result. is-run() takes at least 2 arguments, none given.s,%s.run() takes at least 2 arguments, 1 givenics&tˆˆˆŽ}|iˆiƒ|S(N(RRRR’R R7R#R¢(t ignoredResultR (RR#RR’(RRPsN( RtRRˆRTRR#RRtacquireR R5(RR’RR RR#((RR’R#RRtrun;s !   (RRR*R¢R¥(((RR 3s  t DeferredLockcBs&tZdZdZd„Zd„ZRS(s A lock for event driven systems. API stability: Unstable @ivar locked: True when this Lock has been acquired, false at all other times. Do not change this value, but it is useful to examine for the equivalent of a "non-blocking" acquisition. icCsAtƒ}|io|ii|ƒnd|_|i|ƒ|S(scAttempt to acquire the lock. @return: a Deferred which fires on lock acquisition. iN(RR R#tlockedRŒR1R (R#R ((RR¤fs    cCsW|ip td‚d|_|io,d|_|iidƒ}|i|ƒndS(s|Release the lock. Should be called by whomever did the acquire() when the shared resource is free. s!Tried to release an unlocked lockiiN(R#R§R+RŒRER R (R#R ((RR¡ss   (RRRZR§R¤R¡(((RR¦Zs  tDeferredSemaphorecBs)tZdZd„Zd„Zd„ZRS(sGA semaphore for event driven systems. API stability: Unstable cCs#ti|ƒ||_||_dS(N(R R*R#ttokenstlimit(R#R©((RR*‡s  cCsb|idjp td‚tƒ}|ip|ii|ƒn|id|_|i|ƒ|S(seAttempt to acquire the token. @return: a Deferred which fires on token acquisition. is9Internal inconsistency?? tokens should never be negativeiN(R#R©R+RR RŒR1R (R#R ((RR¤Œs   cCsn|i|ijp td‚|id|_|io3|id|_|iidƒ}|i|ƒndS(s|Release the token. Should be called by whoever did the acquire() when the shared resource is free. s4Someone released me too many times: too many tokens!iiN(R#R©RªR+RŒRER R (R#R ((RR¡šs (RRRZR*R¤R¡(((RR¨s   t QueueOverflowcBstZRS(N(RR(((RR«¨stQueueUnderflowcBstZRS(N(RR(((RR¬«st DeferredQueuecBs/tZdZeed„Zd„Zd„ZRS(sµAn event driven queue. API stability: Unstable Objects may be added as usual to this queue. When an attempt is made to retrieve an object when the queue is empty, a Deferred is returned which will fire when an object becomes available. @ivar size: The maximum number of objects to allow into the queue at a time. When an attempt to add a new object would exceed this limit, QueueOverflow is raised synchronously. None for no limit. @ivar backlog: The maximum number of Deferred gets to allow at one time. When an attempt is made to get an object which would exceed this limit, QueueUnderflow is raised synchronously. None for no limit. cCs(g|_g|_||_||_dS(N(R#RŒtpendingtsizetbacklog(R#R¯R°((RR*Âs   cCsq|io|iidƒi|ƒnG|idjpt|iƒ|ijo|ii |ƒn t ƒ‚dS(shAdd an object to this queue. @raise QueueOverflow: Too many objects are in this queue. iN( R#RŒRER tobjR¯RRtR®R1R«(R#R±((RtputÈs  )cCs{|iot|iidƒƒSnT|idjpt|iƒ|ijo!tƒ}|ii |ƒ|Sn t ƒ‚dS(sAttempt to retrieve and remove an object from the queue. @return: a Deferred which fires with the next object available in the queue. @raise QueueUnderflow: Too many (more than C{backlog}) Deferreds are already waiting for an object from this queue. iN( R#R®R RER°RRtRŒRR R1R¬(R#R ((RtgetÔs ) (RRRZRR*R²R³(((RR­¯s  R RR}R|R†RR•RŸ(4RZt __future__t nested_scopest generatorsR'RLttwisted.pythonRRttwisted.python.utilRXR”t ExceptionRRRR R RRRRRR!R"RR%RgRsR…R†RAR|R[R}R‡RR•t BaseExceptiont NameErrorR–R˜R™RŸtobjectR R¦R¨R«R¬R­t__all__(+RR˜RR%R…RgR•RR‡RŸRRR½R R¨R­R¶R R¦R†R™RRµRLRR R|R”RRR!R–RR'RsR"R}R¬RRR«RXRº((Rt? sV       "    í%J   8 D   < 3'''7