gh-124694: Document missing ctxkwargs argument in ThreadPoolExecutor

[donbarbos]

based: #129669 (comment)

needs backport only to 3.14

• Issue: Add concurrent.futures.InterpreterPoolExecutor #124694

---

📚 Documentation preview 📚: https://cpython-previews--134321.org.readthedocs.build/en/134321/library/concurrent.futures.html

[donbarbos]

cc @picnixz

[picnixz]

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.

[donbarbos]

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]

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.

[donbarbos]

Thanks everyone for suggestions, now it looks complete

[serhiy-storchaka]

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