ir5dZddlmZmZmZddlmZddlmZddl m Z ddl m Z ddgZGd d eZeZGd deZd Zd S)a Timeouts. Many functions in :mod:`gevent` have a *timeout* argument that allows limiting the time the function will block. When that is not available, the :class:`Timeout` class and :func:`with_timeout` function in this module add timeouts to arbitrary code. .. warning:: Timeouts can only work when the greenlet switches to the hub. If a blocking function is called or an intense calculation is ongoing during which no switches occur, :class:`Timeout` is powerless. )absolute_importprint_functiondivision) string_types)_NONE) getcurrent)get_hub_noargsTimeout with_timeoutcneZdZdZedZeZedZexZZ dZ dZ e Z e xZ Z dZdZdS) _FakeTimercdS)NFrselfs 9/usr/local/lib/python3.11/dist-packages/gevent/timeout.pypendingz_FakeTimer.pending(sucdS)zAlways returns NoneNrrs rsecondsz_FakeTimer.seconds.src td)Nz$non-expiring timer cannot be started)AssertionError)rargskwargss rstartz_FakeTimer.start4sCDDDrcdSNrrs rstopz_FakeTimer.stop8rc|Srrrs r __enter__z_FakeTimer.__enter__?s rcdSrr)r_t_v_tbs r__exit__z_FakeTimer.__exit__BrrN)__name__ __module__ __qualname__ __slots__propertyractivertimer exceptionrrcancelcloser!r&rrrr r sI XF X EIEEEFD5rr ceZdZdZ ddZdZdZedd Ze dd Z e d Z d Z d ZdZdZdZdZdZdS)r a Timeout(seconds=None, exception=None, ref=True, priority=-1) Raise *exception* in the current greenlet after *seconds* have elapsed:: timeout = Timeout(seconds, exception) timeout.start() try: ... # exception will be raised here, after *seconds* passed since start() call finally: timeout.close() .. warning:: You must **always** call `close` on a ``Timeout`` object you have created, whether or not the code that the timeout was protecting finishes executing before the timeout elapses (whether or not the ``Timeout`` exception is raised) This ``try/finally`` construct or a ``with`` statement is a good pattern. (If the timeout object will be started again, use `cancel` instead of `close`; this is rare. You must still `close` it when you are done.) When *exception* is omitted or ``None``, the ``Timeout`` instance itself is raised:: >>> import gevent >>> gevent.Timeout(0.1).start() >>> gevent.sleep(0.2) #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ... Timeout: 0.1 seconds If the *seconds* argument is not given or is ``None`` (e.g., ``Timeout()``), then the timeout will never expire and never raise *exception*. This is convenient for creating functions which take an optional timeout parameter of their own. (Note that this is **not** the same thing as a *seconds* value of ``0``.) :: def function(args, timeout=None): "A function with an optional timeout." timer = Timeout(timeout) with timer: ... .. caution:: A *seconds* value less than ``0.0`` (e.g., ``-1``) is poorly defined. In the future, support for negative values is likely to do the same thing as a value of ``None`` or ``0`` A *seconds* value of ``0`` requests that the event loop spin and poll for I/O; it will immediately expire as soon as control returns to the event loop. .. rubric:: Use As A Context Manager To simplify starting and canceling timeouts, the ``with`` statement can be used:: with gevent.Timeout(seconds, exception) as timeout: pass # ... code block ... This is equivalent to the try/finally block above with one additional feature: if *exception* is the literal ``False``, the timeout is still raised, but the context manager suppresses it, so the code outside the with-block won't see it. This is handy for adding a timeout to the functions that don't support a *timeout* parameter themselves:: data = None with gevent.Timeout(5, False): data = mysock.makefile().readline() if data is None: ... # 5 seconds passed without reading a line else: ... # a line was read within 5 seconds .. caution:: If ``readline()`` above catches and doesn't re-raise :exc:`BaseException` (for example, with a bare ``except:``), then your timeout will fail to function and control won't be returned to you when you expect. .. rubric:: Catching Timeouts When catching timeouts, keep in mind that the one you catch may not be the one you have set (a calling function may have set its own timeout); if you are going to silence a timeout, always check that it's the instance you need:: timeout = Timeout(1) timeout.start() try: ... except Timeout as t: if t is not timeout: raise # not my timeout finally: timeout.close() .. versionchanged:: 1.1b2 If *seconds* is not given or is ``None``, no longer allocate a native timer object that will never be started. .. versionchanged:: 1.1 Add warning about negative *seconds* values. .. versionchanged:: 1.3a1 Timeout objects now have a :meth:`close` method that *must* be called when the timeout will no longer be used to properly clean up native resources. The ``with`` statement does this automatically. .. versionchanged:: 24.10.1 Timeout values can be compared to be less than an integer value, or to be less than other timeouts, e.g., ``Timeout(0) < 1`` is true. Timeouts are not absolutely ordered and support no other comparisons; this is purely for convenience and may be removed or altered in the future. NTFct|||_||_||_|t |_dStj|pd|||_dS)Ng)refpriority) BaseException__init__rr. _one_shotr r-get_hubloop)rrr.r4r5r8s rr7zTimeout.__init__sjt$$$ "" ?$DJJJ!--gn#PX-YYDJJJrc|jrtd|z|jdS|j#|jdust |jt r|}n|j}|j|jt|ddS)zSchedule the timeout.z5%r is already started; to restart it, cancel it firstNFT)update) rrrr. isinstancerr-r_on_expirationr)rthrowss rrz Timeout.starts < a !X[_!_`` ` <  F > !T^u%<%< 4>[g@h@h%<FF^F ,jllF4PPPPPrc0||dSr)throw)r prev_greenletexs rr>zTimeout._on_expirationsBrct|tr|js||S|||||}||S)aCreate a started :class:`Timeout`. This is a shortcut, the exact action depends on *timeout*'s type: * If *timeout* is a :class:`Timeout`, then call its :meth:`start` method if it's not already begun. * Otherwise, create a new :class:`Timeout` instance, passing (*timeout*, *exception*) as arguments, then call its :meth:`start` method. Returns the :class:`Timeout` instance. )r4r8)r=r rr)clstimeoutr.r4r8s r start_newzTimeout.start_news\ gw ' ' ?  N#gycYGGG rcP|tSt|||dS)NTr8)r r rG)rFr.r4s r_start_new_or_dummyzTimeout._start_new_or_dummys," ?   )SD IIIrc2|jjp |jjS)z.True if the timeout is scheduled to be raised.)r-rr,rs rrzTimeout.pending%sz!6TZ%66rcr|j|jr|dSdS)z If the timeout is pending, cancel it. Otherwise, do nothing. The timeout object can be :meth:`started ` again. If you will not start the timeout again, you should use :meth:`close` instead. N)r-rr8r0rs rr/zTimeout.cancel*s;  >  JJLLLLL  rc|j|jt|_dS)z Close the timeout and free resources. The timer cannot be started again after this method has been used. N)r-rr0r rs rr0z Timeout.close6s5   rc t|j}|jrd}nd}|jd}n d|jz}d|dt t |d|j||d S)Nz pendingz exception=%r)typer'rr.hexidr)r classnamerr.s r__repr__zTimeout.__repr__?svJJ' <  GGG > !II'$.8I.7iiRXX V_V_ahahahiirc|jdS|jdkrdnd}|j |jd|S|jdur |jd|dS|jd|d|jS) z >>> raise Timeout #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ... Timeout NrOsz secondFz (silent)z: )rr.)rsuffixs r__str__zTimeout.__str__Ks~ < 2|q((c > !$(LLL&&9 9 >U " "-1\\\666B B$(LLL&&&$..IIrc<|js||S)z^ Start and return the timer. If the timer is already started, just return it. )rrrs rr!zTimeout.__enter__]s |  JJLLL rcP|||ur |jdurdSdSdS)z Stop the timer. .. versionchanged:: 1.3a1 The underlying native timer is also stopped. This object cannot be used again. FTN)r0r.)rtypvaluetbs rr&zTimeout.__exit__es8 D==T^u444 =44rc |j|jkS#t$r( |j|kcYS#t$r tcYcYSwxYwwxYw)zw For convenience, timeouts can be compared to integers (numbers) based on their seconds value. )rAttributeError TypeErrorNotImplemented)rothers r__lt__zTimeout.__lt__qsv  &<%-/ / & & & &|e++++ & & &%%%%%% & &s' A *AAAAA)NNTr2F)NNTF)NT)r'r(r)__doc__r7rr> classmethodrG staticmethodrJr+rr/r0rVr[r!r&rfrrrr r Hs2AALIK ZZZZ(QQQ(   [(JJJ\J(77X7       j j jJJJ$    & & & & &rcT|dt}t|d} ||i||S#t$r.}||ur$|tur|cYd}~|Sd}~wwxYw#|wxYw)aZWrap a call to *function* with a timeout; if the called function fails to return before the timeout, cancel it and return a flag value, provided by *timeout_value* keyword argument. If timeout expires but *timeout_value* is not provided, raise :class:`Timeout`. Keyword argument *timeout_value* is not passed to *function*. timeout_valueTrIN)poprr rGr/)rfunctionrkwdsrkrFrCs rr r ~sHH_e44M488G 8T*T**     W}}e!;!;$$$$$$    s5A B B .B/BB  BBB'N)rg __future__rrrgevent._compatr gevent._utilrgreenletrgevent._hub_localr r9__all__objectr r6r r rrrrvs   A@@@@@@@@@''''''777777  %%%%%%%%NZ\\ t&t&t&t&t&mt&t&t&l r