@ajksunkang-aios/kgraph-linux-x64 0.1.2 → 0.1.3

package/lib/site-packages/trio/_core/_ki.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import signal
+import sys
+import weakref
+from typing import TYPE_CHECKING, Generic, Protocol, TypeGuard, TypeVar
+
+import attrs
+
+from .._util import is_main_thread
+from ._run_context import GLOBAL_RUN_CONTEXT
+
+if TYPE_CHECKING:
+    import types
+    from collections.abc import Callable
+
+    from typing_extensions import Self
+# In ordinary single-threaded Python code, when you hit control-C, it raises
+# an exception and automatically does all the regular unwinding stuff.
+#
+# In Trio code, we would like hitting control-C to raise an exception and
+# automatically do all the regular unwinding stuff. In particular, we would
+# like to maintain our invariant that all tasks always run to completion (one
+# way or another), by unwinding all of them.
+#
+# But it's basically impossible to write the core task running code in such a
+# way that it can maintain this invariant in the face of KeyboardInterrupt
+# exceptions arising at arbitrary bytecode positions. Similarly, if a
+# KeyboardInterrupt happened at the wrong moment inside pretty much any of our
+# inter-task synchronization or I/O primitives, then the system state could
+# get corrupted and prevent our being able to clean up properly.
+#
+# So, we need a way to defer KeyboardInterrupt processing from these critical
+# sections.
+#
+# Things that don't work:
+#
+# - Listen for SIGINT and process it in a system task: works fine for
+#   well-behaved programs that regularly pass through the event loop, but if
+#   user-code goes into an infinite loop then it can't be interrupted. Which
+#   is unfortunate, since dealing with infinite loops is what
+#   KeyboardInterrupt is for!
+#
+# - Use pthread_sigmask to disable signal delivery during critical section:
+#   (a) windows has no pthread_sigmask, (b) python threads start with all
+#   signals unblocked, so if there are any threads around they'll receive the
+#   signal and then tell the main thread to run the handler, even if the main
+#   thread has that signal blocked.
+#
+# - Install a signal handler which checks a global variable to decide whether
+#   to raise the exception immediately (if we're in a non-critical section),
+#   or to schedule it on the event loop (if we're in a critical section). The
+#   problem here is that it's impossible to transition safely out of user code:
+#
+#     with keyboard_interrupt_enabled:
+#         msg = coro.send(value)
+#
+#   If this raises a KeyboardInterrupt, it might be because the coroutine got
+#   interrupted and has unwound... or it might be the KeyboardInterrupt
+#   arrived just *after* 'send' returned, so the coroutine is still running,
+#   but we just lost the message it sent. (And worse, in our actual task
+#   runner, the send is hidden inside a utility function etc.)
+#
+# Solution:
+#
+# Mark *stack frames* as being interrupt-safe or interrupt-unsafe, and from
+# the signal handler check which kind of frame we're currently in when
+# deciding whether to raise or schedule the exception.
+#
+# There are still some cases where this can fail, like if someone hits
+# control-C while the process is in the event loop, and then it immediately
+# enters an infinite loop in user code. In this case the user has to hit
+# control-C a second time. And of course if the user code is written so that
+# it doesn't actually exit after a task crashes and everything gets cancelled,
+# then there's not much to be done. (Hitting control-C repeatedly might help,
+# but in general the solution is to kill the process some other way, just like
+# for any Python program that's written to catch and ignore
+# KeyboardInterrupt.)
+
+_T = TypeVar("_T")
+
+
+class _IdRef(weakref.ref[_T]):
+    __slots__ = ("_hash",)
+    _hash: int
+
+    def __new__(
+        cls,
+        ob: _T,
+        callback: Callable[[Self], object] | None = None,
+        /,
+    ) -> Self:
+        self: Self = weakref.ref.__new__(cls, ob, callback)
+        self._hash = object.__hash__(ob)
+        return self
+
+    def __eq__(self, other: object) -> bool:
+        if self is other:
+            return True
+
+        if not isinstance(other, _IdRef):
+            return NotImplemented
+
+        my_obj = None
+        try:
+            my_obj = self()
+            return my_obj is not None and my_obj is other()
+        finally:
+            del my_obj
+
+    # we're overriding a builtin so we do need this
+    def __ne__(self, other: object) -> bool:
+        return not self == other
+
+    def __hash__(self) -> int:
+        return self._hash
+
+
+_KT = TypeVar("_KT")
+_VT = TypeVar("_VT")
+
+
+# see also: https://github.com/python/cpython/issues/88306
+class WeakKeyIdentityDictionary(Generic[_KT, _VT]):
+    def __init__(self) -> None:
+        self._data: dict[_IdRef[_KT], _VT] = {}
+
+        def remove(
+            k: _IdRef[_KT],
+            selfref: weakref.ref[
+                WeakKeyIdentityDictionary[_KT, _VT]
+            ] = weakref.ref(  # noqa: B008  # function-call-in-default-argument
+                self,
+            ),
+        ) -> None:
+            self = selfref()
+            if self is not None:
+                try:  # noqa: SIM105  # suppressible-exception
+                    del self._data[k]
+                except KeyError:
+                    pass
+
+        self._remove = remove
+
+    def __getitem__(self, k: _KT) -> _VT:
+        return self._data[_IdRef(k)]
+
+    def __setitem__(self, k: _KT, v: _VT) -> None:
+        self._data[_IdRef(k, self._remove)] = v
+
+
+_CODE_KI_PROTECTION_STATUS_WMAP: WeakKeyIdentityDictionary[
+    types.CodeType,
+    bool,
+] = WeakKeyIdentityDictionary()
+
+
+# This is to support the async_generator package necessary for aclosing on <3.10
+# functions decorated @async_generator are given this magic property that's a
+# reference to the object itself
+# see python-trio/async_generator/async_generator/_impl.py
+def legacy_isasyncgenfunction(
+    obj: object,
+) -> TypeGuard[Callable[..., types.AsyncGeneratorType[object, object]]]:
+    return getattr(obj, "_async_gen_function", None) == id(obj)
+
+
+# NB: according to the signal.signal docs, 'frame' can be None on entry to
+# this function:
+def ki_protection_enabled(frame: types.FrameType | None) -> bool:
+    try:
+        task = GLOBAL_RUN_CONTEXT.task
+    except AttributeError:
+        task_ki_protected = False
+        task_frame = None
+    else:
+        task_ki_protected = task._ki_protected
+        task_frame = task.coro.cr_frame
+
+    while frame is not None:
+        try:
+            v = _CODE_KI_PROTECTION_STATUS_WMAP[frame.f_code]
+        except KeyError:
+            pass
+        else:
+            return bool(v)
+        if frame.f_code.co_name == "__del__":
+            return True
+        if frame is task_frame:
+            return task_ki_protected
+        frame = frame.f_back
+    return True
+
+
+def currently_ki_protected() -> bool:
+    r"""Check whether the calling code has :exc:`KeyboardInterrupt` protection
+    enabled.
+
+    It's surprisingly easy to think that one's :exc:`KeyboardInterrupt`
+    protection is enabled when it isn't, or vice-versa. This function tells
+    you what Trio thinks of the matter, which makes it useful for ``assert``\s
+    and unit tests.
+
+    Returns:
+      bool: True if protection is enabled, and False otherwise.
+
+    """
+    return ki_protection_enabled(sys._getframe())
+
+
+class _SupportsCode(Protocol):
+    __code__: types.CodeType
+
+
+_T_supports_code = TypeVar("_T_supports_code", bound=_SupportsCode)
+
+
+def enable_ki_protection(f: _T_supports_code, /) -> _T_supports_code:
+    """Decorator to enable KI protection."""
+    orig = f
+
+    if legacy_isasyncgenfunction(f):
+        f = f.__wrapped__  # type: ignore
+
+    _CODE_KI_PROTECTION_STATUS_WMAP[f.__code__] = True
+    return orig
+
+
+def disable_ki_protection(f: _T_supports_code, /) -> _T_supports_code:
+    """Decorator to disable KI protection."""
+    orig = f
+
+    if legacy_isasyncgenfunction(f):
+        f = f.__wrapped__  # type: ignore
+
+    _CODE_KI_PROTECTION_STATUS_WMAP[f.__code__] = False
+    return orig
+
+
+@attrs.define(slots=False)
+class KIManager:
+    handler: Callable[[int, types.FrameType | None], None] | None = None
+
+    def install(
+        self,
+        deliver_cb: Callable[[], object],
+        restrict_keyboard_interrupt_to_checkpoints: bool,
+    ) -> None:
+        assert self.handler is None
+        if (
+            not is_main_thread()
+            or signal.getsignal(signal.SIGINT) != signal.default_int_handler
+        ):
+            return
+
+        def handler(signum: int, frame: types.FrameType | None) -> None:
+            assert signum == signal.SIGINT
+            protection_enabled = ki_protection_enabled(frame)
+            if protection_enabled or restrict_keyboard_interrupt_to_checkpoints:
+                deliver_cb()
+            else:
+                raise KeyboardInterrupt
+
+        self.handler = handler
+        signal.signal(signal.SIGINT, handler)
+
+    def close(self) -> None:
+        if self.handler is not None:
+            if signal.getsignal(signal.SIGINT) is self.handler:
+                signal.signal(signal.SIGINT, signal.default_int_handler)
+            self.handler = None

