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

package/lib/site-packages/trio/_util.py

@@ -0,0 +1,385 @@
+# Little utilities we use internally
+from __future__ import annotations
+
+import collections.abc
+import inspect
+import signal
+from abc import ABCMeta
+from collections.abc import Awaitable, Callable, Sequence
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    NoReturn,
+    TypeVar,
+    final as std_final,
+)
+
+from sniffio import thread_local as sniffio_loop
+
+import trio
+
+# Explicit "Any" is not allowed
+CallT = TypeVar("CallT", bound=Callable[..., Any])  # type: ignore[explicit-any]
+T = TypeVar("T")
+RetT = TypeVar("RetT")
+
+if TYPE_CHECKING:
+    import sys
+    from types import AsyncGeneratorType, TracebackType
+
+    from typing_extensions import TypeVarTuple, Unpack
+
+    if sys.version_info < (3, 11):
+        from exceptiongroup import BaseExceptionGroup
+
+    PosArgsT = TypeVarTuple("PosArgsT")
+
+
+# See: #461 as to why this is needed.
+# The gist is that threading.main_thread() has the capability to lie to us
+# if somebody else edits the threading ident cache to replace the main
+# thread; causing threading.current_thread() to return a _DummyThread,
+# causing the C-c check to fail, and so on.
+# Trying to use signal out of the main thread will fail, so we can then
+# reliably check if this is the main thread without relying on a
+# potentially modified threading.
+def is_main_thread() -> bool:
+    """Attempt to reliably check if we are in the main thread."""
+    try:
+        signal.signal(signal.SIGINT, signal.getsignal(signal.SIGINT))
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+######
+# Call the function and get the coroutine object, while giving helpful
+# errors for common mistakes. Returns coroutine object.
+######
+def coroutine_or_error(
+    async_fn: Callable[[Unpack[PosArgsT]], Awaitable[RetT]],
+    *args: Unpack[PosArgsT],
+) -> collections.abc.Coroutine[object, NoReturn, RetT]:
+    def _return_value_looks_like_wrong_library(value: object) -> bool:
+        # Returned by legacy @asyncio.coroutine functions, which includes
+        # a surprising proportion of asyncio builtins.
+        if isinstance(value, collections.abc.Generator):
+            return True
+        # The protocol for detecting an asyncio Future-like object
+        if getattr(value, "_asyncio_future_blocking", None) is not None:
+            return True
+        # This janky check catches tornado Futures and twisted Deferreds.
+        # By the time we're calling this function, we already know
+        # something has gone wrong, so a heuristic is pretty safe.
+        return value.__class__.__name__ in ("Future", "Deferred")
+
+    # Make sure a sync-fn-that-returns-coroutine still sees itself as being
+    # in trio context
+    prev_loop, sniffio_loop.name = sniffio_loop.name, "trio"
+
+    try:
+        coro = async_fn(*args)
+
+    except TypeError:
+        # Give good error for: nursery.start_soon(trio.sleep(1))
+        if isinstance(async_fn, collections.abc.Coroutine):
+            # explicitly close coroutine to avoid RuntimeWarning
+            async_fn.close()
+
+            raise TypeError(
+                "Trio was expecting an async function, but instead it got "
+                f"a coroutine object {async_fn!r}\n"
+                "\n"
+                "Probably you did something like:\n"
+                "\n"
+                f"  trio.run({async_fn.__name__}(...))            # incorrect!\n"
+                f"  nursery.start_soon({async_fn.__name__}(...))  # incorrect!\n"
+                "\n"
+                "Instead, you want (notice the parentheses!):\n"
+                "\n"
+                f"  trio.run({async_fn.__name__}, ...)            # correct!\n"
+                f"  nursery.start_soon({async_fn.__name__}, ...)  # correct!",
+            ) from None
+
+        # Give good error for: nursery.start_soon(future)
+        if _return_value_looks_like_wrong_library(async_fn):
+            raise TypeError(
+                "Trio was expecting an async function, but instead it got "
+                f"{async_fn!r} – are you trying to use a library written for "
+                "asyncio/twisted/tornado or similar? That won't work "
+                "without some sort of compatibility shim.",
+            ) from None
+
+        raise
+
+    finally:
+        sniffio_loop.name = prev_loop
+
+    # We can't check iscoroutinefunction(async_fn), because that will fail
+    # for things like functools.partial objects wrapping an async
+    # function. So we have to just call it and then check whether the
+    # return value is a coroutine object.
+    # Note: will not be necessary on python>=3.8, see https://bugs.python.org/issue34890
+    # TODO: python3.7 support is now dropped, so the above can be addressed.
+    if not isinstance(coro, collections.abc.Coroutine):
+        # Give good error for: nursery.start_soon(func_returning_future)
+        if _return_value_looks_like_wrong_library(coro):
+            raise TypeError(
+                f"Trio got unexpected {coro!r} – are you trying to use a "
+                "library written for asyncio/twisted/tornado or similar? "
+                "That won't work without some sort of compatibility shim.",
+            )
+
+        if inspect.isasyncgen(coro):
+            raise TypeError(
+                "start_soon expected an async function but got an async "
+                f"generator {coro!r}",
+            )
+
+        # Give good error for: nursery.start_soon(some_sync_fn)
+        raise TypeError(
+            "Trio expected an async function, but {!r} appears to be "
+            "synchronous".format(getattr(async_fn, "__qualname__", async_fn)),
+        )
+
+    return coro
+
+
+class ConflictDetector:
+    """Detect when two tasks are about to perform operations that would
+    conflict.
+
+    Use as a synchronous context manager; if two tasks enter it at the same
+    time then the second one raises an error. You can use it when there are
+    two pieces of code that *would* collide and need a lock if they ever were
+    called at the same time, but that should never happen.
+
+    We use this in particular for things like, making sure that two different
+    tasks don't call sendall simultaneously on the same stream.
+
+    """
+
+    def __init__(self, msg: str) -> None:
+        self._msg = msg
+        self._held = False
+
+    def __enter__(self) -> None:
+        if self._held:
+            raise trio.BusyResourceError(self._msg)
+        else:
+            self._held = True
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self._held = False
+
+
+def async_wraps(  # type: ignore[explicit-any]
+    cls: type[object],
+    wrapped_cls: type[object],
+    attr_name: str,
+) -> Callable[[CallT], CallT]:
+    """Similar to wraps, but for async wrappers of non-async functions."""
+
+    def decorator(func: CallT) -> CallT:  # type: ignore[explicit-any]
+        func.__name__ = attr_name
+        func.__qualname__ = f"{cls.__qualname__}.{attr_name}"
+
+        func.__doc__ = f"Like :meth:`~{wrapped_cls.__module__}.{wrapped_cls.__qualname__}.{attr_name}`, but async."
+
+        return func
+
+    return decorator
+
+
+def fixup_module_metadata(
+    module_name: str,
+    namespace: collections.abc.Mapping[str, object],
+) -> None:
+    seen_ids: set[int] = set()
+
+    def fix_one(qualname: str, name: str, obj: object) -> None:
+        # avoid infinite recursion (relevant when using
+        # typing.Generic, for example)
+        if id(obj) in seen_ids:
+            return
+        seen_ids.add(id(obj))
+
+        mod = getattr(obj, "__module__", None)
+        if mod is not None and mod.startswith("trio."):
+            obj.__module__ = module_name
+            # Modules, unlike everything else in Python, put fully-qualified
+            # names into their __name__ attribute. We check for "." to avoid
+            # rewriting these.
+            if hasattr(obj, "__name__") and "." not in obj.__name__:
+                obj.__name__ = name
+                if hasattr(obj, "__qualname__"):
+                    obj.__qualname__ = qualname
+            if isinstance(obj, type):
+                for attr_name, attr_value in obj.__dict__.items():
+                    fix_one(objname + "." + attr_name, attr_name, attr_value)
+
+    for objname, obj in namespace.items():
+        if not objname.startswith("_"):  # ignore private attributes
+            fix_one(objname, objname, obj)
+
+
+def _init_final_cls(cls: type[object]) -> NoReturn:
+    """Raises an exception when a final class is subclassed."""
+    raise TypeError(f"{cls.__module__}.{cls.__qualname__} does not support subclassing")
+
+
+def _final_impl(decorated: type[T]) -> type[T]:
+    """Decorator that enforces a class to be final (i.e., subclass not allowed).
+
+    If a class uses this metaclass like this::
+
+        @final
+        class SomeClass:
+            pass
+
+    The metaclass will ensure that no subclass can be created.
+
+    Raises
+    ------
+    - TypeError if a subclass is created
+    """
+    # Override the method blindly. We're always going to raise, so it doesn't
+    # matter what the original did (if anything).
+    decorated.__init_subclass__ = classmethod(_init_final_cls)  # type: ignore[assignment]
+    # Apply the typing decorator, in 3.11+ it adds a __final__ marker attribute.
+    return std_final(decorated)
+
+
+if TYPE_CHECKING:
+    from typing import final
+else:
+    final = _final_impl
+
+
+@final  # No subclassing of NoPublicConstructor itself.
+class NoPublicConstructor(ABCMeta):
+    """Metaclass that ensures a private constructor.
+
+    If a class uses this metaclass like this::
+
+        @final
+        class SomeClass(metaclass=NoPublicConstructor):
+            pass
+
+    The metaclass will ensure that no instance can be initialized. This should always be
+    used with @final.
+
+    If you try to instantiate your class (SomeClass()), a TypeError will be thrown. Use
+    _create() instead in the class's implementation.
+
+    Raises
+    ------
+    - TypeError if an instance is created.
+    """
+
+    def __call__(cls, *args: object, **kwargs: object) -> None:
+        raise TypeError(
+            f"{cls.__module__}.{cls.__qualname__} has no public constructor",
+        )
+
+    def _create(cls: type[T], *args: object, **kwargs: object) -> T:
+        return super().__call__(*args, **kwargs)  # type: ignore
+
+
+def name_asyncgen(agen: AsyncGeneratorType[object, NoReturn]) -> str:
+    """Return the fully-qualified name of the async generator function
+    that produced the async generator iterator *agen*.
+    """
+    if not hasattr(agen, "ag_code"):  # pragma: no cover
+        return repr(agen)
+    try:
+        module = agen.ag_frame.f_globals["__name__"]
+    except (AttributeError, KeyError):
+        module = f"<{agen.ag_code.co_filename}>"
+    try:
+        qualname = agen.__qualname__
+    except AttributeError:
+        qualname = agen.ag_code.co_name
+    return f"{module}.{qualname}"
+
+
+# work around a pyright error
+if TYPE_CHECKING:
+    Fn = TypeVar("Fn", bound=Callable[..., object])  # type: ignore[explicit-any]
+
+    def wraps(  # type: ignore[explicit-any]
+        wrapped: Callable[..., object],
+        assigned: Sequence[str] = ...,
+        updated: Sequence[str] = ...,
+    ) -> Callable[[Fn], Fn]: ...
+
+else:
+    from functools import wraps  # noqa: F401  # this is re-exported
+
+
+def raise_saving_context(exc: BaseException) -> NoReturn:
+    """This helper allows re-raising an exception without __context__ being set."""
+    # cause does not need special handling, we simply avoid using `raise .. from ..`
+    # __suppress_context__ also does not need handling, it's only set if modifying cause
+    __tracebackhide__ = True
+    context = exc.__context__
+    try:
+        raise exc
+    finally:
+        exc.__context__ = context
+        del exc, context
+
+
+class MultipleExceptionError(Exception):
+    """Raised by raise_single_exception_from_group if encountering multiple
+    non-cancelled exceptions."""
+
+
+def raise_single_exception_from_group(
+    eg: BaseExceptionGroup[BaseException],
+) -> NoReturn:
+    """This function takes an exception group that is assumed to have at most
+    one non-cancelled exception, which it reraises as a standalone exception.
+
+    This exception may be an exceptiongroup itself, in which case it will not be unwrapped.
+
+    If a :exc:`KeyboardInterrupt` is encountered, a new KeyboardInterrupt is immediately
+    raised with the entire group as cause.
+
+    If the group only contains :exc:`Cancelled` it reraises the first one encountered.
+
+    It will retain context and cause of the contained exception, and entirely discard
+    the cause/context of the group(s).
+
+    If multiple non-cancelled exceptions are encountered, it raises
+    :exc:`AssertionError`.
+    """
+    # immediately bail out if there's any KI or SystemExit
+    for e in eg.exceptions:
+        if isinstance(e, (KeyboardInterrupt, SystemExit)):
+            raise type(e)(*e.args) from eg
+
+    cancelled_exception: trio.Cancelled | None = None
+    noncancelled_exception: BaseException | None = None
+
+    for e in eg.exceptions:
+        if isinstance(e, trio.Cancelled):
+            if cancelled_exception is None:
+                cancelled_exception = e
+        elif noncancelled_exception is None:
+            noncancelled_exception = e
+        else:
+            raise MultipleExceptionError(
+                "Attempted to unwrap exceptiongroup with multiple non-cancelled exceptions. This is often caused by a bug in the caller."
+            ) from eg
+
+    if noncancelled_exception is not None:
+        raise_saving_context(noncancelled_exception)
+
+    assert cancelled_exception is not None, "group can't be empty"
+    raise_saving_context(cancelled_exception)

