HEX

File: //opt/saltstack/salt/lib/python3.10/site-packages/tornado/__pycache__/gen.cpython-310.pyc
o

;j|�
@s$dZddlZddlZddlZddlmZddlZddlZddl	Z	ddl	m
Z
ddlmZddl
Z
ddlZddlmZmZmZmZmZmZddlmZddlmZdd	lmZzddlZWneygdZYnwddlZdd
lmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)ej*r�ddlm+Z+m,Z,m-Z-m.Z.e�/d�Z0e de&e#e&e'e!e&fej1jfZ2Gd
d�de3�Z4Gdd�de3�Z5Gdd�de3�Z6Gdd�de3�Z7Gdd�de3�Z8de e9dfde!fdd�Z:defdd�Z;de"de0fd e!d!e!de0fd"d#�Z<e)d$e"d%de"d&fd'd(��Z=e)d$e"de0fde"d&fd)d(��Z=d$e e"d%e"de0ffde"d&fd*d(�Z=d$e!de>fd+d,�Z?Gd-d�de3�Z@Gd.d/�d/�ZAe)	0dQd1e(e2d2e e$e3e%e$e3dffdee#fd3d4��ZBe)	0dQd1ee!e2fd2e e$e3e%e$e3dffdee'fd5d4��ZB	0dQd1e e(e2ee!e2ffd2d6dd7fd8d4�ZBeBZC	0dQd1e e(e2ee!e2ffd2d6dd7fd9d:�ZDd;e!defd<d=�ZE	0dQd>e eFejGfd?e2d2d6defd@dA�ZHdBeFddCfdDdE�ZIGdFdG�dG�ZJe�KeeJ��ZLe�KeeJ��ZMdHeM_GdIdJ�dJ�ZNdKe&defdLdM�ZOdNe2defdOdP�ZPe
eP�ZPdS)Ra*	``tornado.gen`` implements generator-based coroutines.

.. note::

   The "decorator and generator" approach in this module is a
   precursor to native coroutines (using ``async def`` and ``await``)
   which were introduced in Python 3.5. Applications that do not
   require compatibility with older versions of Python should use
   native coroutines instead. Some parts of this module are still
   useful with native coroutines, notably `multi`, `sleep`,
   `WaitIterator`, and `with_timeout`. Some of these functions have
   counterparts in the `asyncio` module which may be used as well,
   although the two may not necessarily be 100% compatible.

Coroutines provide an easier way to work in an asynchronous
environment than chaining callbacks. Code using coroutines is
technically asynchronous, but it is written as a single generator
instead of a collection of separate functions.

For example, here's a coroutine-based handler:

.. testcode::

    class GenAsyncHandler(RequestHandler):
        @gen.coroutine
        def get(self):
            http_client = AsyncHTTPClient()
            response = yield http_client.fetch("http://example.com")
            do_something_with_response(response)
            self.render("template.html")

Asynchronous functions in Tornado return an ``Awaitable`` or `.Future`;
yielding this object returns its result.

You can also yield a list or dict of other yieldable objects, which
will be started at the same time and run in parallel; a list or dict
of results will be returned when they are all finished:

.. testcode::

    @gen.coroutine
    def get(self):
        http_client = AsyncHTTPClient()
        response1, response2 = yield [http_client.fetch(url1),
                                      http_client.fetch(url2)]
        response_dict = yield dict(response3=http_client.fetch(url3),
                                   response4=http_client.fetch(url4))
        response3 = response_dict['response3']
        response4 = response_dict['response4']

If ``tornado.platform.twisted`` is imported, it is also possible to
yield Twisted's ``Deferred`` objects. See the `convert_yielded`
function to extend this mechanism.

.. versionchanged:: 3.2
   Dict support added.

.. versionchanged:: 4.1
   Support added for yielding ``asyncio`` Futures and Twisted Deferreds
   via ``singledispatch``.

