From 01609cc5e3bada86d4457df90dd0463569a01058 Mon Sep 17 00:00:00 2001 From: Varun Chawla Date: Tue, 10 Feb 2026 00:10:09 -0800 Subject: [PATCH] Add missing docstrings for documented public APIs Addresses #3221 by adding docstrings to all items that appear in the Sphinx documentation but previously had no docstring: - MemorySendChannel, MemoryReceiveChannel, MemoryChannelStatistics class docstrings - SocketStream.send_all, .receive_some, .send_eof, .wait_send_all_might_not_block, .aclose referencing parent ABCs - HasFileno.fileno docstring - ParkingLot.broken_by attribute docstring Also removes :undoc-members: from the SocketStream autoclass directive since all methods now have docstrings. Co-Authored-By: Claude Opus 4.6 --- docs/source/reference-io.rst | 1 - newsfragments/3221.doc.rst | 3 +++ src/trio/_channel.py | 24 ++++++++++++++++++++++++ src/trio/_core/_parking_lot.py | 5 +++++ src/trio/_highlevel_socket.py | 5 +++++ src/trio/_subprocess.py | 4 +++- 6 files changed, 40 insertions(+), 2 deletions(-) create mode 100644 newsfragments/3221.doc.rst diff --git a/docs/source/reference-io.rst b/docs/source/reference-io.rst index 665f62dd0b..c9170f8637 100644 --- a/docs/source/reference-io.rst +++ b/docs/source/reference-io.rst @@ -218,7 +218,6 @@ abstraction. .. autoclass:: SocketStream :members: - :undoc-members: :show-inheritance: .. autoclass:: SocketListener diff --git a/newsfragments/3221.doc.rst b/newsfragments/3221.doc.rst new file mode 100644 index 0000000000..31ef339321 --- /dev/null +++ b/newsfragments/3221.doc.rst @@ -0,0 +1,3 @@ +Added missing docstrings for `MemorySendChannel`, `MemoryReceiveChannel`, +`MemoryChannelStatistics`, ``SocketStream`` methods, `~trio.lowlevel.ParkingLot.broken_by`, +and ``HasFileno.fileno``. diff --git a/src/trio/_channel.py b/src/trio/_channel.py index 05037d8131..d048713df5 100644 --- a/src/trio/_channel.py +++ b/src/trio/_channel.py @@ -118,6 +118,12 @@ def __init__(self, max_buffer_size: int | float) -> None: # noqa: PYI041 @attrs.frozen class MemoryChannelStatistics: + """Object returned by `MemorySendChannel.statistics` and + `MemoryReceiveChannel.statistics`. + + See :func:`open_memory_channel` for details on the fields. + """ + current_buffer_used: int max_buffer_size: int | float open_send_channels: int @@ -152,6 +158,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. + + Created by `open_memory_channel`. This implements the + `~trio.abc.SendChannel` interface. + + See `open_memory_channel` for details, and :ref:`channel-mpmc` for a + discussion of channel cloning. + """ + _state: MemoryChannelState[SendType] _closed: bool = False # This is just the tasks waiting on *this* object. As compared to @@ -300,6 +315,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. + + Created by `open_memory_channel`. This implements the + `~trio.abc.ReceiveChannel` interface. + + See `open_memory_channel` for details, and :ref:`channel-mpmc` for a + discussion of channel cloning. + """ + _state: MemoryChannelState[ReceiveType] _closed: bool = False _tasks: set[trio._core._run.Task] = attrs.Factory(set) diff --git a/src/trio/_core/_parking_lot.py b/src/trio/_core/_parking_lot.py index ddf6276117..40035aadab 100644 --- a/src/trio/_core/_parking_lot.py +++ b/src/trio/_core/_parking_lot.py @@ -152,6 +152,11 @@ class ParkingLot: # items _parked: OrderedDict[Task, None] = attrs.field(factory=OrderedDict, init=False) broken_by: list[Task] = attrs.field(factory=list, init=False) + """List of tasks that have broken this lot via `break_lot`. + + If empty, the lot is not broken. If non-empty, any attempt to + `park` in this lot will raise `~trio.BrokenResourceError`. + """ def __len__(self) -> int: """Returns the number of parked tasks.""" diff --git a/src/trio/_highlevel_socket.py b/src/trio/_highlevel_socket.py index 142ab11e07..9118a4d616 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 `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 `trio.abc.SendStream.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 `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 `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 `trio.abc.AsyncResource.aclose`.""" self.socket.close() await trio.lowlevel.checkpoint() diff --git a/src/trio/_subprocess.py b/src/trio/_subprocess.py index 145c2de9b0..bff4008b59 100644 --- a/src/trio/_subprocess.py +++ b/src/trio/_subprocess.py @@ -98,7 +98,9 @@ def pidfd_open(fd: int, flags: int) -> int: class HasFileno(Protocol): """Represents any file-like object that has a file descriptor.""" - def fileno(self) -> int: ... + def fileno(self) -> int: + """Return the underlying file descriptor as an integer.""" + ... @final