python-trio / python-trio/trio
Some publicly exposed functions/properties have no documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 7.3k
- Forks
- 431
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 6
Description
This issue should only really be looked at after https://github.com/python-trio/trio/issues/3221 is closed (because this is mainly about what people see in an editor, rather than our documentation). The following attributes are listed in our _type_completeness.json as not having a docstring:
-
trio._unix_pipes.FdStream.send_all -
trio._unix_pipes.FdStream.wait_send_all_might_not_block -
trio._unix_pipes.FdStream.receive_some -
trio._unix_pipes.FdStream.close -
trio._unix_pipes.FdStream.aclose -
trio._unix_pipes.FdStream.fileno -
trio._core._io_epoll._EpollStatistics -
trio._channel.MemoryReceiveChannel -
trio._channel.MemoryChannelStatistics -
trio._channel.MemorySendChannel -
trio._core._run.Task -
trio._socket.SocketType -
trio._highlevel_socket.SocketStream.send_all -
trio._highlevel_socket.SocketStream.wait_send_all_might_not_block -
trio._highlevel_socket.SocketStream.send_eof -
trio._highlevel_socket.SocketStream.receive_some -
trio._highlevel_socket.SocketStream.aclose -
trio._subprocess.HasFileno.fileno -
trio._sync.AsyncContextManagerMixin -
trio._sync._HasAcquireRelease.acquire -
trio._sync._HasAcquireRelease.release -
trio._sync._LockImpl -
trio._core._local._NoValue -
trio._core._local.RunVarToken -
trio.socket.gaierror -
trio.socket.herror -
trio._core._mock_clock.MockClock.start_clock -
trio._core._mock_clock.MockClock.current_time -
trio._core._mock_clock.MockClock.deadline_to_sleep_time -
trio.testing._raises_group._ExceptionInfo.exconly -
trio.testing._raises_group._ExceptionInfo.errisinstance -
trio.testing._raises_group._ExceptionInfo.getrepr -
trio.testing._raises_group.RaisesGroup.expected_type
I expect most of these are trivial. There's a couple groups I noticed while copying them over:
- some aren't actually publicly exposed and so we should update
check_type_completeness.pyto filter them out (e.g._HasAcquireRelease) - some should really just inherit documentation from parents (e.g.
SocketStream.wait_send_all_might_not_block). I don't know if pyright supports anything like that but it should
I think some of the logic from check_type_completeness.py is kind of strange: it shouldn't filter out docstrings that are available at runtime because... pyright still can't see those?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Wait for issue #3221 to close, then inspect _type_completeness.json and check_type_completeness.py alongside the listed attributes. Determine which missing docstrings need additions, which entries should be filtered, and whether inherited documentation is supported. Done means the checker and editor-facing type completeness no longer report the applicable attributes as undocumented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- developer-experience, documentation, tooling
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100