Install & Compatibility
Where this runs
tested against v4.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.224s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.198s · 21MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ThreadPooled
✓ from threaded import ThreadPooled
threadpooled
✓ from threaded import threadpooled
Alias for ThreadPooled
Threaded
✓ from threaded import Threaded
threaded
✓ from threaded import threaded
Alias for Threaded
AsyncIOTask
✓ from threaded import AsyncIOTask
asynciotask
✓ from threaded import asynciotask
Alias for AsyncIOTask
This example demonstrates how to use the `ThreadPooled` decorator to run functions in a `ThreadPoolExecutor`. It configures a pool with 3 workers, submits 5 tasks, waits for their completion, and then explicitly shuts down the pool.
import time
import concurrent.futures
from threaded import ThreadPooled
# Configure the thread pool (optional, defaults to CPU_COUNT * 5 workers)
ThreadPooled.configure(max_workers=3)
@ThreadPooled
def process_item(item_id):
print(f"Processing item {item_id} in a thread...")
time.sleep(1) # Simulate I/O-bound work
return f"Item {item_id} processed."
if __name__ == "__main__":
print("Submitting tasks to the thread pool...")
futures = [process_item(i) for i in range(5)]
# Wait for all tasks to complete and retrieve results
for future in concurrent.futures.as_completed(futures):
try:
result = future.result()
print(f"Result: {result}")
except Exception as exc:
print(f'Task generated an exception: {exc}')
print("All tasks submitted and results collected.")
# It's crucial to explicitly shut down the thread pool for graceful exit
ThreadPooled.shutdown()
print("Thread pool shut down.")
Debug
Known issues
gotchaPython's Global Interpreter Lock (GIL) means that standard CPython threads cannot execute CPU-bound tasks in parallel across multiple cores. This library, by using `threading` and `concurrent.futures.ThreadPoolExecutor`, primarily benefits I/O-bound tasks where threads can yield the GIL while waiting. For CPU-bound parallelism, consider `multiprocessing`.fixUnderstand the GIL's implications. For true CPU-bound parallelism, use `multiprocessing` or investigate GIL-free Python builds (Python 3.13+).
affects: All versions on GIL-enabled CPython
gotchaWhen using `ThreadPooled` (which leverages `ThreadPoolExecutor`), it's important to explicitly call `ThreadPooled.shutdown()` when your application is exiting or when the pool is no longer needed. Failure to do so can lead to resource leaks, prevent the program from exiting cleanly, or cause issues during application shutdown.fixEnsure `ThreadPooled.shutdown()` is called, typically at the end of your main execution path or within a `finally` block to guarantee execution. If used as part of a longer-running service, manage its lifecycle carefully.
affects: All versions
gotchaLike any concurrency mechanism, using `threaded` with shared mutable state (e.g., global variables, class attributes, shared objects) can lead to race conditions if access is not properly synchronized. This can result in unpredictable behavior or corrupted data.fixMinimize shared mutable state. When unavoidable, use explicit synchronization primitives like `threading.Lock`, `threading.Semaphore`, or thread-safe data structures from the `queue` module to manage access to shared resources.
affects: All versions
Upgrade
Version history
4.2.0latest on PyPI · released Nov 22, 2023
Audit
Dependencies
No dependency data recorded yet.