Skip to content

Add docstrings for HasFileno.fileno and ParkingLot.broken_by - #3526

Closed
faresrafat3 wants to merge 1 commit into
python-trio:mainfrom
faresrafat3:trio-3221-docstrings
Closed

faresrafat3 wants to merge 1 commit into
python-trio:mainfrom
faresrafat3:trio-3221-docstrings

Conversation

@faresrafat3

Copy link
Copy Markdown

Fixes #3221.

trio._subprocess.HasFileno.fileno and ParkingLot.broken_by are both part
of the public interface but had no documentation. HasFileno.fileno was the
last remaining unchecked item in the "Some functions and properties in the
documentation have no docstring" checklist, and broken_by was rendered in
the low-level reference only because ParkingLot is documented with
:undoc-members:, so it showed up as a bare attribute name.

Changes

  • HasFileno.fileno: added a docstring describing what the method returns and
    noting that it mirrors io.IOBase.fileno.
  • ParkingLot: documented broken_by in the class's Attributes: section,
    matching how other Trio classes describe their attributes.
  • _check_type_completeness.json: removed the now-resolved entry
    No docstring found for function "trio._subprocess.HasFileno.fileno".

Verification

The type completeness checker reports the entry as resolved rather than as a
new error:

$ python src/trio/_tests/check_type_completeness.py
********************
Checking Linux...
Congratulations, you have resolved existing errors! Please remove them from
.../_check_type_completeness.json
['No docstring found for function "trio._subprocess.HasFileno.fileno"']

After removing that entry, the checker passes clean on all three platforms
(Linux, Windows, Darwin).

pyright --verifytypes=trio still reports 99.6% completeness, with the
missing-docstring counts unchanged for every other symbol.

The parking-lot tests pass:

$ pytest src/trio/_core/_tests/test_parking_lot.py
11 passed

The failures in test_exports.py::test_static_tool_sees_all_symbols are
pre-existing in this environment (they require pylint and jedi, which are
not installed here) and are unaffected by this change; I confirmed they fail
identically on the unmodified checkout.

Both symbols are part of the public interface and appeared in the
documentation via `:undoc-members:` without any description.

HasFileno.fileno is now documented like the io.IOBase.fileno it mirrors,
and ParkingLot documents broken_by in its Attributes section.

This resolves the remaining item tracked in _check_type_completeness.json,
so that entry is removed.
Copilot AI balanced review requested due to automatic review settings September 30, 2026 21:01

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@A5rocks

A5rocks commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

I prefer #3523

@A5rocks A5rocks closed this Sep 30, 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.

Some functions and properties in the documentation have no docstring

3 participants