Merge remote-tracking branch 'origin/main' into break_the_lot

Author: jakkdl

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
     hooks:
       - id: black
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.7
+    rev: v0.6.8
     hooks:
       - id: ruff
         types: [file]

docs-requirements.txt

@@ -12,7 +12,7 @@ beautifulsoup4==4.12.3
     # via sphinx-codeautolink
 certifi==2024.8.30
     # via requests
-cffi==1.17.0 ; platform_python_implementation != 'PyPy' or os_name == 'nt'
+cffi==1.17.1 ; platform_python_implementation != 'PyPy' or os_name == 'nt'
     # via
     #   -r docs-requirements.in
     #   cryptography
@@ -24,15 +24,15 @@ colorama==0.4.6 ; sys_platform == 'win32' or platform_system == 'Windows'
     # via
     #   click
     #   sphinx
-cryptography==43.0.0
+cryptography==43.0.1
     # via pyopenssl
 docutils==0.20.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
 exceptiongroup==1.2.2
     # via -r docs-requirements.in
-idna==3.8
+idna==3.10
     # via
     #   -r docs-requirements.in
     #   requests
@@ -77,7 +77,7 @@ sphinx==7.4.7
     #   sphinxcontrib-trio
 sphinx-codeautolink==0.15.2
     # via -r docs-requirements.in
-sphinx-hoverxref==1.4.0
+sphinx-hoverxref==1.4.1
     # via -r docs-requirements.in
 sphinx-rtd-theme==2.0.0
     # via -r docs-requirements.in
@@ -102,5 +102,5 @@ sphinxcontrib-trio==1.1.2
     # via -r docs-requirements.in
 towncrier==24.8.0
     # via -r docs-requirements.in
-urllib3==2.2.2
+urllib3==2.2.3
     # via requests

docs/source/reference-core.rst

@@ -1241,6 +1241,8 @@ more features beyond the core channel interface:
 .. autoclass:: MemoryReceiveChannel
    :members:
 
+.. autoclass:: MemoryChannelStatistics
+   :members:
 
 A simple channel example
 ++++++++++++++++++++++++

newsfragments/3095.bugfix.rst

@@ -0,0 +1 @@
+Update :func:`trio.sleep_forever` to be `NoReturn`.

newsfragments/3101.doc.rst

@@ -0,0 +1 @@
+Add docstrings for memory channels' ``statistics()`` and ``aclose`` methods.

src/trio/__init__.py

