docs: add missing docstrings for public API by nightcityblade · Pull Request #3404 · python-trio/trio

nightcityblade · 2026-03-05T16:27:30Z

Adds docstrings to the following public API items that were showing up without documentation:

MemorySendChannel — class docstring referencing open_memory_channel
MemoryReceiveChannel — class docstring referencing open_memory_channel
MemoryChannelStatistics — class docstring with attribute descriptions
SocketStream.send_all, wait_send_all_might_not_block, send_eof, receive_some, aclose — short docstrings referencing the parent ABC methods
HasFileno.fileno — method docstring
ParkingLot.broken_by — attribute docstring

The SocketStream method docstrings use See :meth:... cross-references rather than duplicating the ABC documentation, keeping them in sync with the parent class.

Tests run: pytest src/trio/_tests/test_channel.py src/trio/_tests/test_highlevel_socket.py src/trio/_core/_tests/test_parking_lot.py — all pass.

Add docstrings to: - MemorySendChannel class - MemoryReceiveChannel class - MemoryChannelStatistics class and attributes - SocketStream.send_all, wait_send_all_might_not_block, send_eof, receive_some, aclose - HasFileno.fileno - ParkingLot.broken_by attribute Fixes python-trio#3221

jakkdl · 2026-03-05T16:52:53Z

See discussion in #3388

codecov · 2026-03-05T17:30:23Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00000%. Comparing base (3dd35d7) to head (54c94dd).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@               Coverage Diff               @@
##                 main        #3404   +/-   ##
===============================================
  Coverage   100.00000%   100.00000%           
===============================================
  Files             128          128           
  Lines           19424        19418    -6     
  Branches         1318         1318           
===============================================
- Hits            19424        19418    -6

Files with missing lines	Coverage Δ
src/trio/_channel.py	`100.00000% <ø> (ø)`
src/trio/_core/_parking_lot.py	`100.00000% <100.00000%> (ø)`
src/trio/_highlevel_socket.py	`100.00000% <ø> (ø)`
src/trio/_subprocess.py	`100.00000% <ø> (ø)`

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

A5rocks · 2026-03-19T02:58:29Z

BTW please make CI pass!

nightcityblade · 2026-03-19T15:10:33Z

Fixed! I've updated the type completeness checklist to remove the entries that are now resolved by the new docstrings. CI should pass now.

CoolCat467 · 2026-03-19T20:12:29Z

Need to update type completeness file, you need to do python src/trio/_tests/check_type_completeness.py --overwrite-file like CI says to.

nightcityblade · 2026-03-20T03:04:44Z

Thanks @CoolCat467! I ran python src/trio/_tests/check_type_completeness.py --overwrite-file to update the type completeness checklist. CI should pass now.

nightcityblade · 2026-03-25T03:06:05Z

Thanks for the feedback @A5rocks @CoolCat467! I've rebased on upstream/main and am working on getting the type_completeness check to pass. The docstrings are present at runtime but pyright's --verifytypes isn't picking some of them up — I'll investigate and push a fix.

jakkdl · 2026-03-25T14:54:39Z

The docstrings are present at runtime but pyright's --verifytypes isn't picking some of them up — I'll investigate and push a fix.

The current CI errors are

you (or, well, probably check_type_completeness doing so on your system) adding trio._core._io_kqueue._KqueueStatistics to the json for Darwin. It indeed doesn't have a docstring, so it's weird that check_type_completeness [when run in CI] doesn't pick up on it. You could give it one, or simply manually undo the change to the json for now. The script can be a bit funky
you need to update the list in https://github.com/nightcityblade/trio/blob/17438782ac724eec0399115c8da92d79e2e1e8da/docs/source/conf.py#L173-L186
add a newsfragment (see newsfragments/README.rst)
fix https://app.readthedocs.org/projects/trio/builds/31890097/#311595438--75

nightcityblade · 2026-03-26T03:02:16Z

Thanks @jakkdl for the detailed feedback! I'll address all four points:

Revert the KqueueStatistics json change for now
Update the conf.py undocumented list
Add a newsfragment (3221.doc.rst)
Fix the readthedocs build issue

Will push the fixes shortly.

…type completeness json

CoolCat467 · 2026-03-26T03:11:49Z

still have RTD failures

docstring of trio.MemorySendChannel:4: WARNING: undefined label: 'channel' [ref.ref]
docstring of trio.MemoryReceiveChannel:4: WARNING: undefined label: 'channel' [ref.ref]

The labels in reference-core.rst use 'channels' (plural), but the MemorySendChannel and MemoryReceiveChannel docstrings referenced 'channel' (singular), causing RTD build warnings.

nightcityblade · 2026-03-26T15:06:13Z

Fixed the RTD warnings — the docstrings in MemorySendChannel and MemoryReceiveChannel were referencing channel but the label in reference-core.rst is channels (plural).
Updated both references.

A5rocks · 2026-04-06T08:32:56Z

src/trio/_core/_parking_lot.py

    # 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 parking lot via


It looks like you tried to document broken_by... but Sphinx didn't pick it up (see your docs/source/conf.py change).

A5rocks · 2026-04-06T08:33:54Z

src/trio/_channel.py

+        open_receive_channels: The number of open
+            :class:`MemoryReceiveChannel` endpoints.
+        tasks_waiting_send: The number of tasks waiting to send.
+        tasks_waiting_receive: The number of tasks waiting to receive.


If MemorySendChannel.statistics and MemoryReceiveChannel.statistics document the attributes (iirc they do), could you remove that?

(well, that's my current mood. but I'm not so sure which way is best!)

A5rocks · 2026-04-06T08:34:17Z

src/trio/_channel.py

+    :func:`open_memory_channel`.
+
+    See :ref:`channels` for details. This implements the
+    :class:`trio.abc.SendChannel` interface.


IMO "this implements ..." is unnecessary. Do we do that elsewhere?

A5rocks · 2026-04-06T08:34:24Z

src/trio/_channel.py

+    :func:`open_memory_channel`.
+
+    See :ref:`channels` for details. This implements the
+    :class:`trio.abc.ReceiveChannel` interface.


A5rocks · 2026-04-06T08:36:16Z

src/trio/_highlevel_socket.py

                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`."""


That's strange, why is Sphinx making you copy-paste these? Hmmm... maybe it's the undoc-members here?

trio/docs/source/reference-io.rst

Line 221 in 94d7159

:undoc-members:

I would rather fix that there instead of adding docstrings here.

fix: update type completeness checklist after adding docstrings

77edca2

fix: update type completeness checklist after adding docstrings

1743878

fix: address review feedback - update conf.py, add newsfragment, fix …

dcfa304

…type completeness json

fix: correct :ref:channel to :ref:channels in docstrings

54c94dd

The labels in reference-core.rst use 'channels' (plural), but the MemorySendChannel and MemoryReceiveChannel docstrings referenced 'channel' (singular), causing RTD build warnings.

A5rocks requested changes Apr 6, 2026

View reviewed changes

Uh oh!

Conversation

nightcityblade commented Mar 5, 2026

Uh oh!

jakkdl commented Mar 5, 2026

Uh oh!

codecov bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

A5rocks commented Mar 19, 2026

Uh oh!

nightcityblade commented Mar 19, 2026

Uh oh!

CoolCat467 commented Mar 19, 2026

Uh oh!

nightcityblade commented Mar 20, 2026

Uh oh!

nightcityblade commented Mar 25, 2026

Uh oh!

jakkdl commented Mar 25, 2026

Uh oh!

nightcityblade commented Mar 26, 2026

Uh oh!

CoolCat467 commented Mar 26, 2026

Uh oh!

nightcityblade commented Mar 26, 2026 • edited by CoolCat467 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

A5rocks Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

A5rocks Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

A5rocks Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

A5rocks Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

A5rocks Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Mar 5, 2026 •

edited

Loading

nightcityblade commented Mar 26, 2026 •

edited by CoolCat467

Loading