package/lib/site-packages/trio/_version.py

@@ -0,0 +1,3 @@
+# This file is imported from __init__.py and parsed by setuptools
+
+__version__ = "0.33.0"

package/lib/site-packages/trio/_wait_for_object.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import math
+
+import trio
+
+from ._core._windows_cffi import (
+    CData,
+    ErrorCodes,
+    _handle,
+    ffi,
+    handle_array,
+    kernel32,
+    raise_winerror,
+)
+
+
+async def WaitForSingleObject(obj: int | CData) -> None:
+    """Async and cancellable variant of WaitForSingleObject. Windows only.
+
+    Args:
+      handle: A Win32 handle, as a Python integer.
+
+    Raises:
+      OSError: If the handle is invalid, e.g. when it is already closed.
+
+    """
+    # Allow ints or whatever we can convert to a win handle
+    handle = _handle(obj)
+
+    # Quick check; we might not even need to spawn a thread. The zero
+    # means a zero timeout; this call never blocks. We also exit here
+    # if the handle is already closed for some reason.
+    retcode = kernel32.WaitForSingleObject(handle, 0)
+    if retcode == ErrorCodes.WAIT_FAILED:
+        raise_winerror()
+    elif retcode != ErrorCodes.WAIT_TIMEOUT:
+        return
+
+    # Wait for a thread that waits for two handles: the handle plus a handle
+    # that we can use to cancel the thread.
+    cancel_handle = kernel32.CreateEventA(ffi.NULL, True, False, ffi.NULL)
+    try:
+        await trio.to_thread.run_sync(
+            WaitForMultipleObjects_sync,
+            handle,
+            cancel_handle,
+            abandon_on_cancel=True,
+            limiter=trio.CapacityLimiter(math.inf),
+        )
+    finally:
+        # Clean up our cancel handle. In case we get here because this task was
+        # cancelled, we also want to set the cancel_handle to stop the thread.
+        kernel32.SetEvent(cancel_handle)
+        kernel32.CloseHandle(cancel_handle)
+
+
+def WaitForMultipleObjects_sync(*handles: int | CData) -> None:
+    """Wait for any of the given Windows handles to be signaled."""
+    n = len(handles)
+    handle_arr = handle_array(n)
+    for i in range(n):
+        handle_arr[i] = handles[i]
+    timeout = 0xFFFFFFFF  # INFINITE
+    retcode = kernel32.WaitForMultipleObjects(n, handle_arr, False, timeout)  # blocking
+    if retcode == ErrorCodes.WAIT_FAILED:
+        raise_winerror()