@@ -25,6 +25,7 @@
 # Submodules imported by default
 from . import abc, from_thread, lowlevel, socket, to_thread
 from ._channel import (
+    MemoryChannelStatistics as MemoryChannelStatistics,
     MemoryReceiveChannel as MemoryReceiveChannel,
     MemorySendChannel as MemorySendChannel,
     open_memory_channel as open_memory_channel,

src/trio/_channel.py

@@ -111,7 +111,7 @@ def __init__(self, max_buffer_size: int | float):  # noqa: PYI041
 
 
 @attrs.frozen
-class MemoryChannelStats:
+class MemoryChannelStatistics:
     current_buffer_used: int
     max_buffer_size: int | float
     open_send_channels: int
@@ -132,8 +132,8 @@ class MemoryChannelState(Generic[T]):
     # {task: None}
     receive_tasks: OrderedDict[Task, None] = attrs.Factory(OrderedDict)
 
-    def statistics(self) -> MemoryChannelStats:
-        return MemoryChannelStats(
+    def statistics(self) -> MemoryChannelStatistics:
+        return MemoryChannelStatistics(
             current_buffer_used=len(self.data),
             max_buffer_size=self.max_buffer_size,
             open_send_channels=self.open_send_channels,
@@ -159,7 +159,9 @@ def __attrs_post_init__(self) -> None:
     def __repr__(self) -> str:
         return f"<send channel at {id(self):#x}, using buffer at {id(self._state):#x}>"
 
-    def statistics(self) -> MemoryChannelStats:
+    def statistics(self) -> MemoryChannelStatistics:
+        """Returns a `MemoryChannelStatistics` for the memory channel this is
+        associated with."""
         # XX should we also report statistics specific to this object?
         return self._state.statistics()
 
@@ -282,6 +284,9 @@ def close(self) -> None:
 
     @enable_ki_protection
     async def aclose(self) -> None:
+        """Close this send channel object asynchronously.
+
+        See `MemorySendChannel.close`."""
         self.close()
         await trio.lowlevel.checkpoint()
 
@@ -296,7 +301,9 @@ class MemoryReceiveChannel(ReceiveChannel[ReceiveType], metaclass=NoPublicConstr
     def __attrs_post_init__(self) -> None:
         self._state.open_receive_channels += 1
 
-    def statistics(self) -> MemoryChannelStats:
+    def statistics(self) -> MemoryChannelStatistics:
+        """Returns a `MemoryChannelStatistics` for the memory channel this is
+        associated with."""
         return self._state.statistics()
 
     def __repr__(self) -> str:
@@ -430,5 +437,8 @@ def close(self) -> None:
 
     @enable_ki_protection
     async def aclose(self) -> None:
+        """Close this receive channel object asynchronously.
+
+        See `MemoryReceiveChannel.close`."""
         self.close()
         await trio.lowlevel.checkpoint()

src/trio/_tests/_check_type_completeness.json

@@ -20,13 +20,10 @@
     "all": [
         "No docstring found for class \"trio.MemoryReceiveChannel\"",
         "No docstring found for class \"trio._channel.MemoryReceiveChannel\"",
-        "No docstring found for function \"trio._channel.MemoryReceiveChannel.statistics\"",
-        "No docstring found for class \"trio._channel.MemoryChannelStats\"",
-        "No docstring found for function \"trio._channel.MemoryReceiveChannel.aclose\"",
+        "No docstring found for class \"trio.MemoryChannelStatistics\"",
+        "No docstring found for class \"trio._channel.MemoryChannelStatistics\"",
         "No docstring found for class \"trio.MemorySendChannel\"",
         "No docstring found for class \"trio._channel.MemorySendChannel\"",
-        "No docstring found for function \"trio._channel.MemorySendChannel.statistics\"",
-        "No docstring found for function \"trio._channel.MemorySendChannel.aclose\"",
         "No docstring found for class \"trio._core._run.Task\"",
         "No docstring found for class \"trio._socket.SocketType\"",
         "No docstring found for function \"trio._highlevel_socket.SocketStream.send_all\"",

src/trio/_tests/test_timeouts.py

@@ -86,6 +86,20 @@ async def sleep_3() -> None:
     await check_takes_about(sleep_3, TARGET)
 
 
+async def test_cannot_wake_sleep_forever() -> None:
+    # Test an error occurs if you manually wake sleep_forever().
+    task = trio.lowlevel.current_task()
+
+    async def wake_task() -> None:
+        await trio.lowlevel.checkpoint()
+        trio.lowlevel.reschedule(task, outcome.Value(None))
+
+    async with trio.open_nursery() as nursery:
+        nursery.start_soon(wake_task)
+        with pytest.raises(RuntimeError):
+            await trio.sleep_forever()
+
+
 class TimeoutScope(Protocol):
     def __call__(self, seconds: float, *, shield: bool) -> trio.CancelScope: ...
 

src/trio/_timeouts.py

@@ -3,7 +3,7 @@
 import math
 import sys
 from contextlib import contextmanager
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NoReturn
 
 import trio
 
@@ -58,13 +58,14 @@ def move_on_after(
     )
 
 
-async def sleep_forever() -> None:
+async def sleep_forever() -> NoReturn:
     """Pause execution of the current task forever (or until cancelled).
 
     Equivalent to calling ``await sleep(math.inf)``.
 
     """
     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: