From 837ead9205fb786e7fd170266a8c7986ec10bf31 Mon Sep 17 00:00:00 2001 From: donBarbos Date: Tue, 20 May 2025 13:30:46 +0400 Subject: [PATCH 1/4] gh-124694: Document missing ctxkwargs argument in ThreadPoolExecutor --- Doc/library/concurrent.futures.rst | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index 3c8d9ab111e09e..6dd4ce03b60b13 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -71,10 +71,10 @@ Executor Objects :class:`ThreadPoolExecutor` and :class:`InterpreterPoolExecutor`, *chunksize* has no effect. - .. versionchanged:: 3.5 + .. versionadded:: 3.5 Added the *chunksize* parameter. - .. versionchanged:: 3.14 + .. versionadded:: 3.14 Added the *buffersize* parameter. .. method:: shutdown(wait=True, *, cancel_futures=False) @@ -113,7 +113,7 @@ Executor Objects e.submit(shutil.copy, 'src3.txt', 'dest3.txt') e.submit(shutil.copy, 'src4.txt', 'dest4.txt') - .. versionchanged:: 3.9 + .. versionadded:: 3.9 Added *cancel_futures*. @@ -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. @@ -180,12 +181,12 @@ And:: should be higher than the number of workers for :class:`ProcessPoolExecutor`. - .. versionchanged:: 3.6 + .. versionadded:: 3.6 Added the *thread_name_prefix* parameter to allow users to control the :class:`threading.Thread` names for worker threads created by the pool for easier debugging. - .. versionchanged:: 3.7 + .. versionadded:: 3.7 Added the *initializer* and *initargs* arguments. .. versionchanged:: 3.8 @@ -201,6 +202,10 @@ And:: Default value of *max_workers* is changed to ``min(32, (os.process_cpu_count() or 1) + 4)``. + .. versionadded:: 3.14 + Added *ctxkwargs* to pass additional arguments to ``cls.prepare_context`` + class method. + .. _threadpoolexecutor-example: @@ -287,7 +292,8 @@ efficient alternative is to serialize with :mod:`pickle` and then send the bytes over a shared :mod:`socket ` or :func:`pipe `. -.. class:: InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=(), shared=None) +.. class:: InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', \ + initializer=None, initargs=(), shared=None) A :class:`ThreadPoolExecutor` subclass that executes calls asynchronously using a pool of at most *max_workers* threads. Each thread runs @@ -357,7 +363,9 @@ that :class:`ProcessPoolExecutor` will not work in the interactive interpreter. Calling :class:`Executor` or :class:`Future` methods from a callable submitted to a :class:`ProcessPoolExecutor` will result in deadlock. -.. 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 @@ -394,13 +402,13 @@ to a :class:`ProcessPoolExecutor` will result in deadlock. was undefined but operations on the executor or its futures would often freeze or deadlock. - .. versionchanged:: 3.7 + .. versionadded:: 3.7 The *mp_context* argument was added to allow users to control the start_method for worker processes created by the pool. Added the *initializer* and *initargs* arguments. - .. versionchanged:: 3.11 + .. versionadded:: 3.11 The *max_tasks_per_child* argument was added to allow users to control the lifetime of workers in the pool. From 850564d16b1314d6fb4b216613862ebb3e57e8f1 Mon Sep 17 00:00:00 2001 From: donBarbos Date: Tue, 20 May 2025 14:13:46 +0400 Subject: [PATCH 2/4] Revert "changing `versionchanged` to `versionadded`" --- Doc/library/concurrent.futures.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index 6dd4ce03b60b13..ea9a5fd6434fde 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -71,10 +71,10 @@ Executor Objects :class:`ThreadPoolExecutor` and :class:`InterpreterPoolExecutor`, *chunksize* has no effect. - .. versionadded:: 3.5 + .. versionchanged:: 3.5 Added the *chunksize* parameter. - .. versionadded:: 3.14 + .. versionchanged:: 3.14 Added the *buffersize* parameter. .. method:: shutdown(wait=True, *, cancel_futures=False) @@ -114,7 +114,7 @@ Executor Objects e.submit(shutil.copy, 'src4.txt', 'dest4.txt') .. versionadded:: 3.9 - Added *cancel_futures*. + Added the *cancel_futures* parameter. ThreadPoolExecutor @@ -181,12 +181,12 @@ And:: should be higher than the number of workers for :class:`ProcessPoolExecutor`. - .. versionadded:: 3.6 + .. versionchanged:: 3.6 Added the *thread_name_prefix* parameter to allow users to control the :class:`threading.Thread` names for worker threads created by the pool for easier debugging. - .. versionadded:: 3.7 + .. versionchanged:: 3.7 Added the *initializer* and *initargs* arguments. .. versionchanged:: 3.8 @@ -202,7 +202,7 @@ And:: Default value of *max_workers* is changed to ``min(32, (os.process_cpu_count() or 1) + 4)``. - .. versionadded:: 3.14 + .. versionchanged:: 3.14 Added *ctxkwargs* to pass additional arguments to ``cls.prepare_context`` class method. @@ -402,13 +402,13 @@ to a :class:`ProcessPoolExecutor` will result in deadlock. was undefined but operations on the executor or its futures would often freeze or deadlock. - .. versionadded:: 3.7 + .. versionchanged:: 3.7 The *mp_context* argument was added to allow users to control the start_method for worker processes created by the pool. Added the *initializer* and *initargs* arguments. - .. versionadded:: 3.11 + .. versionchanged:: 3.11 The *max_tasks_per_child* argument was added to allow users to control the lifetime of workers in the pool. From b47a25d7aaadf928bc24b7499fb98f3046f3826b Mon Sep 17 00:00:00 2001 From: donBarbos Date: Tue, 20 May 2025 14:16:51 +0400 Subject: [PATCH 3/4] Correct more --- Doc/library/concurrent.futures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index ea9a5fd6434fde..5839e21295e6e9 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -113,7 +113,7 @@ Executor Objects e.submit(shutil.copy, 'src3.txt', 'dest3.txt') e.submit(shutil.copy, 'src4.txt', 'dest4.txt') - .. versionadded:: 3.9 + .. versionchanged:: 3.9 Added the *cancel_futures* parameter. From 1e225bdfc59c86efe19a696ce86c966cb6b1268e Mon Sep 17 00:00:00 2001 From: donBarbos Date: Tue, 20 May 2025 17:49:59 +0400 Subject: [PATCH 4/4] Add class method `prepare_context` --- Doc/library/concurrent.futures.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index 5839e21295e6e9..8112fb987adfdb 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -206,6 +206,11 @@ And:: Added *ctxkwargs* to pass additional arguments to ``cls.prepare_context`` class method. + .. classmethod:: prepare_context(initializer, initargs) + Setting up the necessary context for creating worker instances in a pool-based executor (e.g., in a concurrent environment like threads or interpreters). + + .. versionadded:: 3.14 + .. _threadpoolexecutor-example: