From becb825e13b2596ecef83daaa15f775a2e33d479 Mon Sep 17 00:00:00 2001 From: mokashang Date: Tue, 12 May 2026 19:07:01 -0700 Subject: [PATCH] docs: drop undocumented SocketStream method stubs from the API ref These five overrides on SocketStream had no docstring of their own, so they appeared in the SocketStream autodoc table as bare entries because of `:undoc-members:`. Remove that directive so the autoclass directive only lists members that actually have content (`setsockopt`, `getsockopt`, the `socket` attribute). Users following the inheritance chain still get the canonical contracts on the trio.abc classes. Update the cross-reference in the socket section to point at `trio.abc.SendStream.send_all` since `trio.SocketStream.send_all` no longer has a documented target, and prune the now-dead entries from `UNDOCUMENTED` in conf.py. Refs #3221. --- docs/source/conf.py | 5 ----- docs/source/reference-io.rst | 3 +-- newsfragments/3221.doc.rst | 4 ++++ 3 files changed, 5 insertions(+), 7 deletions(-) create mode 100644 newsfragments/3221.doc.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 5017f3895e..925c31e8ef 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -176,11 +176,6 @@ def autodoc_process_signature( "trio.MemorySendChannel", "trio.MemoryReceiveChannel", "trio.MemoryChannelStatistics", - "trio.SocketStream.aclose", - "trio.SocketStream.receive_some", - "trio.SocketStream.send_all", - "trio.SocketStream.send_eof", - "trio.SocketStream.wait_send_all_might_not_block", "trio._subprocess.HasFileno.fileno", "trio.lowlevel.ParkingLot.broken_by", } diff --git a/docs/source/reference-io.rst b/docs/source/reference-io.rst index 665f62dd0b..9d55ec8195 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 @@ -432,7 +431,7 @@ Socket objects * :meth:`~socket.socket.sendall`: Could be supported, but you're better off using the higher-level :class:`~trio.SocketStream`, and specifically its - :meth:`~trio.SocketStream.send_all` method, which also does + :meth:`~trio.abc.SendStream.send_all` method, which also does additional error checking. In addition, the following methods are similar to the equivalents diff --git a/newsfragments/3221.doc.rst b/newsfragments/3221.doc.rst new file mode 100644 index 0000000000..282813c039 --- /dev/null +++ b/newsfragments/3221.doc.rst @@ -0,0 +1,4 @@ +Stopped listing :class:`trio.SocketStream`'s undocumented overrides of +``send_all``, ``wait_send_all_might_not_block``, ``send_eof``, ``receive_some``, +and ``aclose`` in the API reference. The base contracts on the +:mod:`trio.abc` classes remain the canonical reference.