Skip to content

gh-142041: Improve concurrent.interpreters documentation - #145657

Open
mvanhorn wants to merge 3 commits into
python:mainfrom
mvanhorn:osc/142041-improve-interpreters-docs
Open

mvanhorn wants to merge 3 commits into
python:mainfrom
mvanhorn:osc/142041-improve-interpreters-docs

Conversation

@mvanhorn

@mvanhorn mvanhorn commented Mar 9, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #142041.

Improves the concurrent.interpreters documentation with:

  • Queue class: Added complete method documentation (put, get, empty, full, qsize, put_nowait, get_nowait, maxsize) with parameter descriptions including the unbounditems behavior
  • prepare_main: Expanded description explaining its purpose as the primary way to pass data to subinterpreters, with a usage example
  • exec: Fixed incorrect signature (removed non-existent dedent parameter), added description of behavior, return value, error handling, and blocking semantics
  • call and call_in_thread: Expanded descriptions covering supported callables, pickle fallback, error handling, and thread behavior
  • create_queue: Documented maxsize and unbounditems parameters
  • is_shareable: Added missing function documentation
  • Basic usage section: Rewrote with clearer, separated examples covering exec/call, prepare_main, queue communication, and parallel execution patterns
  • Added tip pointing users to InterpreterPoolExecutor for simpler use cases

This contribution was developed with AI assistance (Claude Code).


📚 Documentation preview 📚: https://cpython-previews--145657.org.readthedocs.build/

- Add complete Queue method documentation (put, get, empty, full, qsize,
  maxsize, put_nowait, get_nowait) with parameter descriptions
- Expand prepare_main docs explaining its purpose with an example
- Fix exec() signature (remove incorrect dedent parameter)
- Add detailed exec() and call() descriptions with error handling info
- Expand call_in_thread docs explaining thread behavior
- Document create_queue parameters (maxsize, unbounditems)
- Add is_shareable() function documentation
- Rewrite Basic usage section with clearer examples for exec, call,
  prepare_main, queues, and parallel execution patterns
- Add tip pointing to InterpreterPoolExecutor for simpler use cases

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@python-cla-bot

python-cla-bot Bot commented Mar 9, 2026 •

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app bedevere-app Bot added the docs Documentation in the Doc dir label Mar 9, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Mar 9, 2026
UNBOUND, UNBOUND_ERROR, UNBOUND_REMOVE, and ItemInterpreterDestroyed
are not in the module's public __all__, so use literal backticks
instead of :data: and :exc: roles.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@github-actions

github-actions Bot commented May 8, 2026

Copy link
Copy Markdown

This PR is stale because it has been open for 30 days with no activity.

@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label May 8, 2026
@serhiy-storchaka

Copy link
Copy Markdown
Member

@ericsnowcurrently, could you please review this PR?

@github-actions github-actions Bot removed the stale Stale PR or inactive for long period of time. label Jun 9, 2026
@github-actions

Copy link
Copy Markdown

This PR is stale because it has been open for 90 days with no activity.

@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label Sep 10, 2026
…interpreters-docs

# Conflicts:
#	Doc/library/concurrent.interpreters.rst
@mvanhorn

Copy link
Copy Markdown
Contributor Author

Merged main in be75cd2. gh-136563 had since documented the Queue methods and fixed the exec signature, so I kept main's version of those parts (QueueEmpty/QueueFull names, no unbounditems) and kept this PR's additions on top: is_shareable(), Queue.maxsize, fuller prepare_main/exec/call/call_in_thread text, and the extra examples. The NEWS entry now only describes what is left. sphinx-lint is clean on both files.

@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35519443 | 📁 Comparing be75cd2 against main (1e406e6)

  🔍 Preview build  

2 files changed
± library/concurrent.interpreters.html
± whatsnew/changelog.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir stale Stale PR or inactive for long period of time.

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

Improve concurrent.interpreters documentation

2 participants