lots of typing improvements

docs/source/conf.py

@@ -62,10 +62,22 @@
     ("py:obj", "trio._abc.SendType"),
     ("py:obj", "trio._abc.T"),
     ("py:obj", "trio._abc.T_resource"),
+    ("py:class", "types.FrameType"),
 ]
 autodoc_inherit_docstrings = False
 default_role = "obj"
 
+# These have incorrect __module__ set in stdlib and give the error
+# `py:class reference target not found`
+# Some of the nitpick_ignore's above can probably be fixed with this.
+# See https://github.com/sphinx-doc/sphinx/issues/8315#issuecomment-751335798
+autodoc_type_aliases = {
+    # aliasing doesn't actually fix the warning for types.FrameType, but displaying
+    # "types.FrameType" is more helpful than just "frame"
+    "FrameType": "types.FrameType",
+}
+
+
 # XX hack the RTD theme until
 #   https://github.com/rtfd/sphinx_rtd_theme/pull/382
 # is shipped (should be in the release after 0.2.4)

docs/source/reference-core.rst

@@ -1096,6 +1096,8 @@ Broadcasting an event with :class:`Event`
 .. autoclass:: Event
    :members:
 
+.. autoclass:: EventStatistics
+   :members:
 
 .. _channels:
 
@@ -1456,6 +1458,16 @@ don't have any special access to Trio's internals.)
 .. autoclass:: Condition
    :members:
 
+These primitives return statistics objects that can be inspected.
+
+.. autoclass:: CapacityLimiterStatistics
+   :members:
+
+.. autoclass:: LockStatistics
+   :members:
+
+.. autoclass:: ConditionStatistics
+   :members:
 
 .. _async-generators:
 

docs/source/reference-lowlevel.rst

@@ -378,6 +378,8 @@ Wait queue abstraction
    :members:
    :undoc-members:
 
+.. autoclass:: ParkingLotStatistics
+   :members:
 
 Low-level checkpoint functions
 ------------------------------

trio/__init__.py

@@ -78,9 +78,13 @@
 from ._subprocess import Process as Process, run_process as run_process
 from ._sync import (
     CapacityLimiter as CapacityLimiter,
+    CapacityLimiterStatistics as CapacityLimiterStatistics,
     Condition as Condition,
+    ConditionStatistics as ConditionStatistics,
     Event as Event,
+    EventStatistics as EventStatistics,
     Lock as Lock,
+    LockStatistics as LockStatistics,
     Semaphore as Semaphore,
     StrictFIFOLock as StrictFIFOLock,
 )

trio/_abc.py

@@ -1,8 +1,15 @@
+from __future__ import annotations
+
 from abc import ABCMeta, abstractmethod
-from typing import Generic, TypeVar
+from typing import TYPE_CHECKING, Generic, TypeVar
 
 import trio
 
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from typing_extensions import Self
+
 
 # We use ABCMeta instead of ABC, plus set __slots__=(), so as not to force a
 # __dict__ onto subclasses.
@@ -12,15 +19,15 @@ class Clock(metaclass=ABCMeta):
     __slots__ = ()
 
     @abstractmethod
-    def start_clock(self):
+    def start_clock(self) -> None:
         """Do any setup this clock might need.
 
         Called at the beginning of the run.
 
         """
 
     @abstractmethod
-    def current_time(self):
+    def current_time(self) -> float:
         """Return the current time, according to this clock.
 
         This is used to implement functions like :func:`trio.current_time` and
@@ -32,7 +39,7 @@ def current_time(self):
         """
 
     @abstractmethod
-    def deadline_to_sleep_time(self, deadline):
+    def deadline_to_sleep_time(self, deadline: float) -> float:
         """Compute the real time until the given deadline.
 
         This is called before we enter a system-specific wait function like
@@ -225,7 +232,7 @@ class AsyncResource(metaclass=ABCMeta):
     __slots__ = ()
 
     @abstractmethod
-    async def aclose(self):
+    async def aclose(self) -> None:
         """Close this resource, possibly blocking.
 
         IMPORTANT: This method may block in order to perform a "graceful"
@@ -253,10 +260,15 @@ async def aclose(self):
 
         """
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> Self:
         return self
 
-    async def __aexit__(self, *args):
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
         await self.aclose()
 
 
@@ -279,7 +291,7 @@ class SendStream(AsyncResource):
     __slots__ = ()
 
     @abstractmethod
-    async def send_all(self, data):
+    async def send_all(self, data: bytes | bytearray | memoryview) -> None:
         """Sends the given data through the stream, blocking if necessary.
 
         Args:
@@ -305,7 +317,7 @@ async def send_all(self, data):
         """
 
     @abstractmethod
-    async def wait_send_all_might_not_block(self):
+    async def wait_send_all_might_not_block(self) -> None:
         """Block until it's possible that :meth:`send_all` might not block.
 
         This method may return early: it's possible that after it returns,
@@ -385,7 +397,7 @@ class ReceiveStream(AsyncResource):
     __slots__ = ()
 
     @abstractmethod
-    async def receive_some(self, max_bytes=None):
+    async def receive_some(self, max_bytes: int | None = None) -> bytes | bytearray:
         """Wait until there is data available on this stream, and then return
         some of it.
 
@@ -413,10 +425,10 @@ async def receive_some(self, max_bytes=None):
 
         """
 
-    def __aiter__(self):
+    def __aiter__(self) -> Self:
         return self
 