package/lib/site-packages/trio/_core/_local.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar, cast
+
+# Runvar implementations
+import attrs
+
+from .._util import NoPublicConstructor, final
+from . import _run
+
+T = TypeVar("T")
+
+
+@final
+class _NoValue: ...
+
+
+@final
+@attrs.define(eq=False)
+class RunVarToken(Generic[T], metaclass=NoPublicConstructor):
+    _var: RunVar[T]
+    previous_value: T | type[_NoValue] = _NoValue
+    redeemed: bool = attrs.field(default=False, init=False)
+
+    @classmethod
+    def _empty(cls, var: RunVar[T]) -> RunVarToken[T]:
+        return cls._create(var)
+
+
+@final
+@attrs.define(eq=False, repr=False)
+class RunVar(Generic[T]):
+    """The run-local variant of a context variable.
+
+    :class:`RunVar` objects are similar to context variable objects,
+    except that they are shared across a single call to :func:`trio.run`
+    rather than a single task.
+
+    """
+
+    _name: str = attrs.field(alias="name")
+    _default: T | type[_NoValue] = attrs.field(default=_NoValue, alias="default")
+
+    def get(self, default: T | type[_NoValue] = _NoValue) -> T:
+        """Gets the value of this :class:`RunVar` for the current run call."""
+        try:
+            return cast("T", _run.GLOBAL_RUN_CONTEXT.runner._locals[self])
+        except AttributeError:
+            raise RuntimeError("Cannot be used outside of a run context") from None
+        except KeyError:
+            # contextvars consistency
+            # `type: ignore` awaiting https://github.com/python/mypy/issues/15553 to be fixed & released
+            if default is not _NoValue:
+                return default  # type: ignore[return-value]
+
+            if self._default is not _NoValue:
+                return self._default  # type: ignore[return-value]
+
+            raise LookupError(self) from None
+
+    def set(self, value: T) -> RunVarToken[T]:
+        """Sets the value of this :class:`RunVar` for this current run
+        call.
+
+        """
+        try:
+            old_value = self.get()
+        except LookupError:
+            token = RunVarToken._empty(self)
+        else:
+            token = RunVarToken[T]._create(self, old_value)
+
+        # This can't fail, because if we weren't in Trio context then the
+        # get() above would have failed.
+        _run.GLOBAL_RUN_CONTEXT.runner._locals[self] = value
+        return token
+
+    def reset(self, token: RunVarToken[T]) -> None:
+        """Resets the value of this :class:`RunVar` to what it was
+        previously specified by the token.
+
+        """
+        if token is None:
+            raise TypeError("token must not be none")
+
+        if token.redeemed:
+            raise ValueError("token has already been used")
+
+        if token._var is not self:
+            raise ValueError("token is not for us")
+
+        previous = token.previous_value
+        try:
+            if previous is _NoValue:
+                _run.GLOBAL_RUN_CONTEXT.runner._locals.pop(self)
+            else:
+                _run.GLOBAL_RUN_CONTEXT.runner._locals[self] = previous
+        except AttributeError:
+            raise RuntimeError("Cannot be used outside of a run context") from None
+
+        token.redeemed = True
+
+    def __repr__(self) -> str:
+        return f"<RunVar name={self._name!r}>"

