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

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

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import math
+import sys
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, NoReturn
+
+import trio
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+def move_on_at(deadline: float, *, shield: bool = False) -> trio.CancelScope:
+    """Use as a context manager to create a cancel scope with the given
+    absolute deadline.
+
+    Args:
+      deadline (float): The deadline.
+      shield (bool): Initial value for the `~trio.CancelScope.shield` attribute
+          of the newly created cancel scope.
+
+    Raises:
+      ValueError: if deadline is NaN.
+
+    """
+    # CancelScope validates that deadline isn't math.nan
+    return trio.CancelScope(deadline=deadline, shield=shield)
+
+
+def move_on_after(
+    seconds: float,
+    *,
+    shield: bool = False,
+) -> trio.CancelScope:
+    """Use as a context manager to create a cancel scope whose deadline is
+    set to now + *seconds*.
+
+    The deadline of the cancel scope is calculated upon entering.
+
+    Args:
+      seconds (float): The timeout.
+      shield (bool): Initial value for the `~trio.CancelScope.shield` attribute
+          of the newly created cancel scope.
+
+    Raises:
+      ValueError: if ``seconds`` is less than zero or NaN.
+
+    """
+    # duplicate validation logic to have the correct parameter name
+    if seconds < 0:
+        raise ValueError("`seconds` must be non-negative")
+    if math.isnan(seconds):
+        raise ValueError("`seconds` must not be NaN")
+    return trio.CancelScope(
+        shield=shield,
+        relative_deadline=seconds,
+    )
+
+
+async def sleep_forever() -> NoReturn:
+    """Pause execution of the current task forever (or until cancelled).
+
+    Equivalent to calling ``await sleep(math.inf)``, except that if manually
+    rescheduled this will raise a `RuntimeError`.
+
+    Raises:
+      RuntimeError: if rescheduled
+
+    """
+    await trio.lowlevel.wait_task_rescheduled(lambda _: trio.lowlevel.Abort.SUCCEEDED)
+    raise RuntimeError("Should never have been rescheduled!")
+
+
+async def sleep_until(deadline: float) -> None:
+    """Pause execution of the current task until the given time.
+
+    The difference between :func:`sleep` and :func:`sleep_until` is that the
+    former takes a relative time and the latter takes an absolute time
+    according to Trio's internal clock (as returned by :func:`current_time`).
+
+    Args:
+        deadline (float): The time at which we should wake up again. May be in
+            the past, in which case this function executes a checkpoint but
+            does not block.
+
+    Raises:
+      ValueError: if deadline is NaN.
+
+    """
+    with move_on_at(deadline):
+        await sleep_forever()
+
+
+async def sleep(seconds: float) -> None:
+    """Pause execution of the current task for the given number of seconds.
+
+    Args:
+        seconds (float): The number of seconds to sleep. May be zero to
+            insert a checkpoint without actually blocking.
+
+    Raises:
+        ValueError: if *seconds* is negative or NaN.
+
+    """
+    if seconds < 0:
+        raise ValueError("`seconds` must be non-negative")
+    if seconds == 0:
+        await trio.lowlevel.checkpoint()
+    else:
+        await sleep_until(trio.current_time() + seconds)
+
+
+class TooSlowError(Exception):
+    """Raised by :func:`fail_after` and :func:`fail_at` if the timeout
+    expires.
+
+    """
+
+
+@contextmanager
+def fail_at(
+    deadline: float,
+    *,
+    shield: bool = False,
+) -> Generator[trio.CancelScope, None, None]:
+    """Creates a cancel scope with the given deadline, and raises an error if it
+    is actually cancelled.
+
+    This function and :func:`move_on_at` are similar in that both create a
+    cancel scope with a given absolute deadline, and if the deadline expires
+    then both will cause :exc:`Cancelled` to be raised within the scope. The
+    difference is that when the :exc:`Cancelled` exception reaches
+    :func:`move_on_at`, it's caught and discarded. When it reaches
+    :func:`fail_at`, then it's caught and :exc:`TooSlowError` is raised in its
+    place.
+
+    Args:
+      deadline (float): The deadline.
+      shield (bool): Initial value for the `~trio.CancelScope.shield` attribute
+          of the newly created cancel scope.
+
+    Raises:
+      TooSlowError: if a :exc:`Cancelled` exception is raised in this scope
+        and caught by the context manager.
+      ValueError: if deadline is NaN.
+
+    """
+    with move_on_at(deadline, shield=shield) as scope:
+        yield scope
+    if scope.cancelled_caught:
+        raise TooSlowError
+
+
+@contextmanager
+def fail_after(
+    seconds: float,
+    *,
+    shield: bool = False,
+) -> Generator[trio.CancelScope, None, None]:
+    """Creates a cancel scope with the given timeout, and raises an error if
+    it is actually cancelled.
+
+    This function and :func:`move_on_after` are similar in that both create a
+    cancel scope with a given timeout, and if the timeout expires then both
+    will cause :exc:`Cancelled` to be raised within the scope. The difference
+    is that when the :exc:`Cancelled` exception reaches :func:`move_on_after`,
+    it's caught and discarded. When it reaches :func:`fail_after`, then it's
+    caught and :exc:`TooSlowError` is raised in its place.
+
+    The deadline of the cancel scope is calculated upon entering.
+
+    Args:
+      seconds (float): The timeout.
+      shield (bool): Initial value for the `~trio.CancelScope.shield` attribute
+          of the newly created cancel scope.
+
+    Raises:
+      TooSlowError: if a :exc:`Cancelled` exception is raised in this scope
+        and caught by the context manager.
+      ValueError: if *seconds* is less than zero or NaN.
+
+    """
+    with move_on_after(seconds, shield=shield) as scope:
+        yield scope
+    if scope.cancelled_caught:
+        raise TooSlowError
+
+
+# Users don't need to know that fail_at & fail_after wraps move_on_at and move_on_after
+# and there is no functional difference. So we replace the return value when generating
+# documentation.
+if "sphinx.ext.autodoc" in sys.modules:
+    import inspect
+
+    for c in (fail_at, fail_after):
+        c.__signature__ = inspect.Signature.from_callable(c).replace(return_annotation=trio.CancelScope)  # type: ignore[union-attr]