-    async def __anext__(self):
+    async def __anext__(self) -> bytes | bytearray:
         data = await self.receive_some()
         if not data:
             raise StopAsyncIteration
@@ -446,7 +458,7 @@ class HalfCloseableStream(Stream):
     __slots__ = ()
 
     @abstractmethod
-    async def send_eof(self):
+    async def send_eof(self) -> None:
         """Send an end-of-file indication on this stream, if possible.
 
         The difference between :meth:`send_eof` and
@@ -632,7 +644,7 @@ async def receive(self) -> ReceiveType:
 
         """
 
-    def __aiter__(self):
+    def __aiter__(self) -> Self:
         return self
 
     async def __anext__(self) -> ReceiveType:

trio/_channel.py

@@ -243,8 +243,8 @@ def __enter__(self: SelfT) -> SelfT:
     def __exit__(
         self,
         exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: TracebackType | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ) -> None:
         self.close()
 
@@ -389,8 +389,8 @@ def __enter__(self: SelfT) -> SelfT:
     def __exit__(
         self,
         exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: TracebackType | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ) -> None:
         self.close()
 

trio/_core/__init__.py

@@ -20,7 +20,7 @@
 from ._ki import currently_ki_protected, disable_ki_protection, enable_ki_protection
 from ._local import RunVar
 from ._mock_clock import MockClock
-from ._parking_lot import ParkingLot
+from ._parking_lot import ParkingLot, ParkingLotStatistics
 
 # Imports that always exist
 from ._run import (

trio/_core/_mock_clock.py

@@ -62,7 +62,7 @@ class MockClock(Clock, metaclass=Final):
 
     """
 
-    def __init__(self, rate=0.0, autojump_threshold=inf):
+    def __init__(self, rate: float = 0.0, autojump_threshold: float = inf):
         # 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.
@@ -77,17 +77,17 @@ def __init__(self, rate=0.0, autojump_threshold=inf):
         self.rate = rate
         self.autojump_threshold = autojump_threshold
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<MockClock, time={:.7f}, rate={} @ {:#x}>".format(
             self.current_time(), self._rate, id(self)
         )
 
     @property
-    def rate(self):
+    def rate(self) -> float:
         return self._rate
 
     @rate.setter
-    def rate(self, new_rate):
+    def rate(self, new_rate: float) -> None:
         if new_rate < 0:
             raise ValueError("rate must be >= 0")
         else:
@@ -98,11 +98,11 @@ def rate(self, new_rate):
             self._rate = float(new_rate)
 
     @property
-    def autojump_threshold(self):
+    def autojump_threshold(self) -> float:
         return self._autojump_threshold
 
     @autojump_threshold.setter
-    def autojump_threshold(self, new_autojump_threshold):
+    def autojump_threshold(self, new_autojump_threshold: float) -> None:
         self._autojump_threshold = float(new_autojump_threshold)
         self._try_resync_autojump_threshold()
 
@@ -112,7 +112,7 @@ def autojump_threshold(self, new_autojump_threshold):
     # API. Discussion:
     #
     #     https://github.com/python-trio/trio/issues/1587
-    def _try_resync_autojump_threshold(self):
+    def _try_resync_autojump_threshold(self) -> None:
         try:
             runner = GLOBAL_RUN_CONTEXT.runner
             if runner.is_guest:
@@ -124,24 +124,24 @@ def _try_resync_autojump_threshold(self):
 
     # Invoked by the run loop when runner.clock_autojump_threshold is
     # exceeded.
-    def _autojump(self):
+    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):
+    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):
+    def start_clock(self) -> None:
         self._try_resync_autojump_threshold()
 
-    def current_time(self):
+    def current_time(self) -> float:
         return self._real_to_virtual(self._real_clock())
 
-    def deadline_to_sleep_time(self, deadline):
+    def deadline_to_sleep_time(self, deadline: float) -> float:
         virtual_timeout = deadline - self.current_time()
         if virtual_timeout <= 0:
             return 0
@@ -150,7 +150,7 @@ def deadline_to_sleep_time(self, deadline):
         else:
             return 999999999
 
-    def jump(self, seconds):
+    def jump(self, seconds) -> None:
         """Manually advance the clock by the given number of seconds.
 
         Args:

trio/_core/_multierror.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 import sys
 import warnings
+from typing import TYPE_CHECKING
 
 import attr
 
@@ -10,6 +13,8 @@
 else:
     from traceback import print_exception
 
+if TYPE_CHECKING:
+    from types import TracebackType
 ################################################################
 # MultiError
 ################################################################
@@ -130,11 +135,16 @@ class MultiErrorCatcher:
     def __enter__(self):
         pass
 
-    def __exit__(self, etype, exc, tb):
-        if exc is not None:
-            filtered_exc = _filter_impl(self._handler, exc)
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        if exc_value is not None:
+            filtered_exc = _filter_impl(self._handler, exc_value)
 
-            if filtered_exc is exc:
+            if filtered_exc is exc_value:
                 # Let the interpreter re-raise it
                 return False
             if filtered_exc is None:
@@ -154,6 +164,7 @@ def __exit__(self, etype, exc, tb):
                 # delete references from locals to avoid creating cycles
                 # see test_MultiError_catch_doesnt_create_cyclic_garbage
                 del _, filtered_exc, value
+        return False
 
 
 class MultiError(BaseExceptionGroup):