timeout-iterator 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

timeout_iterator/__init__.py

@@ -1,7 +1,7 @@
-from timeout_iterator.without_terminate import without_terminate
 from timeout_iterator.terminate import terminate
+from timeout_iterator.without_terminate import without_terminate
 
 # https://packaging-guide.openastronomy.org/en/latest/advanced/versioning.html
 from ._version import __version__
 
-__all__ = ["terminate", "without_terminate", "__version__"]
+__all__ = ["__version__", "terminate", "without_terminate"]

timeout_iterator/_seconds.py

@@ -0,0 +1,9 @@
+import math
+
+
+def validate_timeout_seconds(seconds: float) -> None:
+    if seconds > 0 and math.isfinite(seconds):
+        return
+
+    message = "seconds must be a positive finite number"
+    raise ValueError(message)

timeout_iterator/_version.py

@@ -1,16 +1,24 @@
-# file generated by setuptools_scm
+# file generated by vcs-versioning
 # don't change, don't track in version control
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple, Union
-    VERSION_TUPLE = Tuple[Union[int, str], ...]
-else:
-    VERSION_TUPLE = object
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 version: str
 __version__: str
-__version_tuple__: VERSION_TUPLE
-version_tuple: VERSION_TUPLE
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__commit_id__ = commit_id = 'g2389741fe'

timeout_iterator/terminate.py

@@ -1,33 +1,93 @@
-from typing import TypeVar, Iterable
-import datetime
 import signal
+import threading
+import time
+from collections.abc import Iterable, Iterator
+from typing import TypeVar
 
+from timeout_iterator._seconds import validate_timeout_seconds
 
 T = TypeVar("T")
 
 
+def _ensure_itimer_real_is_available() -> None:
+    current_timer = signal.getitimer(signal.ITIMER_REAL)
+    if current_timer == (0.0, 0.0):
+        return
+
+    message = "terminate() cannot run while ITIMER_REAL is already active"
+    raise RuntimeError(message)
+
+
+def _require_main_thread() -> None:
+    if threading.current_thread() is not threading.main_thread():
+        raise ValueError(
+            "terminate() must be called from the main thread; "
+            "signal.signal() and signal.setitimer() are main-thread-only "
+            "APIs. Use without_terminate() for thread-safe timeout iteration.",
+        )
+
+
 # NOTE: float type accepts int
 # https://peps.python.org/pep-0484/#the-numeric-tower
-def terminate(iterable: Iterable[T], seconds: float) -> Iterable[T]:
-    """Timeout iterator
+def terminate(iterable: Iterable[T], seconds: float) -> Iterator[T]:
+    """Timeout iterator that raises TimeoutError when the timeout expires.
+
+    Unlike `without_terminate`, this function forcibly raises TimeoutError
+    after the specified number of seconds, even mid-iteration. It uses
+    ``signal.SIGALRM`` / ``signal.setitimer()`` and is Unix-only.
+    It cannot be used while another ITIMER_REAL timer is active.
+    The timeout must be a positive finite number of seconds.
 
