σ ¨œž[c@`sψdZddlmZmZmZddlZddlZddlZddlm Z de fd„ƒYZ dej fd„ƒYZ e ƒZd efd „ƒYZd efd „ƒYZd efd„ƒYZd„Zd„Zd„Zd„ZdS(sm `StackContext` allows applications to maintain threadlocal-like state that follows execution as it moves to other execution contexts. The motivating examples are to eliminate the need for explicit ``async_callback`` wrappers (as in `tornado.web.RequestHandler`), and to allow some additional context to be kept for logging. This is slightly magic, but it's an extension of the idea that an exception handler is a kind of stack-local state and when that stack is suspended and resumed in a new context that state needs to be preserved. `StackContext` shifts the burden of restoring that state from each call site (e.g. wrapping each `.AsyncHTTPClient` callback in ``async_callback``) to the mechanisms that transfer control from one context to another (e.g. `.AsyncHTTPClient` itself, `.IOLoop`, thread pools, etc). Example usage:: @contextlib.contextmanager def die_on_error(): try: yield except Exception: logging.error("exception in asynchronous operation",exc_info=True) sys.exit(1) with StackContext(die_on_error): # Any exception thrown here *or in callback and its descendants* # will cause the process to exit instead of spinning endlessly # in the ioloop. http_client.fetch(url, callback) ioloop.start() Most applications shouldn't have to work with `StackContext` directly. Here are a few rules of thumb for when it's necessary: * If you're writing an asynchronous library that doesn't rely on a stack_context-aware library like `tornado.ioloop` or `tornado.iostream` (for example, if you're writing a thread pool), use `.stack_context.wrap()` before any asynchronous operations to capture the stack context from where the operation was started. * If you're writing an asynchronous library that has some shared resources (such as a connection pool), create those shared resources within a ``with stack_context.NullContext():`` block. This will prevent ``StackContexts`` from leaking from one request to another. * If you want to write something like an exception handler that will persist across asynchronous calls, create a new `StackContext` (or `ExceptionStackContext`), and make your asynchronous calls in a ``with`` block that references your `StackContext`. .. deprecated:: 5.1 The ``stack_context`` package is deprecated and will be removed in Tornado 6.0. i(tabsolute_importtdivisiontprint_functionN(traise_exc_infotStackContextInconsistentErrorcB`seZRS((t__name__t __module__(((s4lib/python2.7/site-packages/tornado/stack_context.pyRSst_StatecB`seZd„ZRS(cC`stƒdf|_dS(N(ttupletNonetcontexts(tself((s4lib/python2.7/site-packages/tornado/stack_context.pyt__init__Xs(RRR (((s4lib/python2.7/site-packages/tornado/stack_context.pyRWst StackContextcB`sDeZdZd„Zd„Zd„Zd„Zd„Zd„ZRS(sEstablishes the given context as a StackContext that will be transferred. Note that the parameter is a callable that returns a context manager, not the context itself. That is, where for a non-transferable context manager you would say:: with my_context(): StackContext takes the function itself rather than its result:: with StackContext(my_context): The result of ``with StackContext() as cb:`` is a deactivation callback. Run this callback when the StackContext is no longer needed to ensure that it is not propagated any further (note that deactivating a context does not affect any instances of that context that are currently pending). This is an advanced feature and not necessary in most applications. cC`s/tjdtƒ||_g|_t|_dS(Ns=StackContext is deprecated and will be removed in Tornado 6.0(twarningstwarntDeprecationWarningtcontext_factoryR tTruetactive(R R((s4lib/python2.7/site-packages/tornado/stack_context.pyR ss    cC`s t|_dS(N(tFalseR(R ((s4lib/python2.7/site-packages/tornado/stack_context.pyt _deactivatezscC`s*|jƒ}|jj|ƒ|jƒdS(N(RR tappendt __enter__(R tcontext((s4lib/python2.7/site-packages/tornado/stack_context.pytenter~s cC`s&|jjƒ}|j|||ƒdS(N(R tpopt__exit__(R ttypetvaluet tracebackR((s4lib/python2.7/site-packages/tornado/stack_context.pytexitƒscC`sctj|_|jd|f|f|_|jt_y|jƒWn|jt_‚nX|jS(Ni(t_stateR t old_contextst new_contextsRR(R ((s4lib/python2.7/site-packages/tornado/stack_context.pyRŠs   cC`s[z|j|||ƒWdtj}|jt_||jk rMtdƒ‚nd|_XdS(NsWstack_context inconsistency (may be caused by yield within a "with StackContext" block)(RR R R!R"RR (R RRRtfinal_contexts((s4lib/python2.7/site-packages/tornado/stack_context.pyR—s   ( RRt__doc__R RRRRR(((s4lib/python2.7/site-packages/tornado/stack_context.pyR _s     tExceptionStackContextcB`s>eZdZed„Zd„Zd„Zd„Zd„ZRS(sBSpecialization of StackContext for exception handling. The supplied ``exception_handler`` function will be called in the event of an uncaught exception in this context. The semantics are similar to a try/finally clause, and intended use cases are to log an error, close a socket, or similar cleanup actions. The ``exc_info`` triple ``(type, value, traceback)`` will be passed to the exception_handler function. If the exception handler returns true, the exception will be consumed and will not be propagated to other exception handlers. .. versionadded:: 5.1 The ``delay_warning`` argument can be used to delay the emission of DeprecationWarnings until an exception is caught by the ``ExceptionStackContext``, which facilitates certain transitional use cases. cC`s;||_|js%tjdtƒn||_t|_dS(Ns=StackContext is deprecated and will be removed in Tornado 6.0(t delay_warningRRRtexception_handlerRR(R R'R&((s4lib/python2.7/site-packages/tornado/stack_context.pyR Αs    cC`s t|_dS(N(RR(R ((s4lib/python2.7/site-packages/tornado/stack_context.pyRΚscC`s?|dk r;|jr(tjdtƒn|j|||ƒSdS(Ns=StackContext is deprecated and will be removed in Tornado 6.0(R R&RRRR'(R RRR((s4lib/python2.7/site-packages/tornado/stack_context.pyRΝs    cC`s5tj|_|jd|f|_|jt_|jS(Ni(R R R!R"R(R ((s4lib/python2.7/site-packages/tornado/stack_context.pyRΥs  cC`sgz#|dk r"|j|||ƒSWdtj}|jt_||jk rYtdƒ‚nd|_XdS(NsWstack_context inconsistency (may be caused by yield within a "with StackContext" block)(R R'R R R!R"R(R RRRR#((s4lib/python2.7/site-packages/tornado/stack_context.pyRάs    ( RRR$RR RRRR(((s4lib/python2.7/site-packages/tornado/stack_context.pyR%­s    t NullContextcB`s eZdZd„Zd„ZRS(sΙResets the `StackContext`. Useful when creating a shared resource on demand (e.g. an `.AsyncHTTPClient`) where the stack that caused the creating is not relevant to future operations. cC`s"tj|_tƒdft_dS(N(R R R!RR (R ((s4lib/python2.7/site-packages/tornado/stack_context.pyRτs cC`s|jt_dS(N(R!R R (R RRR((s4lib/python2.7/site-packages/tornado/stack_context.pyRψs(RRR$RR(((s4lib/python2.7/site-packages/tornado/stack_context.pyR(νs cC`sΟtg|dD]}|jr|^qƒ}|d}x'|dk r_|j r_|jd}q9W|}x\|dk rΔ|jd}x6|dk rΊ|jržPn|j|_|jd}q…W|}qiW||fS(s*Remove deactivated handlers from the chainiiN(RRR R!(R thtstack_contextstheadtctxtparent((s4lib/python2.7/site-packages/tornado/stack_context.pyt_remove_deactivatedόs,     c`s‡ˆdkstˆdƒrˆStjg‰ˆdd rhˆdd rh‡‡fd†}t|_|S‡‡fd†}t|_|S(s Returns a callable object that will restore the current `StackContext` when executed. Use this whenever saving a callback to be executed later in a different execution context (either in a different thread or asynchronously in the same thread). t_wrappediic`s8z'tj}ˆdt_ˆ||ŽSWd|t_XdS(Ni(R R (targstkwargst current_state(t cap_contextstfn(s4lib/python2.7/site-packages/tornado/stack_context.pyt null_wrapper(s   c `s¦d}ztj}tˆdƒˆd<}|t_d}d}d}|d}xI|D]A} y| jƒ|d7}WqVtjƒ}| jd}qVXqVW|dkrέyˆ||Ž}Wqέtjƒ}|d}qέXn|dk rϋt||ƒ}n€x_|dkrV|d8}||} y| j |ŒWqώtjƒ}| jd}PqώXqώWd}|dk r{t||ƒ}n|dkr”t |ƒnWd|t_X|S(Nii(NNN(NNN( R R R R.Rtsystexc_infoR!t_handle_exceptionRR( R0R1tretR2R texcttoptlast_ctxtstacktntc(R3R4(s4lib/python2.7/site-packages/tornado/stack_context.pytwrapped2sP                 N(R thasattrR R RR/(R4R5R@((R3R4s4lib/python2.7/site-packages/tornado/stack_context.pytwraps   C cC`sVxO|dk rQy|j|Œr*d}nWntjƒ}nX|jd}qW|S(Ni(NNN(R RR6R7R!(ttailR:((s4lib/python2.7/site-packages/tornado/stack_context.pyR8ys cC`s| |ƒSWdQXdS(sΡRun a coroutine ``func`` in the given `StackContext`. It is not safe to have a ``yield`` statement within a ``with StackContext`` block, so it is difficult to use stack context with `.gen.coroutine`. This helper function runs the function in the correct context while keeping the ``yield`` and ``with`` statements syntactically separate. Example:: @gen.coroutine def incorrect(): with StackContext(ctx): # ERROR: this will raise StackContextInconsistentError yield other_coroutine() @gen.coroutine def correct(): yield run_with_stack_context(StackContext(ctx), other_coroutine) .. versionadded:: 3.1 N((Rtfunc((s4lib/python2.7/site-packages/tornado/stack_context.pytrun_with_stack_context†s(R$t __future__RRRR6t threadingRt tornado.utilRt ExceptionRtlocalRR tobjectR R%R(R.RBR8RE(((s4lib/python2.7/site-packages/tornado/stack_context.pytHs    N@  c