Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
donbarbos wants to merge 8 commits into
base:main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
837ead9
gh-124694: Document missing ctxkwargs argument in ThreadPoolExecutor
donbarbos May 20, 2025
850564d
Revert "changing `versionchanged` to `versionadded`"
donbarbos May 20, 2025
b47a25d
Correct more
donbarbos May 20, 2025
1e225bd
Add class method `prepare_context`
donbarbos May 20, 2025
7de4242
Merge branch 'main' into issue-124694-docs
donbarbos Dec 26, 2025
0a8b2fc
Accept suggestions
donbarbos Dec 26, 2025
19d4dad
Use :meth:
donbarbos Dec 26, 2025
f7e4f17
fix typo
donbarbos Dec 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions Doc/library/concurrent.futures.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -114,7 +114,7 @@ Executor Objects
e.submit(shutil.copy, 'src4.txt', 'dest4.txt')

.. versionchanged:: 3.9
Added *cancel_futures*.
Added the *cancel_futures* parameter.


ThreadPoolExecutor
Expand DownExpand Up@@ -154,7 +154,8 @@ And::
executor.submit(wait_on_future)


.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())
.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='', \
initializer=None, initargs=(), **ctxkwargs)

An :class:`Executor` subclass that uses a pool of at most *max_workers*
threads to execute calls asynchronously.
Expand All@@ -172,6 +173,18 @@ And::
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-storchakaserhiy-storchakaDec 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.

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

:meth:`prepare_context`, allowing customization of the worker execution
context.

.. classmethod:: prepare_context(initializer, initargs)

Setting up the necessary context for creating worker instances in a
pool-based executor (for example, in a concurrent environment like
threads or interpreters).

.. versionadded:: 3.14

.. versionchanged:: 3.5
If *max_workers* is ``None`` or
not given, it will default to the number of processors on the machine,
Expand DownExpand Up@@ -201,6 +214,10 @@ And::
Default value of *max_workers* is changed to
``min(32, (os.process_cpu_count() or 1) + 4)``.

.. versionchanged:: 3.14
Added *ctxkwargs* to pass additional arguments to :meth:`prepare_context`
class method.


.. _threadpoolexecutor-example:

Expand DownExpand Up@@ -289,7 +306,8 @@ efficient alternative is to serialize with :mod:`pickle` and then send
the bytes over a shared :mod:`socket <socket>` or
:func:`pipe <os.pipe>`.

.. class:: InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())
.. class:: InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', \
Comment thread
donbarbos marked this conversation as resolved.
initializer=None, initargs=())

A :class:`ThreadPoolExecutor` subclass that executes calls asynchronously
using a pool of at most *max_workers* threads. Each thread runs
Expand DownExpand Up@@ -349,7 +367,9 @@ per :class:`multiprocessing.Process` apply when using :meth:`~Executor.submit`
and :meth:`~Executor.map` on a :class:`ProcessPoolExecutor`. A function defined
in a REPL or a lambda should not be expected to work.

.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)
.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, \
initializer=None, initargs=(), \
max_tasks_per_child=None)

An :class:`Executor` subclass that executes calls asynchronously using a pool
of at most *max_workers* processes. If *max_workers* is ``None`` or not
Expand Down
Loading