�N)�	Generator)�singledispatch)�isawaitable)�Future�	is_future�chain_future�future_set_exc_info�future_add_done_callback�"future_set_result_unless_cancelled)�IOLoop)�app_log)�TimeoutError)�Mapping�Union�Any�Callable�List�Type�Tuple�	Awaitable�Dict�Sequence�overload)�Deque�Optional�Set�Iterable�_Tc@�eZdZdS)�
KeyReuseErrorN��__name__�
__module__�__qualname__�r$r$�?/opt/saltstack/salt/lib/python3.10/site-packages/tornado/gen.pyrv�rc@r)�UnknownKeyErrorNr r$r$r$r%r'zr&r'c@r)�LeakedCallbackErrorNr r$r$r$r%r(~r&r(c@r)�
BadYieldErrorNr r$r$r$r%r)�r&r)c@r)�ReturnValueIgnoredErrorNr r$r$r$r%r*�r&r*�e�Return�returnc	CsBz|jWSty
Ynwz|jdWSttfy YdSw)Nr)�value�AttributeError�args�
IndexError)r+r$r$r%�_value_from_stopiteration�s��r2cCs@t�}t|dd�}|r|dd}|tkr|d=n	|S|s|S)NZ_source_tracebackr$���r)r�getattr�__file__)�futureZsource_traceback�filenamer$r$r%�_create_future�s�r8�f.r0�kwcOs||i|��S�Nr$)r9r0r:r$r$r%�
_fake_ctx_run�sr<�func).zGenerator[Any, Any, _T]).�
Future[_T]cC�dSr;r$�r=r$r$r%�	coroutine�srAcCr?r;r$r@r$r$r%rA��cs&t����fdd��}�|_d|_|S)a>Decorator for asynchronous generators.

    For compatibility with older versions of Python, coroutines may
    also "return" by raising the special exception `Return(value)
    <Return>`.

    Functions with this decorator return a `.Future`.

    .. warning::

       When exceptions occur inside a coroutine, the exception
       information will be stored in the `.Future` object. You must
       examine the result of the `.Future` object, or the exception
       may go unnoticed by your code. This means yielding the function
       if called from another coroutine, using something like
       `.IOLoop.run_sync` for top-level calls, or passing the `.Future`
       to `.IOLoop.add_future`.

    .. versionchanged:: 6.0

       The ``callback`` argument was removed. Use the returned
       awaitable object instead.

    c
sLt�}tdur
t��j}nt}z
|�g|�Ri|��}Wn0ttfy4}z
t|�}WYd}~nod}~wtyLt	|t
���z|Wd}YSd}wwt|t
�r�z|t|�}Wn*ttfyt}z
t|t|��WYd}~n$d}~wty�t	|t
���Ynwt||||��|��fdd��d}z|Wd}Sd}wt||�|S)Ncs�Sr;r$)�_�Zrunnerr$r%�<lambda>sz,coroutine.<locals>.wrapper.<locals>.<lambda>)r8�contextvarsZcopy_context�runr<r,�
StopIterationr2�	Exceptionr�sys�exc_info�
isinstancer�nextr
�Runner�add_done_callback)r0�kwargsr6�ctx_run�resultr+�yieldedr@rDr%�wrapper�sD��
���

zcoroutine.<locals>.wrapperT)�	functools�wraps�__wrapped__�__tornado_coroutine__)r=rTr$r@r%rA�s
>cCst|dd�S)z�Return whether *func* is a coroutine function, i.e. a function
    wrapped with `~.gen.coroutine`.

    .. versionadded:: 4.5
    rXF)r4r@r$r$r%�is_coroutine_functionsrYcs,eZdZdZddeddf�fdd�
