[doc] Clarify that Popen.wait is only a busy-loop in certain cases
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 36k
- PR merge metrics
- PR metrics pending
Description
Documentation
In the docs for Popen.wait(), it states:
Note The function is implemented using a busy loop (non-blocking call and short sleeps). Use the asyncio module for an asynchronous wait: see asyncio.create_subprocess_exec.
This is actually only true in a specific circumstance: when both using Posix/Unix and a timeout is given. If, on the other hand, no timeout is given, then it does not go into a busy-loop but instead blocks on os.waitpid(). And for Windows, it never goes into a busy-loop, as it uses the WaitForSingleObject() windows API.
This note in the docs caused me to refactor my code to use asyncio - only later did I actually check what python did internally and discovered the note was wrong.
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
Start with the Popen.wait() documentation linked in the issue and compare the note with the platform and timeout behavior described here. Revise the note so it limits the busy-loop claim to POSIX/Unix waits with a timeout while accurately covering no-timeout and Windows cases. Done means the wording is technically correct and retains the asyncio guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100