python-concurrency

name	python-concurrency
description	Use for choosing between threads, `asyncio`, `multiprocessing`, and PEP 734 subinterpreters in Python. Covers workload shape (CPU vs I/O), shared state and the GIL, cancellation, and the `concurrent.interpreters` / `InterpreterPoolExecutor` API new in Python 3.14.
globs	["**/*.py"]

Python Concurrency

Use this when the question is which concurrency model fits the workload and how to keep state safe across it.

Working stance

• Start from the workload shape, not the API. CPU-bound, I/O-bound, and blocking-but-cheap have different answers.
• Prefer the model with the least shared mutable state. Asyncio if all work is awaitable; threads if some library blocks; interpreters or processes if pure Python must scale across cores.
• Treat the global interpreter lock (GIL) as a fact about CPython: one interpreter, one Python bytecode at a time. Free-threaded CPython (PEP 703, opt-in) lifts that; PEP 734 lifts it via per-interpreter GILs.
• Set timeouts and cancellation policy at the boundary; never let a worker decide on its own when to abandon work.

Decision surface

• asyncio: I/O-bound work with cooperative scheduling. Single thread, single interpreter, everything awaitable. Use asyncio.TaskGroup for structured concurrency; never await inside a for over a list of coroutines when gather or a task group is the right shape.
• threading / concurrent.futures.ThreadPoolExecutor: blocking I/O libraries (database drivers, OS file calls) that cannot be made async. Threads share memory; protect mutable state with Lock, RLock, or a queue.
• multiprocessing / ProcessPoolExecutor: CPU-bound pure Python today. Each process is its own interpreter and its own GIL; pay the pickling and fork cost on every task.
• PEP 734 subinterpreters (Python 3.14+): CPU-bound pure Python without the fork cost. concurrent.interpreters and InterpreterPoolExecutor give a per-interpreter GIL with a single process and an explicit cross-interpreter queue.Queue.
• Free-threaded CPython (PEP 703): experimental in 3.13, supported in 3.14. One interpreter, no GIL. Useful when C extensions are thread-safe and the build is acceptable to operators.

PEP 734 in practice

from concurrent.futures import InterpreterPoolExecutor

with InterpreterPoolExecutor(max_workers=4) as pool:
    futures = [pool.submit(compute, n) for n in inputs]
    results = [f.result() for f in futures]

What changes versus a thread pool:

• Each worker has its own interpreter and its own GIL; CPU-bound pure Python scales.
• No Python objects are shared. Arguments are serialized across the boundary; return values likewise.
• concurrent.interpreters.create_queue() returns a cross-interpreter queue.Queue implementation for streaming or fan-in/fan-out work when futures are not enough.
• C extensions must opt in to per-interpreter GIL support (Py_mod_multiple_interpreters); pure-Python work always works.

Async discipline

• Default to asyncio.TaskGroup (3.11+) for fan-out. Structured concurrency means a failure cancels siblings deterministically and the context manager re-raises an ExceptionGroup containing every task failure.
• Reach for asyncio.gather only when the call is tolerant fan-out: pass return_exceptions=True and inspect the result list. Bare gather(...) leaks unfinished tasks on the first failure.
• Treat task.cancel() as a request: schedule the cancellation, then await the task to know whether it finished, cancelled, or raised. Never swallow CancelledError — let it propagate after any cleanup so the cancellation chain completes.
• Wrap a coroutine in asyncio.shield(...) only when the inner work must finish even if the caller is cancelled (final flush, commit, audit log). Document the rule; orphaned shielded work hides bugs.
• Set timeouts with asyncio.timeout() rather than wait_for; the context manager is cancellation-safe and composes with TaskGroup.
• Custom task factories belong at the loop boundary: use them for context propagation (contextvars), logging tags, and observability. Switch to asyncio.eager_task_factory (3.12+) when profiling shows the deferred-start cost matters and the codebase does not rely on lazy task semantics.
• Never call blocking I/O on the event loop. asyncio.to_thread or a thread pool offloads it.
• asyncio.run(main()) once per process; nested loops are an anti-pattern.

Red flags

• asyncio mixed with blocking calls inside the same coroutine,
• threads coordinating via a shared list without a Lock,
• a thread pool used for CPU-bound work where a process pool or subinterpreter pool would scale,
• multiprocessing.Pool chosen when the work is already async,
• a subinterpreter worker that tries to share a mutable object across the boundary,
• time.sleep inside an async coroutine,
• cancellation that relies on the worker checking a flag at every iteration rather than catching CancelledError.

Read subinterpreters-pep734.md and workload-shape-matrix.md when the workload shape or the choice between threads, asyncio, and interpreters dominates. Read async-task-discipline.md when the question is TaskGroup versus gather, cancellation and shield semantics, or task factories.