Z�ZS)r,a&Special exception to return a value from a `coroutine`.

    This exception exists for compatibility with older versions of
    Python (before 3.3). In newer code use the ``return`` statement
    instead.

    If this exception is raised, its value argument is used as the
    result of the coroutine::

        @gen.coroutine
        def fetch_json(url):
            response = yield AsyncHTTPClient().fetch(url)
            raise gen.Return(json_decode(response.body))

    By analogy with the return statement, the value argument is optional.
    Nr.r-cst���||_|f|_dSr;)�super�__init__r.r0)�selfr.��	__class__r$r%r[1s
zReturn.__init__r;)r!r"r#�__doc__rr[�
__classcell__r$r$r]r%r,s c@s�eZdZdZiZdededdfdd�Zdefdd	�Zdefd
d�Z	deddfd
d�Z
dedefdd�Zdej
fdd�Zdefdd�ZdS)�WaitIteratora�Provides an iterator to yield the results of awaitables as they finish.

    Yielding a set of awaitables like this:

    ``results = yield [awaitable1, awaitable2]``

    pauses the coroutine until both ``awaitable1`` and ``awaitable2``
    return, and then restarts the coroutine with the results of both
    awaitables. If either awaitable raises an exception, the
    expression will raise that exception and all the results will be
    lost.

    If you need to get the result of each awaitable as soon as possible,
    or if you need the result of some awaitables even if others produce
    errors, you can use ``WaitIterator``::

      wait_iterator = gen.WaitIterator(awaitable1, awaitable2)
      while not wait_iterator.done():
          try:
              result = yield wait_iterator.next()
          except Exception as e:
              print("Error {} from {}".format(e, wait_iterator.current_future))
          else:
              print("Result {} received from {} at {}".format(
                  result, wait_iterator.current_future,
                  wait_iterator.current_index))

    Because results are returned as soon as they are available the
    output from the iterator *will not be in the same order as the
    input arguments*. If you need to know which future produced the
    current result, you can use the attributes
    ``WaitIterator.current_future``, or ``WaitIterator.current_index``
    to get the index of the awaitable from the input list. (if keyword
    arguments were used in the construction of the `WaitIterator`,
    ``current_index`` will use the corresponding keyword).

    `WaitIterator` implements the async iterator
    protocol, so it can be used with the ``async for`` statement (note
    that in this version the entire iteration is aborted if any value
    raises an exception, while the previous example can continue past
    individual errors)::

      async for result in gen.WaitIterator(future1, future2):
          print("Result {} received from {} at {}".format(
              result, wait_iterator.current_future,
              wait_iterator.current_index))

    .. versionadded:: 4.1

    .. versionchanged:: 4.3
       Added ``async for`` support in Python 3.5.

    r0rPr-NcOs�|r|rtd��|rdd�|��D�|_t|���}ndd�t|�D�|_|}t��|_d|_	d|_
d|_|D]}t||j
�q7dS)Nz)You must provide args or kwargs, not bothcS�i|]\}}||�qSr$r$)�.0�kr9r$r$r%�
<dictcomp>v�z)WaitIterator.__init__.<locals>.<dictcomp>cSrbr$r$)rc�ir9r$r$r%reyrf)�
ValueError�items�_unfinished�list�values�	enumerate�collections�deque�	_finished�
current_index�current_future�_running_futurer	�_done_callback)r\r0rP�futuresr6r$r$r%r[qs
�zWaitIterator.__init__cCs |js|jrdSd|_|_dS)z2Returns True if this iterator has no more results.FNT)rprjrqrr�r\r$r$r%�done�szWaitIterator.donecCs$t�|_|jr|�|j���S|jS)z�Returns a `.Future` that will yield the next available result.

        Note that this `.Future` will not be the same object as any of
        the inputs.
        )rrsrp�_return_result�popleftrvr$r$r%rM�szWaitIterator.nextrwcCs.|jr|j��s|�|�dS|j�|�dSr;)rsrwrxrp�append)r\rwr$r$r%rt�szWaitIterator._done_callbackcCsB|jdur	td��t||j�|j}d|_||_|j�|�|_|S)z�Called set the returned future's state that of the future
        we yielded, and set the current future for the iterator.
        Nzno future is running)rsrIrrrrj�poprq)r\rw�resr$r$r%rx�s
