python / python/cpython

[doc] Clarify that Popen.wait is only a busy-loop in certain cases

Open
#94,033 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

docs
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.