package/lib/site-packages/trio/_tools/gen_exports.py

@@ -0,0 +1,401 @@
+#! /usr/bin/env python3
+"""
+Code generation script for class methods
+to be exported as public API
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import os
+import subprocess
+import sys
+from pathlib import Path
+from textwrap import indent
+from typing import TYPE_CHECKING, TypeGuard
+
+import attrs
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+# keep these imports up to date with conditional imports in test_gen_exports
+# isort: split
+import astor
+
+PREFIX = "_generated"
+
+HEADER = """# ***********************************************************
+# ******* WARNING: AUTOGENERATED! ALL EDITS WILL BE LOST ******
+# *************************************************************
+from __future__ import annotations
+
+import sys
+
+from ._ki import enable_ki_protection
+from ._run import GLOBAL_RUN_CONTEXT
+"""
+
+TEMPLATE = """try:
+    return{}GLOBAL_RUN_CONTEXT.{}.{}
+except AttributeError:
+    raise RuntimeError("must be called from async context") from None
+"""
+
+
+@attrs.define
+class File:
+    path: Path
+    modname: str
+    platform: str = attrs.field(default="", kw_only=True)
+    imports: str = attrs.field(default="", kw_only=True)
+
+
+def is_function(node: ast.AST) -> TypeGuard[ast.FunctionDef | ast.AsyncFunctionDef]:
+    """Check if the AST node is either a function
+    or an async function
+    """
+    return isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+
+
+def is_public(node: ast.AST) -> TypeGuard[ast.FunctionDef | ast.AsyncFunctionDef]:
+    """Check if the AST node has a _public decorator"""
+    if is_function(node):
+        for decorator in node.decorator_list:
+            if isinstance(decorator, ast.Name) and decorator.id == "_public":
+                return True
+    return False
+
+
+def get_public_methods(
+    tree: ast.AST,
+) -> Iterator[ast.FunctionDef | ast.AsyncFunctionDef]:
+    """Return a list of methods marked as public.
+    The function walks the given tree and extracts
+    all objects that are functions which are marked
+    public.
+    """
+    for node in ast.walk(tree):
+        if is_public(node):
+            yield node
+
+
+def create_passthrough_args(funcdef: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    """Given a function definition, create a string that represents taking all
+    the arguments from the function, and passing them through to another
+    invocation of the same function.
+
+    Example input: ast.parse("def f(a, *, b): ...")
+    Example output: "(a, b=b)"
+    """
+    call_args = [arg.arg for arg in funcdef.args.args]
+    if funcdef.args.vararg:
+        call_args.append("*" + funcdef.args.vararg.arg)
+    for arg in funcdef.args.kwonlyargs:
+        call_args.append(arg.arg + "=" + arg.arg)  # noqa: PERF401  # clarity
+    if funcdef.args.kwarg:
+        call_args.append("**" + funcdef.args.kwarg.arg)
+    return "({})".format(", ".join(call_args))
+
+
+def run_black(file: File, source: str) -> tuple[bool, str]:
+    """Run black on the specified file.
+
+    Returns:
+      Tuple of success and result string.
+      ex.:
+        (False, "Failed to run black!\nerror: cannot format ...")
+        (True, "<formatted source>")
+
+    Raises:
+      ImportError: If black is not installed.
+    """
+    # imported to check that `subprocess` calls will succeed
+    import black  # noqa: F401
+
+    # Black has an undocumented API, but it doesn't easily allow reading configuration from
+    # pyproject.toml, and simultaneously pass in / receive the code as a string.
+    # https://github.com/psf/black/issues/779
+    result = subprocess.run(
+        # "-" as a filename = use stdin, return on stdout.
+        [sys.executable, "-m", "black", "--stdin-filename", file.path, "-"],
+        input=source,
+        capture_output=True,
+        encoding="utf8",
+    )
+
+    if result.returncode != 0:
+        return False, f"Failed to run black!\n{result.stderr}"
+    return True, result.stdout
+
+
+def run_ruff(file: File, source: str) -> tuple[bool, str]:
+    """Run ruff on the specified file.
+
+    Returns:
+      Tuple of success and result string.
+      ex.:
+        (False, "Failed to run ruff!\nerror: Failed to parse ...")
+        (True, "<formatted source>")
+
+    Raises:
+      ImportError: If ruff is not installed.
+    """
+    # imported to check that `subprocess` calls will succeed
+    import ruff  # noqa: F401
+
+    result = subprocess.run(
+        # "-" as a filename = use stdin, return on stdout.
+        [
+            sys.executable,
+            "-m",
+            "ruff",
+            "check",
+            "--fix",
+            "--unsafe-fixes",
+            "--stdin-filename",
+            file.path,
+            "-",
+        ],
+        input=source,
+        capture_output=True,
+        encoding="utf8",
+    )
+
+    if result.returncode != 0:
+        return False, f"Failed to run ruff!\n{result.stderr}"
+    return True, result.stdout
+
+
+def run_linters(file: File, source: str) -> str:
+    """Format the specified file using black and ruff.
+
+    Returns:
+      Formatted source code.
+
+    Raises:
+      ImportError: If either is not installed.
+      SystemExit: If either failed.
+    """
+
+    for fn in (run_black, run_ruff):
+        success, source = fn(file, source)
+        if not success:
+            print(source)
+            sys.exit(1)
+
+    return source
+
+
+def gen_public_wrappers_source(file: File) -> str:
+    """Scan the given .py file for @_public decorators, and generate wrapper
+    functions.
+
+    """
+    header = [HEADER]
+    header.append(file.imports)
+    if file.platform:
+        # Simple checks to avoid repeating imports. If this messes up, type checkers/tests will
+        # just give errors.
+        if "TYPE_CHECKING" not in file.imports:
+            header.append("from typing import TYPE_CHECKING\n")
+        if "import sys" not in file.imports:  # pragma: no cover
+            header.append("import sys\n")
+        header.append(
+            f'\nassert not TYPE_CHECKING or sys.platform=="{file.platform}"\n',
+        )
+
+    generated = ["".join(header)]
+
+    source = astor.code_to_ast.parse_file(file.path)
+    method_names = []
+    for method in get_public_methods(source):
+        # Remove self from arguments
+        assert method.args.args[0].arg == "self"
+        del method.args.args[0]
+        method_names.append(method.name)
+
+        for dec in method.decorator_list:  # pragma: no cover
+            if isinstance(dec, ast.Name) and dec.id == "contextmanager":
+                is_cm = True
+                break
+        else:
+            is_cm = False
+
+        # Remove decorators
+        method.decorator_list = [ast.Name("enable_ki_protection")]
+
+        # Create pass through arguments
+        new_args = create_passthrough_args(method)
+
+        # Remove method body without the docstring
+        if ast.get_docstring(method) is None:
+            del method.body[:]
+        else:
+            # The first entry is always the docstring
+            del method.body[1:]
+
+        # Create the function definition including the body
+        func = astor.to_source(method, indent_with=" " * 4)
+
+        if is_cm:  # pragma: no cover
+            func = func.replace("->Iterator", "->AbstractContextManager")
+
+        # Create export function body
+        template = TEMPLATE.format(
+            " await " if isinstance(method, ast.AsyncFunctionDef) else " ",
+            file.modname,
+            method.name + new_args,
+        )
+
+        # Assemble function definition arguments and body
+        snippet = func + indent(template, " " * 4)
+
+        # Append the snippet to the corresponding module
+        generated.append(snippet)
+
+    method_names.sort()
+    # Insert after the header, before function definitions
+    generated.insert(1, f"__all__ = {method_names!r}")
+    return "\n\n".join(generated)
+
+
+def matches_disk_files(new_files: dict[str, str]) -> bool:
+    for new_path, new_source in new_files.items():
+        if not os.path.exists(new_path):
+            return False
+        old_source = Path(new_path).read_text(encoding="utf-8")
+        if old_source != new_source:
+            return False
+    return True
+
+
+def process(files: Iterable[File], *, do_test: bool) -> None:
+    new_files = {}
+    for file in files:
+        print("Scanning:", file.path)
+        new_source = gen_public_wrappers_source(file)
+        new_source = run_linters(file, new_source)
+        dirname, basename = os.path.split(file.path)
+        new_path = os.path.join(dirname, PREFIX + basename)
+        new_files[new_path] = new_source
+    matches_disk = matches_disk_files(new_files)
+    if do_test:
+        if not matches_disk:
+            print("Generated sources are outdated. Please regenerate.")
+            sys.exit(1)
+        else:
+            print("Generated sources are up to date.")
+    else:
+        for new_path, new_source in new_files.items():
+            Path(new_path).write_text(new_source, encoding="utf-8", newline="\n")
+        print("Regenerated sources successfully.")
+        if not matches_disk:  # TODO: test this branch
+            # With pre-commit integration, show that we edited files.
+            sys.exit(1)
+
+
+# This is in fact run in CI, but only in the formatting check job, which
+# doesn't collect coverage.
+def main() -> None:  # pragma: no cover
+    parser = argparse.ArgumentParser(
+        description="Generate python code for public api wrappers",
+    )
+    parser.add_argument(
+        "--test",
+        "-t",
+        action="store_true",
+        help="test if code is still up to date",
+    )
+    parsed_args = parser.parse_args()
+
+    source_root = Path.cwd()
+    # Double-check we found the right directory
+    assert (source_root / "LICENSE").exists()
+    core = source_root / "src/trio/_core"
+    to_wrap = [
+        File(core / "_run.py", "runner", imports=IMPORTS_RUN),
+        File(
+            core / "_instrumentation.py",
+            "runner.instruments",
+            imports=IMPORTS_INSTRUMENT,
+        ),
+        File(
+            core / "_io_windows.py",
+            "runner.io_manager",
+            platform="win32",
+            imports=IMPORTS_WINDOWS,
+        ),
+        File(
+            core / "_io_epoll.py",
+            "runner.io_manager",
+            platform="linux",
+            imports=IMPORTS_EPOLL,
+        ),
+        File(
+            core / "_io_kqueue.py",
+            "runner.io_manager",
+            platform="darwin",
+            imports=IMPORTS_KQUEUE,
+        ),
+    ]
+
+    process(to_wrap, do_test=parsed_args.test)
+
+
+IMPORTS_RUN = """\
+from collections.abc import Awaitable, Callable
+from typing import Any, TYPE_CHECKING
+
+import outcome
+import contextvars
+
+from ._run import _NO_SEND, RunStatistics, Task
+from ._entry_queue import TrioToken
+from .._abc import Clock
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+    from ._run import PosArgT
+"""
+IMPORTS_INSTRUMENT = """\
+from ._instrumentation import Instrument
+"""
+
+IMPORTS_EPOLL = """\
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .._file_io import _HasFileNo
+"""
+
+IMPORTS_KQUEUE = """\
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import select
+    from collections.abc import Callable
+    from contextlib import AbstractContextManager
+
+    from .. import _core
+    from .._file_io import _HasFileNo
+    from ._traps import Abort, RaiseCancelT
+"""
+
+IMPORTS_WINDOWS = """\
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from contextlib import AbstractContextManager
+
+    from typing_extensions import Buffer
+
+    from .._file_io import _HasFileNo
+    from ._unbounded_queue import UnboundedQueue
+    from ._windows_cffi import Handle, CData
+"""
+
+
+if __name__ == "__main__":
+    main()