package/lib/site-packages/trio/_core/_mock_clock.py

@@ -0,0 +1,165 @@
+import time
+from math import inf
+
+from .. import _core
+from .._abc import Clock
+from .._util import final
+from ._run import GLOBAL_RUN_CONTEXT
+
+################################################################
+# The glorious MockClock
+################################################################
+
+
+# Prior art:
+#   https://twistedmatrix.com/documents/current/api/twisted.internet.task.Clock.html
+#   https://github.com/ztellman/manifold/issues/57
+@final
+class MockClock(Clock):
+    """A user-controllable clock suitable for writing tests.
+
+    Args:
+      rate (float): the initial :attr:`rate`.
+      autojump_threshold (float): the initial :attr:`autojump_threshold`.
+
+    .. attribute:: rate
+
+       How many seconds of clock time pass per second of real time. Default is
+       0.0, i.e. the clock only advances through manuals calls to :meth:`jump`
+       or when the :attr:`autojump_threshold` is triggered. You can assign to
+       this attribute to change it.
+
+    .. attribute:: autojump_threshold
+
+       The clock keeps an eye on the run loop, and if at any point it detects
+       that all tasks have been blocked for this many real seconds (i.e.,
+       according to the actual clock, not this clock), then the clock
+       automatically jumps ahead to the run loop's next scheduled
+       timeout. Default is :data:`math.inf`, i.e., to never autojump. You can
+       assign to this attribute to change it.
+
+       Basically the idea is that if you have code or tests that use sleeps
+       and timeouts, you can use this to make it run much faster, totally
+       automatically. (At least, as long as those sleeps/timeouts are
+       happening inside Trio; if your test involves talking to external
+       service and waiting for it to timeout then obviously we can't help you
+       there.)
+
+       You should set this to the smallest value that lets you reliably avoid
+       "false alarms" where some I/O is in flight (e.g. between two halves of
+       a socketpair) but the threshold gets triggered and time gets advanced
+       anyway. This will depend on the details of your tests and test
+       environment. If you aren't doing any I/O (like in our sleeping example
+       above) then just set it to zero, and the clock will jump whenever all
+       tasks are blocked.
+
+       .. note:: If you use ``autojump_threshold`` and
+          `wait_all_tasks_blocked` at the same time, then you might wonder how
+          they interact, since they both cause things to happen after the run
+          loop goes idle for some time. The answer is:
+          `wait_all_tasks_blocked` takes priority. If there's a task blocked
+          in `wait_all_tasks_blocked`, then the autojump feature treats that
+          as active task and does *not* jump the clock.
+
+    """
+
+    def __init__(self, rate: float = 0.0, autojump_threshold: float = inf) -> None:
+        # when the real clock said 'real_base', the virtual time was
+        # 'virtual_base', and since then it's advanced at 'rate' virtual
+        # seconds per real second.
+        self._real_base = 0.0
+        self._virtual_base = 0.0
+        self._rate = 0.0
+
+        # kept as an attribute so that our tests can monkeypatch it
+        self._real_clock = time.perf_counter
+
+        # use the property update logic to set initial values
+        self.rate = rate
+        self.autojump_threshold = autojump_threshold
+
+    def __repr__(self) -> str:
+        return f"<MockClock, time={self.current_time():.7f}, rate={self._rate} @ {id(self):#x}>"
+
+    @property
+    def rate(self) -> float:
+        return self._rate
+
+    @rate.setter
+    def rate(self, new_rate: float) -> None:
+        if new_rate < 0:
+            raise ValueError("rate must be >= 0")
+        else:
+            real = self._real_clock()
+            virtual = self._real_to_virtual(real)
+            self._virtual_base = virtual
+            self._real_base = real
+            self._rate = float(new_rate)
+
+    @property
+    def autojump_threshold(self) -> float:
+        return self._autojump_threshold
+
+    @autojump_threshold.setter
+    def autojump_threshold(self, new_autojump_threshold: float) -> None:
+        self._autojump_threshold = float(new_autojump_threshold)
+        self._try_resync_autojump_threshold()
+
+    # runner.clock_autojump_threshold is an internal API that isn't easily
+    # usable by custom third-party Clock objects. If you need access to this
+    # functionality, let us know, and we'll figure out how to make a public
+    # API. Discussion:
+    #
+    #     https://github.com/python-trio/trio/issues/1587
+    def _try_resync_autojump_threshold(self) -> None:
+        try:
+            runner = GLOBAL_RUN_CONTEXT.runner
+            if runner.is_guest:
+                runner.force_guest_tick_asap()
+        except AttributeError:
+            pass
+        else:
+            if runner.clock is self:
+                runner.clock_autojump_threshold = self._autojump_threshold
+
+    # Invoked by the run loop when runner.clock_autojump_threshold is
+    # exceeded.
+    def _autojump(self) -> None:
+        statistics = _core.current_statistics()
+        jump = statistics.seconds_to_next_deadline
+        if 0 < jump < inf:
+            self.jump(jump)
+
+    def _real_to_virtual(self, real: float) -> float:
+        real_offset = real - self._real_base
+        virtual_offset = self._rate * real_offset
+        return self._virtual_base + virtual_offset
+
+    def start_clock(self) -> None:
+        self._try_resync_autojump_threshold()
+
+    def current_time(self) -> float:
+        return self._real_to_virtual(self._real_clock())
+
+    def deadline_to_sleep_time(self, deadline: float) -> float:
+        virtual_timeout = deadline - self.current_time()
+        if virtual_timeout <= 0:
+            return 0
+        elif self._rate > 0:
+            return virtual_timeout / self._rate
+        else:
+            return 999999999
+
+    def jump(self, seconds: float) -> None:
+        """Manually advance the clock by the given number of seconds.
+
+        Args:
+          seconds (float): the number of seconds to jump the clock forward.
+
+        Raises:
+          ValueError: if you try to pass a negative value for ``seconds``.
+
+        """
+        if seconds < 0:
+            raise ValueError("time can't go backwards")
+        self._virtual_base += seconds