Merge branch 'master' into add-pre-commit

Author: CoolCat467

docs/source/_static/hackrtd.css

@@ -12,6 +12,11 @@ pre {
     background-color: #ffe13b;
 }
 
+/* Make typevar/paramspec names distinguishable from classes. */
+.typevarref {
+    text-decoration: dashed underline;
+}
+
 /* Add a snakey triskelion ornament to <hr>
  * https://stackoverflow.com/questions/8862344/css-hr-with-ornament/18541258#18541258
  * but only do it to <hr>s in the content box, b/c the RTD popup control panel

docs/source/conf.py

@@ -44,7 +44,6 @@
 nitpick_ignore = [
     ("py:class", "CapacityLimiter-like object"),
     ("py:class", "bytes-like"),
-    ("py:class", "None"),
     # Was removed but still shows up in changelog
     ("py:class", "trio.lowlevel.RunLocal"),
     # trio.abc is documented at random places scattered throughout the docs
@@ -53,27 +52,8 @@
     ("py:exc", "Anything else"),
     ("py:class", "async function"),
     ("py:class", "sync function"),
-    # https://github.com/sphinx-doc/sphinx/issues/7722
-    # TODO: why do these need to be spelled out?
-    ("py:class", "trio._abc.ReceiveType"),
-    ("py:class", "trio._abc.SendType"),
-    ("py:class", "trio._abc.T"),
-    ("py:obj", "trio._abc.ReceiveType"),
-    ("py:obj", "trio._abc.SendType"),
-    ("py:obj", "trio._abc.T"),
-    ("py:obj", "trio._abc.T_resource"),
-    ("py:class", "trio._core._run.StatusT"),
-    ("py:class", "trio._core._run.StatusT_co"),
-    ("py:class", "trio._core._run.StatusT_contra"),
-    ("py:class", "trio._core._run.RetT"),
-    ("py:class", "trio._threads.T"),
-    ("py:class", "P.args"),
-    ("py:class", "P.kwargs"),
-    ("py:class", "RetT"),
     # why aren't these found in stdlib?
     ("py:class", "types.FrameType"),
-    # TODO: figure out if you can link this to SSL
-    ("py:class", "Context"),
     # TODO: temporary type
     ("py:class", "_SocketType"),
     # these are not defined in https://docs.python.org/3/objects.inv
@@ -91,6 +71,9 @@
     # aliasing doesn't actually fix the warning for types.FrameType, but displaying
     # "types.FrameType" is more helpful than just "frame"
     "FrameType": "types.FrameType",
+    # unaliasing these makes intersphinx able to resolve them
+    "Outcome": "outcome.Outcome",
+    "Context": "OpenSSL.SSL.Context",
 }
 
 
@@ -139,6 +122,7 @@ def setup(app):
     "sphinxcontrib_trio",
     "sphinxcontrib.jquery",
     "local_customization",
+    "typevars",
 ]
 
 intersphinx_mapping = {

docs/source/reference-io.rst

@@ -731,7 +731,11 @@ task and interact with it while it's running:
 
 .. autofunction:: trio.run_process
 
-.. autoclass:: trio.Process
+.. autoclass:: trio._subprocess.HasFileno(Protocol)
+
+   .. automethod:: fileno
+
+.. autoclass:: trio.Process()
 
    .. autoattribute:: returncode
 

docs/source/typevars.py

@@ -0,0 +1,103 @@
+"""Transform references to typevars to avoid missing reference errors.
+
+See https://github.com/sphinx-doc/sphinx/issues/7722 also.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from sphinx.addnodes import Element, pending_xref
+from sphinx.application import Sphinx
+from sphinx.environment import BuildEnvironment
+from sphinx.errors import NoUri
+
+import trio
+
+
+def identify_typevars(trio_folder: Path) -> None:
+    """Record all typevars in trio."""
+    for filename in trio_folder.rglob("*.py"):
+        with open(filename, encoding="utf8") as f:
+            for line in f:
+                # A simple regex should be sufficient to find them all, no need to actually parse.
+                match = re.search(
+                    r"\b(TypeVar|TypeVarTuple|ParamSpec)\(['\"]([^'\"]+)['\"]",
+                    line,
+                )
+                if match is not None:
+                    relative = "trio" / filename.relative_to(trio_folder)
+                    relative = relative.with_suffix("")
+                    if relative.name == "__init__":  # Package, remove.
+                        relative = relative.parent
+                    kind = match.group(1)
+                    name = match.group(2)
+                    typevars_qualified[f'{".".join(relative.parts)}.{name}'] = kind
+                    existing = typevars_named.setdefault(name, kind)
+                    if existing != kind:
+                        print("Mismatch: {} = {}, {}", name, existing, kind)
+
+
+# All our typevars, so we can suppress reference errors for them.
+typevars_qualified: dict[str, str] = {}
+typevars_named: dict[str, str] = {}
+
+
+def lookup_reference(
+    app: Sphinx,
+    env: BuildEnvironment,
+    node: pending_xref,
+    contnode: Element,
+) -> Element | None:
+    """Handle missing references."""
+    # If this is a typing_extensions object, redirect to typing.
+    # Most things there are backports, so the stdlib docs should have an entry.
+    target: str = node["reftarget"]
+    if target.startswith("typing_extensions."):
+        new_node = node.copy()
+        new_node["reftarget"] = f"typing.{target[18:]}"
+        # This fires off this same event, with our new modified node in order to fetch the right
+        # URL to use.
+        return app.emit_firstresult(
+            "missing-reference",
+            env,
+            new_node,
+            contnode,
+            allowed_exceptions=(NoUri,),
+        )
+
+    try:
+        typevar_type = typevars_qualified[target]
+    except KeyError:
+        # Imports might mean the typevar was defined in a different module or something.
+        # Fall back to checking just by name.
+        dot = target.rfind(".")
+        stem = target[dot + 1 :] if dot >= 0 else target
+        try:
+            typevar_type = typevars_named[stem]
+        except KeyError:
+            # Let other handlers deal with this name, it's not a typevar.
+            return None
+
+    # Found a typevar. Redirect to the stdlib docs for that kind of var.
+    new_node = node.copy()
+    new_node["reftarget"] = f"typing.{typevar_type}"
+    new_node = app.emit_firstresult(
+        "missing-reference",
+        env,
+        new_node,
+        contnode,
+        allowed_exceptions=(NoUri,),
+    )
+    reftitle = new_node["reftitle"]
+    # Is normally "(in Python 3.XX)", make it say typevar/paramspec/etc
+    paren = "(" if reftitle.startswith("(") else ""
+    new_node["reftitle"] = f"{paren}{typevar_type}, {reftitle.lstrip('(')}"
+    # Add a CSS class, for restyling.
+    new_node["classes"].append("typevarref")
+    return new_node
+
+
+def setup(app: Sphinx) -> None:
+    identify_typevars(Path(trio.__file__).parent)
+    app.connect("missing-reference", lookup_reference, -10)

pyproject.toml

@@ -61,23 +61,31 @@ module = [
     "trio._abc",
     "trio._core._asyncgens",
     "trio._core._entry_queue",
-    "trio._core._generated_run",
     "trio._core._generated_io_epoll",
     "trio._core._generated_io_kqueue",
+    "trio._core._generated_run",
     "trio._core._io_epoll",
     "trio._core._io_kqueue",
     "trio._core._local",
     "trio._core._multierror",
+    "trio._core._run",
     "trio._core._thread_cache",
+    "trio._core._traps",
+    "trio._core._unbounded_queue",
     "trio._core._unbounded_queue",
-    "trio._core._run",
     "trio._deprecate",
     "trio._dtls",
     "trio._file_io",
     "trio._highlevel_open_tcp_stream",
     "trio._ki",
     "trio._socket",
+    "trio._subprocess",
+    "trio._subprocess_platform",
+    "trio._subprocess_platform.kqueue",
+    "trio._subprocess_platform.waitid",
+    "trio._subprocess_platform.windows",
     "trio._sync",
+    "trio._threads",
     "trio._tools.gen_exports",
     "trio._util",
 ]

trio/_core/_traps.py

@@ -1,14 +1,21 @@
-# These are the only functions that ever yield back to the task runner.
+"""These are the only functions that ever yield back to the task runner."""
+from __future__ import annotations
 
 import enum
 import types
-from typing import Any, Callable, NoReturn
+from typing import TYPE_CHECKING, Any, Callable, NoReturn
 
 import attr
 import outcome
 
 from . import _run
 
+if TYPE_CHECKING:
+    from outcome import Outcome
+    from typing_extensions import TypeAlias
+
+    from ._run import Task
+
 
 # Helper for the bottommost 'yield'. You can't use 'yield' inside an async
 # function, but you can inside a generator, and if you decorate your generator
@@ -18,7 +25,7 @@
 # tracking machinery. Since our traps are public APIs, we make them real async
 # functions, and then this helper takes care of the actual yield:
 @types.coroutine
-def _async_yield(obj):
+def _async_yield(obj: Any) -> Any:  # type: ignore[misc]
     return (yield obj)
 
 
@@ -28,7 +35,7 @@ class CancelShieldedCheckpoint:
     pass
 
 
-async def cancel_shielded_checkpoint():
+async def cancel_shielded_checkpoint() -> None:
     """Introduce a schedule point, but not a cancel point.
 
     This is *not* a :ref:`checkpoint <checkpoints>`, but it is half of a
@@ -41,7 +48,7 @@ async def cancel_shielded_checkpoint():
             await trio.lowlevel.checkpoint()
 
     """
-    return (await _async_yield(CancelShieldedCheckpoint)).unwrap()
+    (await _async_yield(CancelShieldedCheckpoint)).unwrap()
 
 
 # Return values for abort functions
@@ -62,10 +69,10 @@ class Abort(enum.Enum):
 # Not exported in the trio._core namespace, but imported directly by _run.
 @attr.s(frozen=True)
 class WaitTaskRescheduled:
-    abort_func = attr.ib()
+    abort_func: Callable[[RaiseCancelT], Abort] = attr.ib()
 
 
-RaiseCancelT = Callable[[], NoReturn]  # TypeAlias
+RaiseCancelT: TypeAlias = Callable[[], NoReturn]
 
 
 # Should always return the type a Task "expects", unless you willfully reschedule it
@@ -175,10 +182,10 @@ def abort(inner_raise_cancel):
 # Not exported in the trio._core namespace, but imported directly by _run.
 @attr.s(frozen=True)
 class PermanentlyDetachCoroutineObject:
-    final_outcome = attr.ib()
+    final_outcome: Outcome = attr.ib()
 
 
-async def permanently_detach_coroutine_object(final_outcome):
+async def permanently_detach_coroutine_object(final_outcome: Outcome) -> Any:
     """Permanently detach the current task from the Trio scheduler.
 
     Normally, a Trio task doesn't exit until its coroutine object exits. When
@@ -209,7 +216,9 @@ async def permanently_detach_coroutine_object(final_outcome):
     return await _async_yield(PermanentlyDetachCoroutineObject(final_outcome))
 
 
-async def temporarily_detach_coroutine_object(abort_func):
+async def temporarily_detach_coroutine_object(
+    abort_func: Callable[[RaiseCancelT], Abort]
+) -> Any:
     """Temporarily detach the current coroutine object from the Trio
     scheduler.
 
@@ -245,7 +254,7 @@ async def temporarily_detach_coroutine_object(abort_func):
     return await _async_yield(WaitTaskRescheduled(abort_func))
 
 
-async def reattach_detached_coroutine_object(task, yield_value):
+async def reattach_detached_coroutine_object(task: Task, yield_value: object) -> None:
     """Reattach a coroutine object that was detached using
     :func:`temporarily_detach_coroutine_object`.