FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-124694: Document missing ctxkwargs argument in ThreadPoolExecutor by donbarbos · Pull Request #134321 · python/cpython · GitHub

/ cpython Public

gh-124694: Document missing ctxkwargs argument in ThreadPoolExecutor - #134321

Open
donbarbos wants to merge 8 commits into
python:mainfrom
donbarbos:issue-124694-docs
ConversationCommits (8)ChecksFiles changed
Open

gh-124694: Document missing ctxkwargs argument in ThreadPoolExecutor#134321
donbarbos wants to merge 8 commits into
python:mainfrom
donbarbos:issue-124694-docs

Conversation

donbarbos commented May 20, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

bedevere-app Bot added docs Documentation in the Doc dir skip news labels May 20, 2025
bedevere-app Bot mentioned this pull request May 20, 2025
Closed
github-project-automation Bot moved this to Todo in Docs PRs May 20, 2025

donbarbos commented May 20, 2025

Copy link
Copy Markdown
Contributor Author

cc @picnixz

picnixz added the needs backport to 3.14 bugs and security fixes label May 20, 2025
picnixz reviewed May 20, 2025
View reviewed changes
Comment thread Doc/library/concurrent.futures.rst
picnixz reviewed May 20, 2025
View reviewed changes

picnixz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I don't know if the parameters are meant to be public but the signature indeed needs to be correct for possible subclassing.

However, prepare_context is not documented so we can't even know how to use them. So we need to also document this at the same time.

picnixz requested a review from ericsnowcurrently May 20, 2025 12:22

donbarbos commented May 20, 2025

Copy link
Copy Markdown
Contributor Author

I don't know if the parameters are meant to be public but the signature indeed needs to be correct for possible subclassing.

ctxkwargs argument described in ThreadPoolExecutor.__init__ docstring.

And maybe I'm missing something but this is what the class method prepare_context looks like (I don't know how **ctxkwargs should be passed here if this argument is omitted in prepare_context):

cpython/Lib/concurrent/futures/thread.py

Lines 157 to 187 in 5ab66a8

@classmethod
def prepare_context(cls, initializer, initargs):
return WorkerContext.prepare(initializer, initargs)
def __init__(self, max_workers=None, thread_name_prefix='',
initializer=None, initargs=(), **ctxkwargs):
"""Initializes a new ThreadPoolExecutor instance.
Args:
max_workers: The maximum number of threads that can be used to
execute the given calls.
thread_name_prefix: An optional name prefix to give our threads.
initializer: A callable used to initialize worker threads.
initargs: A tuple of arguments to pass to the initializer.
ctxkwargs: Additional arguments to cls.prepare_context().
"""
if max_workers is None:
# ThreadPoolExecutor is often used to:
# * CPU bound task which releases GIL
# * I/O bound task (which releases GIL, of course)
#
# We use process_cpu_count + 4 for both types of tasks.
# But we limit it to 32 to avoid consuming surprisingly large resource
# on many core machine.
max_workers = min(32, (os.process_cpu_count() or 1) + 4)
if max_workers <= 0:
raise ValueError("max_workers must be greater than 0")
(self._create_worker_context,
self._resolve_work_item_task,
) = type(self).prepare_context(initializer, initargs, **ctxkwargs)

picnixz commented May 20, 2025

Copy link
Copy Markdown
Member

And maybe I'm missing something but this is what the class method prepare_context looks like (I don't know how **ctxkwargs should be passed here if this argument is omitted in prepare_context):

in this case, we should wait for Eric's feedback. I'm away until Saturday so I won't be able to reply in the meantime.

StanFromIreland reviewed May 20, 2025
View reviewed changes
Comment thread Doc/library/concurrent.futures.rst Outdated
serhiy-storchaka reviewed Dec 26, 2025
View reviewed changes
Comment thread Doc/library/concurrent.futures.rst Outdated

donbarbos commented Dec 26, 2025

Copy link
Copy Markdown
Contributor Author

Thanks everyone for suggestions, now it looks complete

serhiy-storchaka reviewed Dec 26, 2025
View reviewed changes
Comment thread Doc/library/concurrent.futures.rst
pending jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`,
as well as any attempt to submit more jobs to the pool.

*ctxkwargs* is a mapping of additional keyword arguments passed to

serhiy-storchaka Dec 26, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

The ctxkwargs parameter is special -- it does not correspond to a single argument. I am not even sure that it should be documented, since it is only purpose is to be able to pass shared to prepare_context() in InterpreterPoolExecutor(). It may be an implementation detail, in which case I am not sure that it should be documented.

If we still document this, I would write something like "Any addition keyword arguments are passed to prepare_context()." And updated the docstring correspondingly.

cc @ericsnowcurrently

github-actions Bot commented Apr 25, 2026

Copy link
Copy Markdown

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

github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 25, 2026
serhiy-storchaka added the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label May 30, 2026
github-actions Bot removed the stale Stale PR or inactive for long period of time. label May 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

serhiy-storchaka serhiy-storchaka left review comments
picnixz picnixz left review comments
StanFromIreland StanFromIreland left review comments
ericsnowcurrently Awaiting requested review from ericsnowcurrently

Assignees

No one assigned

Labels

awaiting review docs Documentation in the Doc dir needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes skip news

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

Back | FazBrowse Home | New Git URL