Skip to main content

python-timeout-iterator

timeout-iterator provides a timeout in iteration.

Python PyPI version Coverage License

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 check and uv 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)

Source distribution for timeout-iterator 0.3.0
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)

Table of built distributions (wheels) for timeout-iterator 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page