From 08bc36fb6ac98cc30e49c53a3ff13c26aa3890a9 Mon Sep 17 00:00:00 2001 From: Sai Sridhar Date: Sat, 30 May 2026 17:31:16 +0530 Subject: [PATCH 1/2] docs: add missing docstrings to memory channel classes and SocketStream methods Several public classes and methods were missing docstrings, causing them to show up as undocumented in the API reference. - MemoryChannelStatistics: add class-level docstring with field descriptions - MemorySendChannel: add class-level docstring - MemoryReceiveChannel: add class-level docstring - SocketStream.send_all: add one-line docstring referencing the ABC - SocketStream.wait_send_all_might_not_block: add docstring - SocketStream.send_eof: add docstring - SocketStream.receive_some: add docstring - SocketStream.aclose: add docstring Contributes to #3221 --- src/trio/_channel.py | 27 +++++++++++++++++++++++++++ src/trio/_highlevel_socket.py | 5 +++++ 2 files changed, 32 insertions(+) diff --git a/src/trio/_channel.py b/src/trio/_channel.py index 05037d8131..8699d64785 100644 --- a/src/trio/_channel.py +++ b/src/trio/_channel.py @@ -118,6 +118,19 @@ def __init__(self, max_buffer_size: int | float) -> None: # noqa: PYI041 @attrs.frozen class MemoryChannelStatistics: + """Statistics about a memory channel, as returned by + :meth:`MemorySendChannel.statistics` or + :meth:`MemoryReceiveChannel.statistics`. + + Attributes: + current_buffer_used: Number of items currently stored in the channel buffer. + max_buffer_size: Maximum number of items allowed in the buffer. + open_send_channels: Number of open :class:`MemorySendChannel` endpoints. + open_receive_channels: Number of open :class:`MemoryReceiveChannel` endpoints. + tasks_waiting_send: Number of tasks blocked in ``send`` across all clones. + tasks_waiting_receive: Number of tasks blocked in ``receive`` across all clones. + """ + current_buffer_used: int max_buffer_size: int | float open_send_channels: int @@ -152,6 +165,13 @@ def statistics(self) -> MemoryChannelStatistics: @final @attrs.define(eq=False, repr=False, slots=False) class MemorySendChannel(SendChannel[SendType], metaclass=NoPublicConstructor): + """The send end of a memory channel, as returned by :func:`open_memory_channel`. + + Use :meth:`send` to send objects and :meth:`aclose` (or ``async with``) + to close. Call :meth:`clone` to create additional send endpoints that + share the same underlying channel. + """ + _state: MemoryChannelState[SendType] _closed: bool = False # This is just the tasks waiting on *this* object. As compared to @@ -300,6 +320,13 @@ async def aclose(self) -> None: @final @attrs.define(eq=False, repr=False, slots=False) class MemoryReceiveChannel(ReceiveChannel[ReceiveType], metaclass=NoPublicConstructor): + """The receive end of a memory channel, as returned by :func:`open_memory_channel`. + + Use :meth:`receive` to receive objects and :meth:`aclose` (or ``async with``) + to close. Call :meth:`clone` to create additional receive endpoints that + share the same underlying channel. + """ + _state: MemoryChannelState[ReceiveType] _closed: bool = False _tasks: set[trio._core._run.Task] = attrs.Factory(set) diff --git a/src/trio/_highlevel_socket.py b/src/trio/_highlevel_socket.py index 142ab11e07..35537efb86 100644 --- a/src/trio/_highlevel_socket.py +++ b/src/trio/_highlevel_socket.py @@ -107,6 +107,7 @@ def __init__(self, socket: SocketType) -> None: self.setsockopt(tsocket.IPPROTO_TCP, tsocket.TCP_NOTSENT_LOWAT, 2**14) async def send_all(self, data: bytes | bytearray | memoryview) -> None: + """See :meth:`trio.abc.SendStream.send_all`.""" if self.socket.did_shutdown_SHUT_WR: raise trio.ClosedResourceError("can't send data after sending EOF") with self._send_conflict_detector: @@ -124,6 +125,7 @@ async def send_all(self, data: bytes | bytearray | memoryview) -> None: total_sent += sent async def wait_send_all_might_not_block(self) -> None: + """See :meth:`trio.abc.HalfCloseableStream.wait_send_all_might_not_block`.""" with self._send_conflict_detector: if self.socket.fileno() == -1: raise trio.ClosedResourceError @@ -131,6 +133,7 @@ async def wait_send_all_might_not_block(self) -> None: await self.socket.wait_writable() async def send_eof(self) -> None: + """See :meth:`trio.abc.HalfCloseableStream.send_eof`.""" with self._send_conflict_detector: await trio.lowlevel.checkpoint() # On macOS, calling shutdown a second time raises ENOTCONN, but @@ -141,6 +144,7 @@ async def send_eof(self) -> None: self.socket.shutdown(tsocket.SHUT_WR) async def receive_some(self, max_bytes: int | None = None) -> bytes: + """See :meth:`trio.abc.ReceiveStream.receive_some`.""" if max_bytes is None: max_bytes = DEFAULT_RECEIVE_SIZE if max_bytes < 1: @@ -149,6 +153,7 @@ async def receive_some(self, max_bytes: int | None = None) -> bytes: return await self.socket.recv(max_bytes) async def aclose(self) -> None: + """See :meth:`trio.abc.AsyncResource.aclose`.""" self.socket.close() await trio.lowlevel.checkpoint() From 2d43031eeaf9b955ce2392d82b765009c460846e Mon Sep 17 00:00:00 2001 From: Sai Sridhar Date: Sat, 30 May 2026 17:54:28 +0530 Subject: [PATCH 2/2] news: add doc fragment for #3221 --- newsfragments/3221.doc.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 newsfragments/3221.doc.rst diff --git a/newsfragments/3221.doc.rst b/newsfragments/3221.doc.rst new file mode 100644 index 0000000000..ace165aa9b --- /dev/null +++ b/newsfragments/3221.doc.rst @@ -0,0 +1,3 @@ +Added docstrings to :class:`MemoryChannelStatistics`, :class:`MemorySendChannel`, +:class:`MemoryReceiveChannel`, and several :class:`SocketStream` methods that +were missing from the API reference.