---
id: iterators
version: "0.2.0"
license: unclear
license_treatment: permissive
maintenance: dormant
---

# iterators — Iterator utility classes and functions

License: permissive · Maintenance: dormant · Downloads: 721.8K/mo

## What it is and what it does

TimeoutIterator is a wrapper class that adds timeout semantics to any Python iterator. When you wrap an iterator with TimeoutIterator and call next() on it, the wrapper will wait for the underlying iterator to yield a value, but only up to a specified timeout duration. If the timeout expires before a value arrives, TimeoutIterator returns a sentinel object instead of blocking indefinitely or raising an exception.

The package supports both fixed timeouts (set once at construction) and dynamic timeout adjustment via set_timeout(). When a timeout occurs, iteration continues—the next call to next() will attempt to retrieve the next value from the underlying iterator with the current timeout setting. This is useful for scenarios where you're iterating over slow or potentially stalled sources and need to enforce a deadline without terminating the entire iteration.

Use it for:

- Wrap a generator that fetches data from a slow source to enforce per-item timeout and skip items that take too long.
- Protect against runaway generators in a data pipeline by returning a sentinel when iteration stalls beyond a threshold.
- Dynamically adjust timeout thresholds during iteration based on observed latency or changing system conditions.
- Iterate over file handles or network streams with a deadline, gracefully handling slow or hung sources.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Wraps Python iterators to add timeout behavior, returning a sentinel value when iteration takes longer than a specified duration.

Yes, if you need simple timeout semantics on synchronous iterators and can tolerate dormant maintenance. The package has no dependencies, low install friction, and a permissive license. However, verify that the timeout mechanism meets your concurrency and performance requirements before relying on it in production—the project has not been actively maintained since early 2023.

## Install

pip install iterators
uv add iterators
poetry add iterators

## Installing iterators

Before you install: Low install friction with no runtime dependencies. Package is dormant—last release was 2023-01-23 with no commits since 2024-07-31—so expect no active maintenance or bug fixes.

License in practice: MIT license (permissive) means you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

from iterators import TimeoutIterator

def iter_with_sleep():
    yield 1
    yield 2

i = iter_with_sleep()
it = TimeoutIterator(i, timeout=0.5)
print(next(it))
print(next(it))

Requires Python 3.6 or later.

Verify before relying:

- Whether TimeoutIterator works correctly with generators that yield at unpredictable intervals or with very short timeout windows.
- Whether the timeout mechanism is thread-safe or suitable for concurrent iteration scenarios.
- Performance overhead of wrapping iterators, especially for high-frequency iteration patterns.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 721.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

iterator timeout wrapper, timeout for iterators, iterator with timeout, iteration timeout control, timeout sentinel iterator, iterator deadline enforcement, sync iterator timeout, iterator-control, timeout-wrapper

[View on SkillFed](https://skillfed.io/packages/iterators) · [View on PyPI](https://pypi.org/project/iterators/)