-    This iterator forcibly terminates a running task after the specified number of seconds.
+    Caution: ``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.
+    This means code running concurrently inside the iterator — or
+    libraries that also use ``signal.alarm()`` / ``signal.setitimer()``
+    — will have their signals suppressed until the iterator exits.
+
+    Must be called from the main thread of the main interpreter.
+    Calling from a worker thread raises ValueError.
+
+    **Main-thread only**: ``signal.signal()`` and ``signal.setitimer()``
+    are Python main-thread APIs.  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 fires at any Python bytecode boundary in the
+    calling thread, not only during fetches from the upstream iterable.
+    The ``for`` loop body can also be interrupted and raise ``TimeoutError``.
+    Keep loop body code interrupt-safe, or use ``without_terminate`` if the
+    upstream must be fully consumed before yielding to the caller.
+
+    The timeout is measured using ``time.monotonic()``, so it counts
+    monotonic elapsed time and is unaffected by DST transitions or
+    wall-clock adjustments.
     """
-    now = datetime.datetime.now()
-    end = now + datetime.timedelta(seconds=seconds)
+    _require_main_thread()
+    _ensure_itimer_real_is_available()
+    validate_timeout_seconds(seconds)
+    start = time.monotonic()
+    end = start + seconds
+    fired = False
 
-    def handler(signum: int, frame: object) -> None:
-        if signum != signal.SIGALRM:
-            return
-        if datetime.datetime.now() < end:
+    def handler(signum: int, _frame: object) -> None:
+        nonlocal fired
+        if fired or signum != signal.SIGALRM or time.monotonic() < end:
             return
-        raise TimeoutError
-
-    signal.signal(signal.SIGALRM, handler)
-    signal.setitimer(signal.ITIMER_REAL, seconds)
+        fired = True
+        elapsed = time.monotonic() - start
+        raise TimeoutError(
+            f"timed out after {elapsed:.3f}s (limit: {seconds}s)",
+        )
 
+    original_handler = signal.signal(signal.SIGALRM, handler)
     try:
-        for item in iterable:
-            yield item
+        signal.setitimer(signal.ITIMER_REAL, seconds)
+        try:
+            yield from iterable
+        finally:
+            signal.setitimer(signal.ITIMER_REAL, 0)
     finally:
-        signal.setitimer(signal.ITIMER_REAL, 0)
+        signal.signal(signal.SIGALRM, original_handler)

timeout_iterator/without_terminate.py

@@ -1,22 +1,53 @@
-from typing import TypeVar, Iterable
-import datetime
+import time
+from collections.abc import Iterable, Iterator
+from typing import Protocol, TypeGuard, TypeVar
 
+from timeout_iterator._seconds import validate_timeout_seconds
 
 T = TypeVar("T")
 
 
+class _Closeable(Protocol):
+    def close(self) -> None: ...
+
+
+def _is_closeable(value: object) -> TypeGuard[_Closeable]:
+    return callable(getattr(value, "close", None))
+
+
+def _close_if_possible(value: object) -> None:
+    if _is_closeable(value):
+        value.close()
+
+
 # NOTE: float type accepts int
 # https://peps.python.org/pep-0484/#the-numeric-tower
-def without_terminate(iterable: Iterable[T], seconds: float) -> Iterable[T]:
-    """Timeout iterator
+def without_terminate(iterable: Iterable[T], seconds: float) -> Iterator[T]:
+    """Timeout iterator that stops yielding items once the deadline elapses.
+
+    Unlike `terminate`, this function does NOT raise TimeoutError when the
+    timeout expires and does not use signals, so it is safe to use in
+    environments that restrict SIGALRM. It simply stops yielding further
+    items after the deadline.
+
+    The timeout is checked *after* each item is fetched from the upstream
+    iterator, not before. This means that if the deadline expires while a
+    fetch is in progress (or just after one completes), the fetched item is
+    silently dropped — consumed from the upstream but not yielded to the
+    caller. At most one item may be lost this way at the boundary.
+
+    The trade-off is that it cannot forcibly interrupt a blocking upstream
+    fetch or a task that is running between yields.
 
-    This iterator times out after the specified number of seconds.
-    This iterator cannot forcibly terminate a running task.
-    It just ends without executing the next task.
+    The timeout is measured using ``time.monotonic()``, so it counts
+    monotonic elapsed time and is unaffected by DST transitions or
+    wall-clock adjustments.
     """
-    now = datetime.datetime.now()
-    end = now + datetime.timedelta(seconds=seconds)
-    for item in iterable:
-        if datetime.datetime.now() > end:
+    validate_timeout_seconds(seconds)
+    end = time.monotonic() + seconds
+    iterator = iter(iterable)
+    for item in iterator:
+        if time.monotonic() > end:
+            _close_if_possible(iterator)
             break
         yield item