package/lib/site-packages/trio/_windows_pipes.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from . import _core
+from ._abc import ReceiveStream, SendStream
+from ._core._windows_cffi import _handle, kernel32, raise_winerror
+from ._util import ConflictDetector, final
+
+assert sys.platform == "win32" or not TYPE_CHECKING
+
+# XX TODO: don't just make this up based on nothing.
+DEFAULT_RECEIVE_SIZE = 65536
+
+
+# See the comments on _unix_pipes._FdHolder for discussion of why we set the
+# handle to -1 when it's closed.
+class _HandleHolder:
+    def __init__(self, handle: int) -> None:
+        self.handle = -1
+        if not isinstance(handle, int):
+            raise TypeError("handle must be an int")
+        self.handle = handle
+        _core.register_with_iocp(self.handle)
+
+    @property
+    def closed(self) -> bool:
+        return self.handle == -1
+
+    def close(self) -> None:
+        if self.closed:
+            return
+        handle = self.handle
+        self.handle = -1
+        if not kernel32.CloseHandle(_handle(handle)):
+            raise_winerror()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+@final
+class PipeSendStream(SendStream):
+    """Represents a send stream over a Windows named pipe that has been
+    opened in OVERLAPPED mode.
+    """
+
+    def __init__(self, handle: int) -> None:
+        self._handle_holder = _HandleHolder(handle)
+        self._conflict_detector = ConflictDetector(
+            "another task is currently using this pipe",
+        )
+
+    async def send_all(self, data: bytes) -> None:
+        with self._conflict_detector:
+            if self._handle_holder.closed:
+                raise _core.ClosedResourceError("this pipe is already closed")
+
+            if not data:
+                await _core.checkpoint()
+                return
+
+            try:
+                written = await _core.write_overlapped(self._handle_holder.handle, data)
+            except BrokenPipeError as ex:
+                raise _core.BrokenResourceError from ex
+            # By my reading of MSDN, this assert is guaranteed to pass so long
+            # as the pipe isn't in nonblocking mode, but... let's just
+            # double-check.
+            assert written == len(data)
+
+    async def wait_send_all_might_not_block(self) -> None:
+        with self._conflict_detector:
+            if self._handle_holder.closed:
+                raise _core.ClosedResourceError("This pipe is already closed")
+
+            # not implemented yet, and probably not needed
+            await _core.checkpoint()
+
+    def close(self) -> None:
+        self._handle_holder.close()
+
+    async def aclose(self) -> None:
+        self.close()
+        await _core.checkpoint()
+
+
+@final
+class PipeReceiveStream(ReceiveStream):
+    """Represents a receive stream over an os.pipe object."""
+
+    def __init__(self, handle: int) -> None:
+        self._handle_holder = _HandleHolder(handle)
+        self._conflict_detector = ConflictDetector(
+            "another task is currently using this pipe",
+        )
+
+    async def receive_some(self, max_bytes: int | None = None) -> bytes:
+        with self._conflict_detector:
+            if self._handle_holder.closed:
+                raise _core.ClosedResourceError("this pipe is already closed")
+
+            if max_bytes is None:
+                max_bytes = DEFAULT_RECEIVE_SIZE
+            else:
+                if not isinstance(max_bytes, int):
+                    raise TypeError("max_bytes must be integer >= 1")
+                if max_bytes < 1:
+                    raise ValueError("max_bytes must be integer >= 1")
+
+            buffer = bytearray(max_bytes)
+            try:
+                size = await _core.readinto_overlapped(
+                    self._handle_holder.handle,
+                    buffer,
+                )
+            except BrokenPipeError:
+                if self._handle_holder.closed:
+                    raise _core.ClosedResourceError(
+                        "another task closed this pipe",
+                    ) from None
+
+                # Windows raises BrokenPipeError on one end of a pipe
+                # whenever the other end closes, regardless of direction.
+                # Convert this to the Unix behavior of returning EOF to the
+                # reader when the writer closes.
+                #
+                # And since we're not raising an exception, we have to
+                # checkpoint. But readinto_overlapped did raise an exception,
+                # so it might not have checkpointed for us. So we have to
+                # checkpoint manually.
+                await _core.checkpoint()
+                return b""
+            else:
+                del buffer[size:]
+                return buffer
+
+    def close(self) -> None:
+        self._handle_holder.close()
+
+    async def aclose(self) -> None:
+        self.close()
+        await _core.checkpoint()

