Skip to content

docs: document HasFileno.fileno and ParkingLot.broken_by (remaining #3221 items) - #3537

Closed
bfs2021 wants to merge 1 commit into
python-trio:mainfrom
bfs2021:docs/remaining-undocumented-members
Closed

bfs2021 wants to merge 1 commit into
python-trio:mainfrom
bfs2021:docs/remaining-undocumented-members

Conversation

@bfs2021

@bfs2021 bfs2021 commented Oct 9, 2026

Copy link
Copy Markdown

Resolves the two remaining checklist items of #3221 (trio._subprocess.HasFileno.fileno and trio.lowlevel.ParkingLot.broken_by). This also covers the remaining ground of #3406, whose memory-channel docstrings have already landed separately — the approach follows what was approved there.

What

  • HasFileno.fileno: added a docstring describing the contract (return the file descriptor as an integer, which trio passes to the child process when a HasFileno object is used as stdio).
  • ParkingLot.broken_by: documented via an Attributes: block in the class docstring (same pattern as MemoryChannelStatistics from docs: add docstrings to memory channel classes #3406), because the field is a slotted attrs attribute and autodoc reads its docstring at runtime, where a PEP-224-style attribute docstring would not be visible.
  • Removed the now-satisfied trio._subprocess.HasFileno.fileno entry from _check_type_completeness.json (the docstring makes pyright stop reporting it), and removed trio.lowlevel.ParkingLot.broken_by from the UNDOCUMENTED set in docs/source/conf.py, since it now renders through the class docstring.
  • Added :exclude-members: broken_by to the ParkingLot autoclass in reference-lowlevel.rst: with the Attributes: block plus :undoc-members:, the (still docstring-less at runtime) slotted field was rendered a second time as an empty entry, producing a duplicate-object-description warning.

Verification

  • sphinx-build -n on docs/: zero warnings related to these members; both docstrings render (HasFileno.fileno in reference-io.html, the broken_by attributes block in reference-lowlevel.html).
  • check_type_completeness.py runs cleanly against the updated JSON with respect to the touched symbols (the checker's output is pyright-version-dependent locally — the pre-existing baseline also reports unrelated drift — but HasFileno.fileno now resolves to a runtime docstring via inspect.getdoc, so the diagnostic is skipped exactly as the checker intends).
  • ruff check / ruff format --check clean on touched files.

@A5rocks

A5rocks commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Duplicate of #3523

@A5rocks A5rocks marked this as a duplicate of #3523 Oct 9, 2026
@A5rocks A5rocks closed this Oct 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants