python-timeout-iterator
timeout-iterator provides a timeout in iteration.
Installation
$ pip install timeout-iterator
Usage
without_terminate
without_terminate stops yielding items once the timeout elapses without
raising an exception. It is safe to use on all platforms because it does not
use signals.
import time
from timeout_iterator import without_terminate
results = []
for i in without_terminate(range(10), seconds=0.3):
results.append(i)
time.sleep(0.1)
assert results == [0, 1, 2]
Boundary behavior: The timeout is checked after each item is fetched
from the upstream iterator. If the deadline passes between a fetch and its
yield, the fetched item is silently dropped. At most one item near the
boundary may be consumed from the upstream but not passed to the caller.
This differs from terminate, which delivers every item fetched before the
SIGALRM fires.
terminate
terminate is a generator that it will raise an exception after the timeout.
This function uses signal.SIGALRM and signal.setitimer(), so it is only
supported on Unix-like platforms that provide those signal APIs.
Signal interaction: terminate installs a SIGALRM handler for its
duration. Any SIGALRM that arrives before the timeout elapses is silently
discarded — the previous handler is not called for those signals. Libraries or
code that also use signal.alarm() / signal.setitimer() will have their
signals suppressed until the iterator exits.
import time
from timeout_iterator import terminate
try:
results = []
for i in terminate(range(10), seconds=0.3):
results.append(i)
time.sleep(0.1)
except TimeoutError:
pass
assert results == [0, 1, 2]
Main-thread only: signal.signal() and signal.setitimer() are
main-thread APIs in CPython. Calling terminate() from a worker thread
(e.g. inside threading.Thread or concurrent.futures.ThreadPoolExecutor)
raises ValueError immediately. Use without_terminate() for thread-safe
timeout iteration.
Signal scope: SIGALRM is delivered at any Python bytecode boundary in
the calling thread — not only during fetches from the upstream iterator. The
loop body itself can be interrupted and raise TimeoutError. Keep loop body
code safe to interrupt at any point, or use without_terminate if you need the
upstream items to be fully consumed before yielding control.
Development
This repository uses lefthook to run the same checks as CI locally, so problems surface before they reach CI.
# Install dependencies
uv sync
# Install the Git hooks (once; requires lefthook on your PATH)
lefthook install
Once installed, the hooks run automatically:
- pre-commit:
uv run poe check - pre-push:
uv run poe checkanduv run poe test
You can also run the checks manually:
uv run poe check
uv run poe test
CI still runs the full matrix (see .github/workflows/); the hooks only bring that
feedback earlier on your machine.
LICENSE
BSD 3-Clause License
Metadata
Release files for timeout-iterator 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| timeout_iterator-0.3.0.tar.gz | 54.8 kB | With provenance | Details for timeout_iterator-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| timeout_iterator-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for timeout_iterator-0.3.0-py3-none-any.whl |
Total release size: 63.4 kB
Release files / timeout_iterator-0.3.0.tar.gz
| Download URL | timeout_iterator-0.3.0.tar.gz |
|---|---|
| Size | 54.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9b3b8b3b9188f2a58231f316641479860ab6e6d387d45110d8f058360301aa45
|
|
BLAKE2b-256 checksum How to use checksums |
9b4da9114c5c031622e1ae186c7aaf2327745c137f6ce4a624fc321dce965638
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logRelease files / timeout_iterator-0.3.0-py3-none-any.whl
| Download URL | timeout_iterator-0.3.0-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7090eae71450f8a7183076024585da77e1374828c2a2a129d6940ad860f85e86
|
|
BLAKE2b-256 checksum How to use checksums |
dd26b806285c947eecac30f056fbd7ca07c8a3933d8035d77ba5248dafc26a7f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logSecurity for timeout-iterator 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for timeout_iterator-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.