package/lib/site-packages/trio/abc.py

@@ -0,0 +1,23 @@
+# This is a public namespace, so we don't want to expose any non-underscored
+# attributes that aren't actually part of our public API. But it's very
+# annoying to carefully always use underscored names for module-level
+# temporaries, imports, etc. when implementing the module. So we put the
+# implementation in an underscored module, and then re-export the public parts
+# here.
+
+# Uses `from x import y as y` for compatibility with `pyright --verifytypes` (#2625)
+from ._abc import (
+    AsyncResource as AsyncResource,
+    Channel as Channel,
+    Clock as Clock,
+    HalfCloseableStream as HalfCloseableStream,
+    HostnameResolver as HostnameResolver,
+    Instrument as Instrument,
+    Listener as Listener,
+    ReceiveChannel as ReceiveChannel,
+    ReceiveStream as ReceiveStream,
+    SendChannel as SendChannel,
+    SendStream as SendStream,
+    SocketFactory as SocketFactory,
+    Stream as Stream,
+)

package/lib/site-packages/trio/from_thread.py

@@ -0,0 +1,13 @@
+"""
+This namespace represents special functions that can call back into Trio from
+an external thread by means of a Trio Token present in Thread Local Storage
+"""
+
+from ._threads import (
+    from_thread_check_cancelled as check_cancelled,
+    from_thread_run as run,
+    from_thread_run_sync as run_sync,
+)
+
+# need to use __all__ for pyright --verifytypes to see re-exports when renaming them
+__all__ = ["check_cancelled", "run", "run_sync"]