{timeout_iterator-0.2.2.dist-info → timeout_iterator-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: timeout-iterator
-Version: 0.2.2
+Version: 0.3.0
 Summary: Iterator with timeout
 Author-email: Yui KITSU <kitsuyui+github@kitsuyui.com>
 License: Copyright 2024-2025 Kitsu Yui
@@ -17,16 +17,19 @@ License: Copyright 2024-2025 Kitsu Yui
 Project-URL: Homepage, https://github.com/kitsuyui/python-timeout-iterator
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: BSD License
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.9
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: license-file
 
 # python-timeout-iterator
 
@@ -34,7 +37,7 @@ License-File: LICENSE
 
 [![Python](https://img.shields.io/pypi/pyversions/timeout-iterator.svg)](https://badge.fury.io/py/timeout-iterator)
 [![PyPI version](https://img.shields.io/pypi/v/timeout-iterator.svg)](https://pypi.python.org/pypi/timeout-iterator/)
-[![codecov](https://codecov.io/gh/kitsuyui/python-timeout-iterator/graph/badge.svg?token=D608CG7CUH)](https://codecov.io/gh/kitsuyui/python-timeout-iterator)
+![Coverage](https://raw.githubusercontent.com/kitsuyui/octocov-central/main/badges/kitsuyui/python-timeout-iterator/coverage.svg)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
 ## Installation
@@ -47,10 +50,13 @@ $ pip install timeout-iterator
 
 ### without_terminate
 
-`without_terminate` is a generator that it will not yield after the timeout,
-but it will not raise an exception.
+`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.
 
 ```python
+import time
+
 from timeout_iterator import without_terminate
 results = []
 for i in without_terminate(range(10), seconds=0.3):
@@ -60,11 +66,28 @@ for i in without_terminate(range(10), seconds=0.3):
 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.
 
 ```python
+import time
+
 from timeout_iterator import terminate
 try:
     results = []
@@ -77,6 +100,44 @@ except TimeoutError:
 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](https://lefthook.dev/) to run the same checks as CI
+locally, so problems surface before they reach CI.
+
+```sh
+# 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:
+
+```sh
+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

timeout_iterator-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+timeout_iterator/__init__.py,sha256=FFOkrfbOPzqGZ9Tdky1Jh1AEGHzl93alRlKiOsrGAy8,289
+timeout_iterator/_seconds.py,sha256=H8gVu4qvSvS4g6MuspdZ4Dpxn5cXI48kHU0uk8FvEpM,218
+timeout_iterator/_version.py,sha256=rc1GsnWwMvRGh39VX1_37B4EoeA79pQ2v_jvz1p3zIw,528
+timeout_iterator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+timeout_iterator/terminate.py,sha256=V4LJ1bhFsb_KXNFrEP6fygnp3r7pRcNe-k0-IPcN73U,3647
+timeout_iterator/without_terminate.py,sha256=RvHfToUweVvEHkvTUpalDTRbQfyZSX3E-0n8IA35XRQ,1866
+timeout_iterator-0.3.0.dist-info/licenses/LICENSE,sha256=i_4Vm9uYuomNQI4x5y04-L0mrzPFBnioSHjfSsQHWa0,1458
+timeout_iterator-0.3.0.dist-info/METADATA,sha256=lUPtFBy5M9j5DYCWa-mM_EBapc_PLMPLfJrCu6Qdt5U,5996
+timeout_iterator-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+timeout_iterator-0.3.0.dist-info/top_level.txt,sha256=nvIqkq7driA1qK_Go6asLhagba5hwEx_mgvJNx7OUsg,17
+timeout_iterator-0.3.0.dist-info/RECORD,,

{timeout_iterator-0.2.2.dist-info → timeout_iterator-0.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

timeout_iterator-0.2.2.dist-info/RECORD

@@ -1,9 +0,0 @@
-timeout_iterator/__init__.py,sha256=ul6_kSumsg72svZShaWJQeafVkyo4JFnKKXGxOyfbA8,289
-timeout_iterator/_version.py,sha256=RrHB9KG1O3GPm--rbTedqmZbdDrbgeRLXBmT4OBUqqI,411
-timeout_iterator/terminate.py,sha256=fwsKwenq1aJxGj-bux8b_jee91lBRc-AlBNOI1WTZnU,869
-timeout_iterator/without_terminate.py,sha256=-HQ7WfHdNcUdwpSYHVET95zQaQzq5ejgGKPWsoPGDr0,637
-timeout_iterator-0.2.2.dist-info/LICENSE,sha256=i_4Vm9uYuomNQI4x5y04-L0mrzPFBnioSHjfSsQHWa0,1458
-timeout_iterator-0.2.2.dist-info/METADATA,sha256=uDwEqmMvZAsSPTkWIBjGIf3NIjhti7Z9G-fHa3cYWh8,3663
-timeout_iterator-0.2.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-timeout_iterator-0.2.2.dist-info/top_level.txt,sha256=nvIqkq7driA1qK_Go6asLhagba5hwEx_mgvJNx7OUsg,17
-timeout_iterator-0.2.2.dist-info/RECORD,,