zWaitIterator._return_resultcCs|Sr;r$rvr$r$r%�	__aiter__�rBzWaitIterator.__aiter__cCs|��r
ttd���|��S)N�StopAsyncIteration)rwr4�builtinsrMrvr$r$r%�	__anext__�szWaitIterator.__anext__)r!r"r#r_rjrr[�boolrwrMrtrx�typing�
AsyncIteratorr}r�r$r$r$r%ra8s6
rar$�children�quiet_exceptionscCr?r;r$�r�r�r$r$r%�multi��r�cCr?r;r$r�r$r$r%r��r�z3Union[Type[Exception], Tuple[Type[Exception], ...]]z!Union[Future[List], Future[Dict]]cCst||d�S)aRuns multiple asynchronous operations in parallel.

    ``children`` may either be a list or a dict whose values are
    yieldable objects. ``multi()`` returns a new yieldable
    object that resolves to a parallel structure containing their
    results. If ``children`` is a list, the result is a list of
    results in the same order; if it is a dict, the result is a dict
    with the same keys.

    That is, ``results = yield multi(list_of_futures)`` is equivalent
    to::

        results = []
        for future in list_of_futures:
            results.append(yield future)

    If any children raise exceptions, ``multi()`` will raise the first
    one. All others will be logged, unless they are of types
    contained in the ``quiet_exceptions`` argument.

    In a ``yield``-based coroutine, it is not normally necessary to
    call this function directly, since the coroutine runner will
    do it automatically when a list or dict is yielded. However,
    it is necessary in ``await``-based coroutines, or to pass
    the ``quiet_exceptions`` argument.

    This function is available under the names ``multi()`` and ``Multi()``
    for historical reasons.

    Cancelling a `.Future` returned by ``multi()`` does not cancel its
    children. `asyncio.gather` is similar to ``multi()``, but it does
    cancel its children.

    .. versionchanged:: 4.2
       If multiple yieldables fail, any exceptions after the first
       (which is raised) will be logged. Added the ``quiet_exceptions``
       argument to suppress this logging for selected exception types.

    .. versionchanged:: 4.3
       Replaced the class ``Multi`` and the function ``multi_future``
       with a unified function ``multi``. Added support for yieldables
       other than ``YieldPoint`` and `.Future`.

    �r�)�multi_futurer�r$r$r%r��s0cs�t|t�rt|����|��}nd�|}ttt|���tdd��D��s&J�t���t	���s:t
��dur7ing�dtddf�����fdd�}t�}�D]}||vr^|�|�t
||�qN�S)a�Wait for multiple asynchronous futures in parallel.

    Since Tornado 6.0, this function is exactly the same as `multi`.

    .. versionadded:: 4.0

    .. versionchanged:: 4.2
       If multiple ``Futures`` fail, any exceptions after the first (which is
       raised) will be logged. Added the ``quiet_exceptions``
       argument to suppress this logging for selected exception types.

    .. deprecated:: 4.3
       Use `multi` instead.
    Ncss"�|]}t|�pt|t�VqdSr;)rrL�_NullFuture)rcrgr$r$r%�	<genexpr>s� zmulti_future.<locals>.<genexpr>�futr-cs���|��s\g}�D]5}z	|�|���Wqty@}z���r/t|��s.tjddd�nt�t	�
��WYd}~qd}~ww���s^�durUt�tt
�|���dSt�|�dSdSdS)Nz!Multiple exceptions in yield listT�rK)�removerzrRrIrwrLr�errorrrJrKr
�dict�zip)r�Zresult_listr9r+�Z
children_futsr6�keysr�Zunfinished_childrenr$r%�callbacks0

������
zmulti_future.<locals>.callback)rLr�rkr�rl�map�convert_yielded�all�setr8r
r�addr	)r�r�Zchildren_seqr�Z	listeningr9r$r�r%r��s&



�r��xcCs t|�r|St�}|�|�|S)aConverts ``x`` into a `.Future`.

    If ``x`` is already a `.Future`, it is simply returned; otherwise
    it is wrapped in a new `.Future`.  This is suitable for use as
    ``result = yield gen.maybe_future(f())`` when you don't know whether
    ``f()`` returns a `.Future` or not.

    .. deprecated:: 4.3
       This function only handles ``Futures``, not other yieldable objects.
       Instead of `maybe_future`, check for the non-future result types
       you expect (often just ``None``), and ``yield`` anything unknown.
    )rr8Z
set_result)r�r�r$r$r%�maybe_future;s


