{"id":4964,"library":"iterators","title":"Iterator Utility Classes and Functions","description":"The `iterators` library provides utility classes and functions for working with Python iterators. It includes features like adding timeouts to iterators and creating synchronous/asynchronous pipelines. The current version is 0.2.0, with an irregular release cadence as new utility features are added.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/leangaurav/pypi_iterator","tags":["iterator","utility","timeout","async","sync","pipeline"],"install":[{"cmd":"pip install iterators","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"TimeoutIterator","correct":"from iterators import TimeoutIterator"},{"symbol":"IteratorPipe","correct":"from iterators import IteratorPipe"}],"quickstart":{"code":"import time\nfrom iterators import TimeoutIterator\n\ndef my_slow_iterator():\n    yield 1\n    time.sleep(0.6) # This sleep might cause a timeout\n    yield 2\n    time.sleep(0.4)\n    yield 3\n\nprint(\"--- Demonstrating TimeoutIterator ---\")\n# Example 1: Basic iteration\ni = my_slow_iterator()\nit = TimeoutIterator(i)\nprint(f\"Next: {next(it)}\") # Expected: 1\nprint(f\"Next: {next(it)}\") # Expected: 2 (if timeout not hit)\nprint(f\"Next: {next(it)}\") # Expected: 3\ntry:\n    next(it)\nexcept StopIteration:\n    print(\"StopIteration: Iterator exhausted.\")\n\nprint(\"\\n--- Demonstrating Timeout with Sentinel ---\")\ni_timeout = my_slow_iterator()\nit_timeout = TimeoutIterator(i_timeout, timeout=0.5)\nprint(f\"Next (with timeout): {next(it_timeout)}\") # Expected: 1\n# The next call will likely hit the timeout if sleep is 0.6s and timeout 0.5s\nsentinel_value = next(it_timeout)\nif sentinel_value == it_timeout.get_sentinel():\n    print(\"Timeout occurred, sentinel value returned.\")\nelse:\n    print(f\"Next (after potential timeout): {sentinel_value}\")\n\n# Continue to consume remaining items, potentially with adjusted timeout\nit_timeout.set_timeout(0.7) # Adjust timeout dynamically\ntry:\n    print(f\"Next (after timeout reset): {next(it_timeout)}\")\n    print(f\"Next (final item): {next(it_timeout)}\")\nexcept StopIteration:\n    print(\"StopIteration: Iterator exhausted after timeout handling.\")\n\n","lang":"python","description":"This example demonstrates the `TimeoutIterator` class, which wraps an existing iterator to introduce a timeout mechanism. If the next item isn't available within the specified timeout, a sentinel value is returned instead of waiting indefinitely or raising an exception. The timeout can also be adjusted dynamically. While `IteratorPipe` is a newer feature (v0.2.0), the most explicit quickstart examples in the official README focus on `TimeoutIterator`."},"warnings":[{"fix":"Always pin to exact versions (e.g., `pip install iterators==0.2.0`) or review release notes carefully before upgrading minor versions.","message":"As a pre-1.0.0 library (currently v0.2.0), this package does not strictly adhere to Semantic Versioning where minor versions guarantee backward compatibility. Breaking changes might occur between minor releases (e.g., 0.1.x to 0.2.x).","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Refer to the library's test suite on GitHub for `IteratorPipe` examples, and exercise caution as its API might be subject to change in future minor releases.","message":"The `IteratorPipe` class, introduced in v0.2.0, is mentioned in release notes but lacks detailed examples or a dedicated section in the main GitHub README. Users might need to consult the source code or tests for advanced usage patterns, indicating a less stable API or incomplete documentation at this stage.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}