From 94de8a209763b7fa0b55c6dfd0dee56ac74d8131 Mon Sep 17 00:00:00 2001 From: wavebyrd Date: Mon, 16 Mar 2026 09:47:28 -0400 Subject: [PATCH 1/3] docs: add docstrings to memory channel classes Add docstrings to MemoryChannelStatistics, MemorySendChannel, and MemoryReceiveChannel classes so they show up properly in the Sphinx-generated documentation. - MemoryChannelStatistics: Document all attributes with descriptions - MemorySendChannel: Reference open_memory_channel and note it implements SendChannel interface - MemoryReceiveChannel: Reference open_memory_channel and note it implements ReceiveChannel interface Partial fix for #3221 Co-Authored-By: Claude Opus 4.5 --- src/trio/_channel.py | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/src/trio/_channel.py b/src/trio/_channel.py index 05037d8131..4ebdf03c45 100644 --- a/src/trio/_channel.py +++ b/src/trio/_channel.py @@ -118,6 +118,26 @@ def __init__(self, max_buffer_size: int | float) -> None: # noqa: PYI041 @attrs.frozen class MemoryChannelStatistics: + """Statistics about a memory channel. + + This object is returned by the ``statistics()`` method on + :class:`MemorySendChannel` and :class:`MemoryReceiveChannel`. + + Attributes: + current_buffer_used: The number of items currently stored in the + channel buffer. + max_buffer_size: The maximum number of items allowed in the buffer, + as passed to :func:`open_memory_channel`. + open_send_channels: The number of open :class:`MemorySendChannel` + endpoints pointing to this channel. + open_receive_channels: The number of open :class:`MemoryReceiveChannel` + endpoints pointing to this channel. + tasks_waiting_send: The number of tasks blocked in ``send`` on this + channel (summing over all clones). + tasks_waiting_receive: The number of tasks blocked in ``receive`` on + this channel (summing over all clones). + """ + current_buffer_used: int max_buffer_size: int | float open_send_channels: int @@ -152,6 +172,15 @@ def statistics(self) -> MemoryChannelStatistics: @final @attrs.define(eq=False, repr=False, slots=False) class MemorySendChannel(SendChannel[SendType], metaclass=NoPublicConstructor): + """The sending end of a memory channel. + + Memory channels are created using :func:`open_memory_channel`, which + returns a pair of (:class:`MemorySendChannel`, :class:`MemoryReceiveChannel`). + See :func:`open_memory_channel` for full documentation. + + This implements the :class:`~trio.abc.SendChannel` interface. + """ + _state: MemoryChannelState[SendType] _closed: bool = False # This is just the tasks waiting on *this* object. As compared to @@ -300,6 +329,15 @@ async def aclose(self) -> None: @final @attrs.define(eq=False, repr=False, slots=False) class MemoryReceiveChannel(ReceiveChannel[ReceiveType], metaclass=NoPublicConstructor): + """The receiving end of a memory channel. + + Memory channels are created using :func:`open_memory_channel`, which + returns a pair of (:class:`MemorySendChannel`, :class:`MemoryReceiveChannel`). + See :func:`open_memory_channel` for full documentation. + + This implements the :class:`~trio.abc.ReceiveChannel` interface. + """ + _state: MemoryChannelState[ReceiveType] _closed: bool = False _tasks: set[trio._core._run.Task] = attrs.Factory(set) From 35a3ae344e583fb6a37e25dd97f742ddda134dc3 Mon Sep 17 00:00:00 2001 From: wavebyrd Date: Tue, 17 Mar 2026 13:01:15 -0400 Subject: [PATCH 2/3] docs: remove unnecessary backrefs and interface mentions Address review feedback: - Remove backref in MemoryChannelStatistics docstring - Remove "implements interface" lines from Send/ReceiveChannel Co-Authored-By: Claude Opus 4.5 --- src/trio/_channel.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/trio/_channel.py b/src/trio/_channel.py index 4ebdf03c45..8e68cf07f8 100644 --- a/src/trio/_channel.py +++ b/src/trio/_channel.py @@ -120,9 +120,6 @@ def __init__(self, max_buffer_size: int | float) -> None: # noqa: PYI041 class MemoryChannelStatistics: """Statistics about a memory channel. - This object is returned by the ``statistics()`` method on - :class:`MemorySendChannel` and :class:`MemoryReceiveChannel`. - Attributes: current_buffer_used: The number of items currently stored in the channel buffer. @@ -177,8 +174,6 @@ class MemorySendChannel(SendChannel[SendType], metaclass=NoPublicConstructor): Memory channels are created using :func:`open_memory_channel`, which returns a pair of (:class:`MemorySendChannel`, :class:`MemoryReceiveChannel`). See :func:`open_memory_channel` for full documentation. - - This implements the :class:`~trio.abc.SendChannel` interface. """ _state: MemoryChannelState[SendType] @@ -334,8 +329,6 @@ class MemoryReceiveChannel(ReceiveChannel[ReceiveType], metaclass=NoPublicConstr Memory channels are created using :func:`open_memory_channel`, which returns a pair of (:class:`MemorySendChannel`, :class:`MemoryReceiveChannel`). See :func:`open_memory_channel` for full documentation. - - This implements the :class:`~trio.abc.ReceiveChannel` interface. """ _state: MemoryChannelState[ReceiveType] From 4eb6f844ad3889378eae343f95efaa9263147727 Mon Sep 17 00:00:00 2001 From: wavebyrd Date: Wed, 18 Mar 2026 21:23:35 -0400 Subject: [PATCH 3/3] Remove fixed docstring entries from type_completeness.json The docstrings for MemoryReceiveChannel, MemorySendChannel, and MemoryChannelStatistics are now present, so remove them from the known-missing list. Co-Authored-By: Claude Opus 4.5 --- src/trio/_tests/_check_type_completeness.json | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/trio/_tests/_check_type_completeness.json b/src/trio/_tests/_check_type_completeness.json index 6e8c54ea8b..e5414cfe56 100644 --- a/src/trio/_tests/_check_type_completeness.json +++ b/src/trio/_tests/_check_type_completeness.json @@ -18,12 +18,6 @@ ], "Windows": [], "all": [ - "No docstring found for class \"trio.MemoryReceiveChannel\"", - "No docstring found for class \"trio._channel.MemoryReceiveChannel\"", - "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 class \"trio._core._run.Task\"", "No docstring found for class \"trio._socket.SocketType\"", "No docstring found for function \"trio._highlevel_socket.SocketStream.send_all\"",