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

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

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import logging
+import sys
+import warnings
+import weakref
+from typing import TYPE_CHECKING, NoReturn, TypeVar
+
+import attrs
+
+from .. import _core
+from .._util import name_asyncgen
+from . import _run
+
+# Used to log exceptions in async generator finalizers
+ASYNCGEN_LOGGER = logging.getLogger("trio.async_generator_errors")
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from types import AsyncGeneratorType
+
+    from typing_extensions import ParamSpec
+
+    _P = ParamSpec("_P")
+
+    _WEAK_ASYNC_GEN_SET = weakref.WeakSet[AsyncGeneratorType[object, NoReturn]]
+    _ASYNC_GEN_SET = set[AsyncGeneratorType[object, NoReturn]]
+else:
+    _WEAK_ASYNC_GEN_SET = weakref.WeakSet
+    _ASYNC_GEN_SET = set
+
+_R = TypeVar("_R")
+
+
+@_core.disable_ki_protection
+def _call_without_ki_protection(
+    f: Callable[_P, _R],
+    /,
+    *args: _P.args,
+    **kwargs: _P.kwargs,
+) -> _R:
+    return f(*args, **kwargs)
+
+
+@attrs.define(eq=False)
+class AsyncGenerators:
+    # Async generators are added to this set when first iterated. Any
+    # left after the main task exits will be closed before trio.run()
+    # returns.  During most of the run, this is a WeakSet so GC works.
+    # During shutdown, when we're finalizing all the remaining
+    # asyncgens after the system nursery has been closed, it's a
+    # regular set so we don't have to deal with GC firing at
+    # unexpected times.
+    alive: _WEAK_ASYNC_GEN_SET | _ASYNC_GEN_SET = attrs.Factory(_WEAK_ASYNC_GEN_SET)
+    # The ids of foreign async generators are added to this set when first
+    # iterated. Usually it is not safe to refer to ids like this, but because
+    # we're using a finalizer we can ensure ids in this set do not outlive
+    # their async generator.
+    foreign: set[int] = attrs.Factory(set)
+
+    # This collects async generators that get garbage collected during
+    # the one-tick window between the system nursery closing and the
+    # init task starting end-of-run asyncgen finalization.
+    trailing_needs_finalize: _ASYNC_GEN_SET = attrs.Factory(_ASYNC_GEN_SET)
+
+    prev_hooks: sys._asyncgen_hooks = attrs.field(init=False)
+
+    def install_hooks(self, runner: _run.Runner) -> None:
+        def firstiter(agen: AsyncGeneratorType[object, NoReturn]) -> None:
+            if hasattr(_run.GLOBAL_RUN_CONTEXT, "task"):
+                self.alive.add(agen)
+            else:
+                # An async generator first iterated outside of a Trio
+                # task doesn't belong to Trio. Probably we're in guest
+                # mode and the async generator belongs to our host.
+                # A strong set of ids is one of the only good places to
+                # remember this fact, at least until
+                # https://github.com/python/cpython/issues/85093 is implemented.
+                self.foreign.add(id(agen))
+                if self.prev_hooks.firstiter is not None:
+                    self.prev_hooks.firstiter(agen)
+
+        def finalize_in_trio_context(
+            agen: AsyncGeneratorType[object, NoReturn],
+            agen_name: str,
+        ) -> None:
+            try:
+                runner.spawn_system_task(
+                    self._finalize_one,
+                    agen,
+                    agen_name,
+                    name=f"close asyncgen {agen_name} (abandoned)",
+                )
+            except RuntimeError:
+                # There is a one-tick window where the system nursery
+                # is closed but the init task hasn't yet made
+                # self.asyncgens a strong set to disable GC. We seem to
+                # have hit it.
+                self.trailing_needs_finalize.add(agen)
+
+        @_core.enable_ki_protection
+        def finalizer(agen: AsyncGeneratorType[object, NoReturn]) -> None:
+            try:
+                self.foreign.remove(id(agen))
+            except KeyError:
+                is_ours = True
+            else:
+                is_ours = False
+
+            agen_name = name_asyncgen(agen)
+            if is_ours:
+                runner.entry_queue.run_sync_soon(
+                    finalize_in_trio_context,
+                    agen,
+                    agen_name,
+                )
+
+                # Do this last, because it might raise an exception
+                # depending on the user's warnings filter. (That
+                # exception will be printed to the terminal and
+                # ignored, since we're running in GC context.)
+                warnings.warn(
+                    f"Async generator {agen_name!r} was garbage collected before it "
+                    "had been exhausted. Surround its use in 'async with "
+                    "aclosing(...):' to ensure that it gets cleaned up as soon as "
+                    "you're done using it.",
+                    ResourceWarning,
+                    stacklevel=2,
+                    source=agen,
+                )
+            else:
+                # Not ours -> forward to the host loop's async generator finalizer
+                finalizer = self.prev_hooks.finalizer
+                if finalizer is not None:
+                    _call_without_ki_protection(finalizer, agen)
+                else:
+                    # Host has no finalizer.  Reimplement the default
+                    # Python behavior with no hooks installed: throw in
+                    # GeneratorExit, step once, raise RuntimeError if
+                    # it doesn't exit.
+                    closer = agen.aclose()
+                    try:
+                        # If the next thing is a yield, this will raise RuntimeError
+                        # which we allow to propagate
+                        _call_without_ki_protection(closer.send, None)
+                    except StopIteration:
+                        pass
+                    else:
+                        # If the next thing is an await, we get here. Give a nicer
+                        # error than the default "async generator ignored GeneratorExit"
+                        raise RuntimeError(
+                            f"Non-Trio async generator {agen_name!r} awaited something "
+                            "during finalization; install a finalization hook to "
+                            "support this, or wrap it in 'async with aclosing(...):'",
+                        )
+
+        self.prev_hooks = sys.get_asyncgen_hooks()
+        sys.set_asyncgen_hooks(firstiter=firstiter, finalizer=finalizer)  # type: ignore[arg-type]  # Finalizer doesn't use AsyncGeneratorType
+
+    async def finalize_remaining(self, runner: _run.Runner) -> None:
+        # This is called from init after shutting down the system nursery.
+        # The only tasks running at this point are init and
+        # the run_sync_soon task, and since the system nursery is closed,
+        # there's no way for user code to spawn more.
+        assert _core.current_task() is runner.init_task
+        assert len(runner.tasks) == 2
+
+        # To make async generator finalization easier to reason
+        # about, we'll shut down asyncgen garbage collection by turning
+        # the alive WeakSet into a regular set.
+        self.alive = set(self.alive)
+
+        # Process all pending run_sync_soon callbacks, in case one of
+        # them was an asyncgen finalizer that snuck in under the wire.
+        runner.entry_queue.run_sync_soon(runner.reschedule, runner.init_task)
+        await _core.wait_task_rescheduled(
+            lambda _: _core.Abort.FAILED,  # pragma: no cover
+        )
+        self.alive.update(self.trailing_needs_finalize)
+        self.trailing_needs_finalize.clear()
+
+        # None of the still-living tasks use async generators, so
+        # every async generator must be suspended at a yield point --
+        # there's no one to be doing the iteration. That's good,
+        # because aclose() only works on an asyncgen that's suspended
+        # at a yield point.  (If it's suspended at an event loop trap,
+        # because someone is in the middle of iterating it, then you
+        # get a RuntimeError on 3.8+, and a nasty surprise on earlier
+        # versions due to https://bugs.python.org/issue32526.)
+        #
+        # However, once we start aclose() of one async generator, it
+        # might start fetching the next value from another, thus
+        # preventing us from closing that other (at least until
+        # aclose() of the first one is complete).  This constraint
+        # effectively requires us to finalize the remaining asyncgens
+        # in arbitrary order, rather than doing all of them at the
+        # same time. On 3.8+ we could defer any generator with
+        # ag_running=True to a later batch, but that only catches
+        # the case where our aclose() starts after the user's
+        # asend()/etc. If our aclose() starts first, then the
+        # user's asend()/etc will raise RuntimeError, since they're
+        # probably not checking ag_running.
+        #
+        # It might be possible to allow some parallelized cleanup if
+        # we can determine that a certain set of asyncgens have no
+        # interdependencies, using gc.get_referents() and such.
+        # But just doing one at a time will typically work well enough
+        # (since each aclose() executes in a cancelled scope) and
+        # is much easier to reason about.
+
+        # It's possible that that cleanup code will itself create
+        # more async generators, so we iterate repeatedly until
+        # all are gone.
+        while self.alive:
+            batch = self.alive
+            self.alive = _ASYNC_GEN_SET()
+            for agen in batch:
+                await self._finalize_one(agen, name_asyncgen(agen))
+
+    def close(self) -> None:
+        sys.set_asyncgen_hooks(*self.prev_hooks)
+
+    async def _finalize_one(
+        self,
+        agen: AsyncGeneratorType[object, NoReturn],
+        name: object,
+    ) -> None:
+        try:
+            # This shield ensures that finalize_asyncgen never exits
+            # with an exception, not even a Cancelled. The inside
+            # is cancelled so there's no deadlock risk.
+            with _core.CancelScope(shield=True) as cancel_scope:
+                cancel_scope.cancel(
+                    reason="disallow async work when closing async generators during trio shutdown"
+                )
+                await agen.aclose()
+        except BaseException:
+            ASYNCGEN_LOGGER.exception(
+                "Exception ignored during finalization of async generator %r -- "
+                "surround your use of the generator in 'async with aclosing(...):' "
+                "to raise exceptions like this in the context where they're generated",
+                name,
+            )

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

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from types import TracebackType
+
+
+# this is used for collapsing single-exception ExceptionGroups when using
+# `strict_exception_groups=False`. Once that is retired this function can
+# be removed as well.
+def concat_tb(
+    head: TracebackType | None,
+    tail: TracebackType | None,
+) -> TracebackType | None:
+    # We have to use an iterative algorithm here, because in the worst case
+    # this might be a RecursionError stack that is by definition too deep to
+    # process by recursion!
+    head_tbs = []
+    pointer = head
+    while pointer is not None:
+        head_tbs.append(pointer)
+        pointer = pointer.tb_next
+    current_head = tail
+    for head_tb in reversed(head_tbs):
+        current_head = TracebackType(
+            current_head, head_tb.tb_frame, head_tb.tb_lasti, head_tb.tb_lineno
+        )
+    return current_head

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

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import threading
+from collections import deque
+from collections.abc import Callable
+from typing import TYPE_CHECKING, NoReturn
+
+import attrs
+
+from .. import _core
+from .._util import NoPublicConstructor, final
+from ._wakeup_socketpair import WakeupSocketpair
+
+if TYPE_CHECKING:
+    from typing_extensions import TypeVarTuple, Unpack
+
+    PosArgsT = TypeVarTuple("PosArgsT")
+
+Function = Callable[..., object]  # type: ignore[explicit-any]
+Job = tuple[Function, tuple[object, ...]]
+
+
+@attrs.define
+class EntryQueue:
+    # This used to use a queue.Queue. but that was broken, because Queues are
+    # implemented in Python, and not reentrant -- so it was thread-safe, but
+    # not signal-safe. deque is implemented in C, so each operation is atomic
+    # WRT threads (and this is guaranteed in the docs), AND each operation is
+    # atomic WRT signal delivery (signal handlers can run on either side, but
+    # not *during* a deque operation). dict makes similar guarantees - and
+    # it's even ordered!
+    queue: deque[Job] = attrs.Factory(deque)
+    idempotent_queue: dict[Job, None] = attrs.Factory(dict)
+
+    wakeup: WakeupSocketpair = attrs.Factory(WakeupSocketpair)
+    done: bool = False
+    # Must be a reentrant lock, because it's acquired from signal handlers.
+    # RLock is signal-safe as of cpython 3.2. NB that this does mean that the
+    # lock is effectively *disabled* when we enter from signal context. The
+    # way we use the lock this is OK though, because when
+    # run_sync_soon is called from a signal it's atomic WRT the
+    # main thread -- it just might happen at some inconvenient place. But if
+    # you look at the one place where the main thread holds the lock, it's
+    # just to make 1 assignment, so that's atomic WRT a signal anyway.
+    lock: threading.RLock = attrs.Factory(threading.RLock)
+
+    async def task(self) -> None:
+        assert _core.currently_ki_protected()
+        # RLock has two implementations: a signal-safe version in _thread, and
+        # and signal-UNsafe version in threading. We need the signal safe
+        # version. Python 3.2 and later should always use this anyway, but,
+        # since the symptoms if this goes wrong are just "weird rare
+        # deadlocks", then let's make a little check.
+        # See:
+        #     https://bugs.python.org/issue13697#msg237140
+        assert self.lock.__class__.__module__ == "_thread"
+
+        def run_cb(job: Job) -> None:
+            # We run this with KI protection enabled; it's the callback's
+            # job to disable it if it wants it disabled. Exceptions are
+            # treated like system task exceptions (i.e., converted into
+            # TrioInternalError and cause everything to shut down).
+            sync_fn, args = job
+            try:
+                sync_fn(*args)
+            except BaseException as exc:
+
+                async def kill_everything(  # noqa: RUF029  # await not used
+                    exc: BaseException,
+                ) -> NoReturn:
+                    raise exc
+
+                try:
+                    _core.spawn_system_task(kill_everything, exc)
+                except RuntimeError:
+                    # We're quite late in the shutdown process and the
+                    # system nursery is already closed.
+                    # TODO(2020-06): this is a gross hack and should
+                    # be fixed soon when we address #1607.
+                    parent_nursery = _core.current_task().parent_nursery
+                    if parent_nursery is None:
+                        raise AssertionError(
+                            "Internal error: `parent_nursery` should never be `None`",
+                        ) from exc  # pragma: no cover
+                    parent_nursery.start_soon(kill_everything, exc)
+
+        # This has to be carefully written to be safe in the face of new items
+        # being queued while we iterate, and to do a bounded amount of work on
+        # each pass:
+        def run_all_bounded() -> None:
+            for _ in range(len(self.queue)):
+                run_cb(self.queue.popleft())
+            for job in list(self.idempotent_queue):
+                del self.idempotent_queue[job]
+                run_cb(job)
+
+        try:
+            while True:
+                run_all_bounded()
+                if not self.queue and not self.idempotent_queue:
+                    await self.wakeup.wait_woken()
+                else:
+                    await _core.checkpoint()
+        except _core.Cancelled:
+            # Keep the work done with this lock held as minimal as possible,
+            # because it doesn't protect us against concurrent signal delivery
+            # (see the comment above). Notice that this code would still be
+            # correct if written like:
+            #   self.done = True
+            #   with self.lock:
+            #       pass
+            # because all we want is to force run_sync_soon
+            # to either be completely before or completely after the write to
+            # done. That's why we don't need the lock to protect
+            # against signal handlers.
+            with self.lock:
+                self.done = True
+            # No more jobs will be submitted, so just clear out any residual
+            # ones:
+            run_all_bounded()
+            assert not self.queue
+            assert not self.idempotent_queue
+
+    def close(self) -> None:
+        self.wakeup.close()
+
+    def size(self) -> int:
+        return len(self.queue) + len(self.idempotent_queue)
+
+    def run_sync_soon(
+        self,
+        sync_fn: Callable[[Unpack[PosArgsT]], object],
+        *args: Unpack[PosArgsT],
+        idempotent: bool = False,
+    ) -> None:
+        with self.lock:
+            if self.done:
+                raise _core.RunFinishedError("run() has exited")
+            # We have to hold the lock all the way through here, because
+            # otherwise the main thread might exit *while* we're doing these
+            # calls, and then our queue item might not be processed, or the
+            # wakeup call might trigger an OSError b/c the IO manager has
+            # already been shut down.
+            if idempotent:
+                self.idempotent_queue[sync_fn, args] = None
+            else:
+                self.queue.append((sync_fn, args))
+            self.wakeup.wakeup_thread_and_signal_safe()
+
+
+@final
+@attrs.define(eq=False)
+class TrioToken(metaclass=NoPublicConstructor):
+    """An opaque object representing a single call to :func:`trio.run`.
+
+    It has no public constructor; instead, see :func:`current_trio_token`.
+
+    This object has two uses:
+
+    1. It lets you re-enter the Trio run loop from external threads or signal
+       handlers. This is the low-level primitive that :func:`trio.to_thread`
+       and `trio.from_thread` use to communicate with worker threads, that
+       `trio.open_signal_receiver` uses to receive notifications about
+       signals, and so forth.
+
+    2. Each call to :func:`trio.run` has exactly one associated
+       :class:`TrioToken` object, so you can use it to identify a particular
+       call.
+
+    """
+
+    _reentry_queue: EntryQueue
+
+    def run_sync_soon(
+        self,
+        sync_fn: Callable[[Unpack[PosArgsT]], object],
+        *args: Unpack[PosArgsT],
+        idempotent: bool = False,
+    ) -> None:
+        """Schedule a call to ``sync_fn(*args)`` to occur in the context of a
+        Trio task.
+
+        This is safe to call from the main thread, from other threads, and
+        from signal handlers. This is the fundamental primitive used to
+        re-enter the Trio run loop from outside of it.
+
+        The call will happen "soon", but there's no guarantee about exactly
+        when, and no mechanism provided for finding out when it's happened.
+        If you need this, you'll have to build your own.
+
+        The call is effectively run as part of a system task (see
+        :func:`~trio.lowlevel.spawn_system_task`). In particular this means
+        that:
+
+        * :exc:`KeyboardInterrupt` protection is *enabled* by default; if
+          you want ``sync_fn`` to be interruptible by control-C, then you
+          need to use :func:`~trio.lowlevel.disable_ki_protection`
+          explicitly.
+
+        * If ``sync_fn`` raises an exception, then it's converted into a
+          :exc:`~trio.TrioInternalError` and *all* tasks are cancelled. You
+          should be careful that ``sync_fn`` doesn't crash.
+
+        All calls with ``idempotent=False`` are processed in strict
+        first-in first-out order.
+
+        If ``idempotent=True``, then ``sync_fn`` and ``args`` must be
+        hashable, and Trio will make a best-effort attempt to discard any
+        call submission which is equal to an already-pending call. Trio
+        will process these in first-in first-out order.
+
+        Any ordering guarantees apply separately to ``idempotent=False``
+        and ``idempotent=True`` calls; there's no rule for how calls in the
+        different categories are ordered with respect to each other.
+
+        :raises trio.RunFinishedError:
+              if the associated call to :func:`trio.run`
+              has already exited. (Any call that *doesn't* raise this error
+              is guaranteed to be fully processed before :func:`trio.run`
+              exits.)
+
+        """
+        self._reentry_queue.run_sync_soon(sync_fn, *args, idempotent=idempotent)

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

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, Literal, TypeAlias
+
+import attrs
+
+from trio._util import NoPublicConstructor, final
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from typing_extensions import Self
+
+CancelReasonLiteral: TypeAlias = Literal[
+    "KeyboardInterrupt",
+    "deadline",
+    "explicit",
+    "nursery",
+    "shutdown",
+    "unknown",
+]
+
+
+class TrioInternalError(Exception):
+    """Raised by :func:`run` if we encounter a bug in Trio, or (possibly) a
+    misuse of one of the low-level :mod:`trio.lowlevel` APIs.
+
+    This should never happen! If you get this error, please file a bug.
+
+    Unfortunately, if you get this error it also means that all bets are off –
+    Trio doesn't know what is going on and its normal invariants may be void.
+    (For example, we might have "lost track" of a task. Or lost track of all
+    tasks.) Again, though, this shouldn't happen.
+
+    """
+
+
+class RunFinishedError(RuntimeError):
+    """Raised by `trio.from_thread.run` and similar functions if the
+    corresponding call to :func:`trio.run` has already finished.
+
+    """
+
+
+class WouldBlock(Exception):
+    """Raised by ``X_nowait`` functions if ``X`` would block."""
+
+
+@final
+@attrs.define(eq=False, kw_only=True)
+class Cancelled(BaseException, metaclass=NoPublicConstructor):
+    """Raised by blocking calls if the surrounding scope has been cancelled.
+
+    You should let this exception propagate, to be caught by the relevant
+    cancel scope. To remind you of this, it inherits from :exc:`BaseException`
+    instead of :exc:`Exception`, just like :exc:`KeyboardInterrupt` and
+    :exc:`SystemExit` do. This means that if you write something like::
+
+       try:
+           ...
+       except Exception:
+           ...
+
+    then this *won't* catch a :exc:`Cancelled` exception.
+
+    You cannot raise :exc:`Cancelled` yourself. Attempting to do so
+    will produce a :exc:`TypeError`. Use :meth:`cancel_scope.cancel()
+    <trio.CancelScope.cancel>` instead.
+
+    .. note::
+
+       In the US it's also common to see this word spelled "canceled", with
+       only one "l". This is a `recent
+       <https://books.google.com/ngrams/graph?content=canceled%2Ccancelled&year_start=1800&year_end=2000&corpus=5&smoothing=3&direct_url=t1%3B%2Ccanceled%3B%2Cc0%3B.t1%3B%2Ccancelled%3B%2Cc0>`__
+       and `US-specific
+       <https://books.google.com/ngrams/graph?content=canceled%2Ccancelled&year_start=1800&year_end=2000&corpus=18&smoothing=3&share=&direct_url=t1%3B%2Ccanceled%3B%2Cc0%3B.t1%3B%2Ccancelled%3B%2Cc0>`__
+       innovation, and even in the US both forms are still commonly used. So
+       for consistency with the rest of the world and with "cancellation"
+       (which always has two "l"s), Trio uses the two "l" spelling
+       everywhere.
+
+    """
+
+    source: CancelReasonLiteral = "unknown"
+    # repr(Task), so as to avoid gc troubles from holding a reference
+    source_task: str | None = None
+    reason: str | None = None
+
+    def __str__(self) -> str:
+        return (
+            f"cancelled due to {self.source}"
+            + ("" if self.reason is None else f" with reason {self.reason!r}")
+            + ("" if self.source_task is None else f" from task {self.source_task}")
+        )
+
+    def __reduce__(self) -> tuple[Callable[[], Cancelled], tuple[()]]:
+        # The `__reduce__` tuple does not support directly passing kwargs, and the
+        # kwargs are required so we can't use the third item for adding to __dict__,
+        # so we use partial.
+        return (
+            partial(
+                Cancelled._create,
+                source=self.source,
+                source_task=self.source_task,
+                reason=self.reason,
+            ),
+            (),
+        )
+
+    if TYPE_CHECKING:
+        # for type checking on internal code
+        @classmethod
+        def _create(
+            cls,
+            *,
+            source: CancelReasonLiteral = "unknown",
+            source_task: str | None = None,
+            reason: str | None = None,
+        ) -> Self: ...
+
+
+class BusyResourceError(Exception):
+    """Raised when a task attempts to use a resource that some other task is
+    already using, and this would lead to bugs and nonsense.
+
+    For example, if two tasks try to send data through the same socket at the
+    same time, Trio will raise :class:`BusyResourceError` instead of letting
+    the data get scrambled.
+
+    """
+
+
+class ClosedResourceError(Exception):
+    """Raised when attempting to use a resource after it has been closed.
+
+    Note that "closed" here means that *your* code closed the resource,
+    generally by calling a method with a name like ``close`` or ``aclose``, or
+    by exiting a context manager. If a problem arises elsewhere – for example,
+    because of a network failure, or because a remote peer closed their end of
+    a connection – then that should be indicated by a different exception
+    class, like :exc:`BrokenResourceError` or an :exc:`OSError` subclass.
+
+    """
+
+
+class BrokenResourceError(Exception):
+    """Raised when an attempt to use a resource fails due to external
+    circumstances.
+
+    For example, you might get this if you try to send data on a stream where
+    the remote side has already closed the connection.
+
+    You *don't* get this error if *you* closed the resource – in that case you
+    get :class:`ClosedResourceError`.
+
+    This exception's ``__cause__`` attribute will often contain more
+    information about the underlying error.
+
+    """
+
+
+class EndOfChannel(Exception):
+    """Raised when trying to receive from a :class:`trio.abc.ReceiveChannel`
+    that has no more data to receive.
+
+    This is analogous to an "end-of-file" condition, but for channels.
+
+    """