Install & Compatibility
Where this runs
tested against v1.1.2 · 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.219s · 19.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.189s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ThreadingTimeout
✓ from stopit import ThreadingTimeout
✗ from stopit import ThreadingTimeout
This quickstart demonstrates using `stopit.ThreadingTimeout` as a context manager and `stopit.threading_timeoutable` as a decorator to limit the execution time of code. The context manager allows checking its state to determine if execution completed or timed out. The decorator automatically returns a default value if the function exceeds its allowed time.
import stopit
import time
print("Starting long running task with 5-second timeout...")
with stopit.ThreadingTimeout(5) as context_manager:
# Simulate a long-running operation
for i in range(10**8):
_ = i * 2 # Some computation
if not context_manager.state == context_manager.EXECUTING: # Optional: check state inside loop
break
if context_manager.state == context_manager.EXECUTED:
print("Task completed within timeout.")
elif context_manager.state == context_manager.TIMED_OUT:
print("Task timed out after 5 seconds.")
# Example using a decorator
@stopit.threading_timeoutable(default='Timed out!')
def potentially_long_function(timeout=1, max_iterations=10**8):
print(f" Function starting with {timeout}s timeout...")
for i in range(max_iterations):
_ = i * 2
time.sleep(0.001) # Small sleep to allow thread context switching
return "Function completed."
result = potentially_long_function(timeout=2)
print(f"Decorator result: {result}")
result_fast = potentially_long_function(timeout=10, max_iterations=1000)
print(f"Decorator result (fast completion): {result_fast}")
Debug
Known issues
breakingIn version 1.1.0, the main context manager `stopit.Timeout` was renamed to `stopit.ThreadingTimeout`, and the decorator `stopit.timeoutable` was renamed to `stopit.threading_timeoutable`. Using the old names will result in import errors or unexpected behavior.fixUpdate your imports and usage to `ThreadingTimeout` and `threading_timeoutable` respectively.
affects: 1.0.0 and earlier
gotchaSignal-based timeout controls (`SignalTimeout` and `signal_timeoutable`) are not supported on Windows due to the operating system's lack of `signal.SIGALRM` support.fixUse the threading-based context managers (`ThreadingTimeout`) and decorators (`threading_timeoutable`) which are platform-independent for basic timeout functionality.
affects: All versions
gotchaThreading-based timeout mechanisms (like `ThreadingTimeout`) will only work reliably with CPython implementations. They rely on CPython-specific low-level APIs and are not compatible with alternative Python implementations like PyPy, Jython, or IronPython.fixEnsure your application is running on CPython. Be aware that `stopit` might not be suitable for projects requiring broad Python interpreter compatibility.
affects: All versions
gotchaThe library cannot stop the execution of blocking Python atomic instructions that acquire the Global Interpreter Lock (GIL), such as `time.sleep()` for long durations or I/O operations. The asynchronous exception will only be effective *after* such blocking operations complete.fixFor very precise or immediate interruption of blocking I/O or long `time.sleep` calls, consider using `multiprocessing` to run the task in a separate process that can be terminated.
affects: All versions
gotchaVery short timeout values, especially zero, can lead to unexpected `TimeoutException` being raised immediately or trigger race conditions, particularly on Windows/Cygwin. The accuracy of timeouts generally depends on the GIL interval checking of your Python platform.fixAvoid setting extremely small or zero timeout values. If precise, sub-millisecond control is critical, `stopit` might not be the ideal solution due to Python's GIL and thread scheduling characteristics.
affects: All versions
Upgrade
Version history
1.1.2latest on PyPI · released Feb 9, 2018
Audit
Dependencies
No dependency data recorded yet.