r��timeoutr6cs�t|��t��t���t���dtddf�fdd��d���fdd�}��||��t�t�r;t���fdd	���S��	���fd
d	���S)a�Wraps a `.Future` (or other yieldable object) in a timeout.

    Raises `tornado.util.TimeoutError` if the input future does not
    complete before ``timeout``, which may be specified in any form
    allowed by `.IOLoop.add_timeout` (i.e. a `datetime.timedelta` or
    an absolute time relative to `.IOLoop.time`)

    If the wrapped `.Future` fails after it has timed out, the exception
    will be logged unless it is either of a type contained in
    ``quiet_exceptions`` (which may be an exception type or a sequence of
    types), or an ``asyncio.CancelledError``.

    The wrapped `.Future` is not canceled when the timeout expires,
    permitting it to be reused. `asyncio.wait_for` is similar to this
    function but it does cancel the wrapped `.Future` on timeout.

    .. versionadded:: 4.0

    .. versionchanged:: 4.1
       Added the ``quiet_exceptions`` argument and the logging of unhandled
       exceptions.

    .. versionchanged:: 4.4
       Added support for yieldable objects other than `.Future`.

    .. versionchanged:: 6.0.3
       ``asyncio.CancelledError`` is now always considered "quiet".

    .. versionchanged:: 6.2
       ``tornado.util.TimeoutError`` is now an alias to ``asyncio.TimeoutError``.

    r6r-Nc
srz|��WdStjyYdSty8}zt|��s-tjd|dd�WYd}~dSWYd}~dSd}~ww)Nz$Exception in Future %r after timeoutTr�)rR�asyncioZCancelledErrorrIrLrr�)r6r+r�r$r%�error_callbacks
����z$with_timeout.<locals>.error_callbackcs$���s��td��t���dS)NZTimeout)rwZ
set_exceptionr
r	r$)r��future_convertedrRr$r%�timeout_callback�sz&with_timeout.<locals>.timeout_callbackc�
����Sr;�Zremove_timeout�r6��io_loop�timeout_handler$r%rE��
zwith_timeout.<locals>.<lambda>cr�r;r�r�r�r$r%rE�r��r-N)
r�r8rr�currentrZadd_timeoutrLr	�
add_future)r�r6r�r�r$)r�r�r�r�rRr�r%�with_timeoutPs *

�	��r��durationzFuture[None]cs"t��t���|�fdd���S)a�Return a `.Future` that resolves after the given number of seconds.

    When used with ``yield`` in a coroutine, this is a non-blocking
    analogue to `time.sleep` (which should not be used in coroutines
    because it is blocking)::

        yield gen.sleep(0.5)

    Note that calling this function on its own does nothing; you must
    wait on the `.Future` it returns (usually by yielding it).

    .. versionadded:: 4.1
    cs
t�d�Sr;)r
r$�r9r$r%rE�r�zsleep.<locals>.<lambda>)r8rr�Z
call_later)r�r$r�r%�sleep�s
�r�c@s(eZdZdZddd�Zdefdd�ZdS)	r�a�_NullFuture resembles a Future that finished with a result of None.

    It's not actually a `Future` to avoid depending on a particular event loop.
    Handled as a special case in the coroutine runner.

    We lie and tell the type checker that a _NullFuture is a Future so
    we don't have to leak _NullFuture into lots of public APIs. But
    this means that the type checker can't warn us when we're passing
    a _NullFuture into a code path that doesn't understand what to do
    with it.
    r-NcCr?r;r$rvr$r$r%rR�rBz_NullFuture.resultcCsdS)NTr$rvr$r$r%rw�rBz_NullFuture.doner�)r!r"r#r_rRr�rwr$r$r$r%r��s
r�a�A special object which may be yielded to allow the IOLoop to run for
one iteration.

This is not needed in normal use but it can be helpful in long-running
coroutines that are likely to yield Futures that are ready instantly.

Usage: ``yield gen.moment``

In native coroutines, the equivalent of ``yield gen.moment`` is
``await asyncio.sleep(0)``.

.. versionadded:: 4.0

.. deprecated:: 4.5
   ``yield None`` (or ``yield`` with no argument) is now equivalent to
    ``yield gen.moment``.
c
@sjeZdZdZdedddddedd	f
d
d�Zddd
�Zdedefdd�Z	de
ededej
defdd�Zd	S)rNz�Internal implementation of `tornado.gen.coroutine`.

    Maintains information about pending callbacks and their results.

    The results of the generator are stored in ``result_future`` (a
    `.Future`)
    rQ�genzGenerator[_Yieldable, Any, _T]�
result_futurer>�
first_yieldedr-NcCs\||_||_||_t|_d|_d|_t��|_	|�|j
|�r,d}}}|�|j�dSdS)NF)rQr�r��_null_futurer6�running�finishedrr�r��handle_yieldrG)r\rQr�r�r�r$r$r%r[�s
�zRunner.__init__c
Csz|js|jrdSz�d|_	|j}|durtd��|��s"Wd|_dSd|_z=z!z|��}WntyA}z|}WYd}~nd}~wwd}Wd}nd}w|dur[z	|j�|�}W~n~w|j�|�}WnHt	t
fy�}zd|_t|_t|j
t|��d|_
WYd}~Wd|_dSd}~wty�d|_t|_t|j
t���d|_
YWd|_dSw|�|�s�Wd|_dSd}q
d|_w)zkStarts or resumes the generator, running until it reaches a
        yield point that is not ready.
        NTzNo pending futureF)r�r�r6rIrwrRr��throw�sendrHr,r�r
r�r2rrJrKr�)r\r6r.r+�excrSr$r$r%rG�sh
+�����
�
��
�

��0z
Runner.runrScs�zt|��_Wntyt��_t�jt���Ynw�jtur-�j�	�j
�j�dS�jdur6td���j�
�sPdtddf�fdd�}�j��j|�dSdS)NFzno pending futurer9r-csd}���j�dSr;)rQrGr�rvr$r%�innerFsz"Runner.handle_yield.<locals>.innerT)r�r6r)rrrJrK�momentr�Zadd_callbackrQrGrIrwrr�)r\rSr�r$rvr%r�8s �


zRunner.handle_yield�typr.�tbcCs:|js|jst�|_t|j|||f�|�|j�dSdS)NTF)r�r�rr6rrQrG)r\r�r.r�r$r$r%�handle_exceptionOszRunner.handle_exceptionr�)r!r"r#r_r�
_Yieldabler[rGr�r�rrI�types�
TracebackTyper�r$r$r$r%rN�s0����
�
:����rN�	awaitablecs2t�|�}t�����|�|��fdd��|S)Ncs
��|�Sr;)Z_unregister_taskr��Zloopr$r%rEdr�z!_wrap_awaitable.<locals>.<lambda>)r�Z
ensure_futurerr�Z_register_taskrO)r�r�r$r�r%�_wrap_awaitable[s


r�rScCsh|dus|tur
tS|turtSt|ttf�rt|�St|�r%t�t	|�St
|�r-t|�Std|����)a?Convert a yielded object into a `.Future`.

    The default implementation accepts lists, dictionaries, and
    Futures. This has the side effect of starting any coroutines that
    did not start themselves, similar to `asyncio.ensure_future`.

    If the `~functools.singledispatch` library is available, this function
    may be extended to support additional types. For example::

        @convert_yielded.register(asyncio.Future)
        def _(asyncio_future):
            return tornado.platform.asyncio.to_tornado_future(asyncio_future)

    .. versionadded:: 4.1

    Nzyielded unknown object )
r�r�rLrkr�r�rr��castrrr�r))rSr$r$r%r�hsr�)r$)Qr_r�rrn�collections.abcr�concurrent.futuresZ
concurrent�datetimerUr�inspectrrJr�Ztornado.concurrentrrrrr	r
Ztornado.iolooprZtornado.logrZtornado.utilr
rF�ImportErrorr�rrrrrrrrrrr�
TYPE_CHECKINGrrrr�TypeVarrrur�rIrr'r(r)r*rHr2r8r<rAr�rYr,rar�ZMultir�r��float�	timedeltar�r�r�r�r�r�rNr�r�r$r$r$r%�<module>s�? �4
�"�� �
�`	�����
������
�3���
�?����
�Qx