calltimeout 0.2.0__py3-none-any.whl

calltimeout/__init__.py

@@ -0,0 +1,11 @@
+"""Run a callable with a wall-clock timeout and get a typed result or a clean error."""
+
+from __future__ import annotations
+
+from ._api import Mode, run
+from ._decorator import with_timeout
+from ._errors import CallCrashed, CallTimeout
+
+__version__ = "0.2.0"
+
+__all__ = ["CallCrashed", "CallTimeout", "Mode", "run", "with_timeout"]

calltimeout/_api.py

@@ -0,0 +1,91 @@
+"""Public entry point: run a callable under a wall-clock timeout."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from enum import Enum
+from typing import Final, Literal, TypeVar, overload
+
+from ._errors import CallTimeout, Expired
+from ._process import run_in_process
+from ._signal import check_signal_mode, run_with_signal
+from ._thread import run_in_thread
+from ._validate import check_call, check_mode, check_timeout
+
+T = TypeVar("T")
+D = TypeVar("D")
+
+Mode = Literal["thread", "process", "signal"]
+
+RUNNERS: Final = {
+    "thread": run_in_thread,
+    "process": run_in_process,
+    "signal": run_with_signal,
+}
+
+
+class _Unset(Enum):
+    token = 0
+
+
+UNSET: Final = _Unset.token
+
+
+@overload
+def run(
+    fn: Callable[..., T],
+    timeout: float,
+    *,
+    args: tuple[object, ...] = ...,
+    kwargs: Mapping[str, object] | None = ...,
+    mode: Mode = ...,
+) -> T: ...
+
+
+@overload
+def run(
+    fn: Callable[..., T],
+    timeout: float,
+    *,
+    args: tuple[object, ...] = ...,
+    kwargs: Mapping[str, object] | None = ...,
+    mode: Mode = ...,
+    default: D,
+) -> T | D: ...
+
+
+def run(
+    fn: Callable[..., T],
+    timeout: float,
+    *,
+    args: tuple[object, ...] = (),
+    kwargs: Mapping[str, object] | None = None,
+    mode: Mode = "thread",
+    default: D | _Unset = UNSET,
+) -> T | D:
+    """Run fn and return its result, or handle the timeout.
+
+    mode "thread" (the default) runs fn in a daemon thread and stops waiting on overrun;
+    the call itself cannot be killed and keeps running if it ignores the clock.
+    mode "process" runs fn in a child process that is terminated on overrun; fn, its
+    arguments and its result must be picklable, and a child that dies without a result
+    raises CallCrashed. mode "signal" (POSIX, main thread) raises CallTimeout inside fn.
+
+    A zero timeout raises at once without starting fn. If default is given it is
+    returned when this call's own budget runs out; otherwise CallTimeout is raised. A
+    CallTimeout from a nested call inside fn always propagates.
+    """
+    seconds = check_timeout(timeout)
+    check_call(fn, args, kwargs)
+    check_mode(mode, RUNNERS)
+    runner = RUNNERS[mode]
+    if mode == "signal":
+        check_signal_mode()  # before the zero-budget shortcut, so misuse always surfaces
+    try:
+        if seconds == 0:
+            raise Expired
+        return runner(fn, seconds, args, dict(kwargs or {}))
+    except Expired as expired:
+        if not isinstance(default, _Unset):
+            return default
+        raise CallTimeout(seconds) from expired.__cause__

calltimeout/_decorator.py

@@ -0,0 +1,77 @@
+"""Decorator form of run that keeps the wrapped function's signature."""
+
+from __future__ import annotations
+
+import functools
+import sys
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar, overload
+
+from ._api import RUNNERS, UNSET, Mode, _Unset, run
+from ._process import claim_child_target
+from ._validate import check_call, check_mode, check_timeout
+
+P = ParamSpec("P")
+T = TypeVar("T")
+D = TypeVar("D")
+R = TypeVar("R")
+
+
+def _by_name(obj: object) -> object:
+    """Whatever pickle would find under obj's module and qualified name, or None."""
+    target: object = sys.modules.get(getattr(obj, "__module__", None) or "")
+    for part in str(getattr(obj, "__qualname__", "<>")).split("."):
+        target = getattr(target, part, None)
+    return target
+
+
+def _process_target(wrapper: Callable[..., R], fn: Callable[..., R]) -> Callable[..., R]:
+    # The wrapper is sent when its name leads to it (the child then unwraps it); when
+    # the name still leads to the original (fast = with_timeout(...)(slow)), the
+    # original is sent. Under fork nothing is pickled and either works.
+    if _by_name(wrapper) is not wrapper and _by_name(fn) is fn:
+        return fn
+    return wrapper
+
+
+@overload
+def with_timeout(
+    timeout: float, *, mode: Mode = ...
+) -> Callable[[Callable[P, T]], Callable[P, T]]: ...
+
+
+@overload
+def with_timeout(
+    timeout: float, *, mode: Mode = ..., default: D
+) -> Callable[[Callable[P, T]], Callable[P, T | D]]: ...
+
+
+def with_timeout(
+    timeout: float, *, mode: Mode = "thread", default: D | _Unset = UNSET
+) -> Callable[[Callable[P, T]], Callable[P, T | D]]:
+    """Decorate a function so every call runs under run(fn, timeout, mode=...).
+
+    The decorated function keeps its parameters for type checkers. With default, a
+    timed-out call returns it instead of raising. In process mode, under the spawn and
+    forkserver start methods, the child imports the function by name, so the decorated
+    function or the original must be reachable under its own module and name.
+    """
+    check_timeout(timeout)
+    check_mode(mode, RUNNERS)
+
+    def decorate(fn: Callable[P, T]) -> Callable[P, T | D]:
+        check_call(fn, (), None)
+
+        @functools.wraps(fn)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T | D:
+            if mode == "process" and claim_child_target(wrapper):
+                # Already inside the child started for this call: run the body.
+                return fn(*args, **kwargs)
+            target = _process_target(wrapper, fn) if mode == "process" else fn
+            if isinstance(default, _Unset):
+                return run(target, timeout, args=args, kwargs=kwargs, mode=mode)
+            return run(target, timeout, args=args, kwargs=kwargs, mode=mode, default=default)
+
+        return wrapper
+
+    return decorate

calltimeout/_errors.py

@@ -0,0 +1,30 @@
+"""Exceptions raised when a call overruns its budget or its process dies."""
+
+from __future__ import annotations
+
+
+class CallTimeout(TimeoutError):
+    """Raised when a call does not finish within its allotted time."""
+
+    def __init__(self, timeout: float) -> None:
+        self.timeout = timeout
+        super().__init__(f"call did not finish within {timeout} seconds")
+
+    def __reduce__(self) -> tuple[type[CallTimeout], tuple[float]]:
+        # The default reduce would rebuild from the message and lose the number.
+        return (type(self), (self.timeout,))
+
+
+class CallCrashed(RuntimeError):
+    """Raised in process mode when the child exits without sending a result."""
+
+    def __init__(self, exitcode: int | None) -> None:
+        self.exitcode = exitcode
+        super().__init__(f"the call's process exited with code {exitcode} before returning")
+
+    def __reduce__(self) -> tuple[type[CallCrashed], tuple[int | None]]:
+        return (type(self), (self.exitcode,))
+
+
+class Expired(Exception):
+    """Private signal from a runner to the entry point: this call's own budget ran out."""

calltimeout/_process.py

@@ -0,0 +1,141 @@
+"""Run a callable in a separate process that can be truly terminated."""
+
+from __future__ import annotations
+
+import multiprocessing
+import pickle
+import time
+from collections.abc import Callable, Mapping, Sequence
+from multiprocessing.connection import Connection, wait
+from multiprocessing.process import BaseProcess
+from typing import Any, Protocol, TypeVar, cast
+
+from ._errors import CallCrashed, Expired
+from ._thread import thread_name
+from ._validate import reject_coroutine
+from ._wire import pack_error, pack_result, prepickle, unpack
+
+T = TypeVar("T")
+
+# Seconds a terminated child gets to exit before it is killed (SIGTERM can be ignored).
+GRACE = 1.0
+
+# Longest sleep between checks that the child is still alive.
+POLL = 0.25
+
+# The target this child process was started for, so a decorated function knows it is
+# already inside its own child and must not start another one.
+_targets: list[object] = []
+
+
+def claim_child_target(fn: object) -> bool:
+    """Return True once if fn is the call this child process was started to run."""
+    if _targets and _targets[-1] is fn:
+        _targets.pop()
+        return True
+    return False
+
+
+class _Reader(Protocol):
+    def poll(self) -> bool: ...
+    def recv_bytes(self) -> bytes: ...
+
+
+def _child(call: object, conn: Connection) -> None:
+    if isinstance(call, bytes):
+        call = pickle.loads(call)
+    fn, args, kwargs = cast(tuple[Callable[..., object], tuple[object, ...], dict[str, Any]], call)
+    _targets.append(fn)
+    try:
+        try:
+            data = pack_result(reject_coroutine(fn(*args, **kwargs)))
+        except BaseException as exc:
+            data = pack_error(exc)
+        conn.send_bytes(data)
+    finally:
+        conn.close()
+
+
+def _await(reader: Any, process: BaseProcess, timeout: float) -> list[object]:
+    """Wait for a result or the child's exit, whichever comes first; [] on overrun."""
+    deadline = time.monotonic() + timeout
+    while True:
+        left = deadline - time.monotonic()
+        if left <= 0:
+            return []
+        ready = wait([reader, process.sentinel], min(left, POLL))
+        if ready:
+            return list(ready)
+        if not process.is_alive():
+            # A grandchild forked by the call inherits the pipe and, under fork and
+            # spawn, the sentinel too, hiding the exit from both; waitpid still sees it.
+            return [process.sentinel]
+
+
+def _exits_within(process: BaseProcess, seconds: float) -> bool:
+    # Not join(seconds): it waits on the sentinel, which a grandchild may hold open.
+    deadline = time.monotonic() + seconds
+    while process.is_alive() and time.monotonic() < deadline:
+        time.sleep(0.01)
+    return not process.is_alive()
+
+
+def _stop(process: BaseProcess, *, finished: bool) -> None:
+    """End the child: a finished one first gets to exit on its own (atexit, flushes)."""
+    try:
+        if not (finished and _exits_within(process, GRACE)) and process.is_alive():
+            process.terminate()
+            _exits_within(process, GRACE)
+    finally:
+        # Also reached on KeyboardInterrupt during the grace period.
+        if process.is_alive():
+            process.kill()
+        process.join()
+
+
+def _receive(reader: _Reader, ready: Sequence[object]) -> bytes | None:
+    # The child may have sent and exited in the same instant: check the pipe either way.
+    if reader in ready or reader.poll():
+        try:
+            return reader.recv_bytes()
+        except EOFError:
+            return None
+    return None
+
+
+def run_in_process(
+    fn: Callable[..., T],
+    timeout: float,
+    args: tuple[object, ...],
+    kwargs: Mapping[str, object],
+) -> T:
+    """Run fn in a child process, terminating it if it overruns the budget.
+
+    Unlike thread mode this truly stops the work on timeout, but fn, its arguments
+    and its result must be picklable so they can cross the process boundary. A child
+    that exits without a result raises CallCrashed as soon as it is gone.
+    """
+    ctx = multiprocessing.get_context()
+    call = prepickle(ctx.get_start_method(), (fn, args, dict(kwargs)))
+    reader, writer = ctx.Pipe(duplex=False)
+    process = ctx.Process(target=_child, args=(call, writer), name=thread_name(fn))
+    started = finished = False
+    try:
+        process.start()
+        started = True
+        writer.close()
+        ready = _await(reader, process, timeout)
+        if not ready:
+            raise Expired
+        data = _receive(reader, ready)
+        if data is None:
+            process.join()
+            raise CallCrashed(process.exitcode)
+        finished = True
+    finally:
+        # Runs on every exit, including KeyboardInterrupt while waiting.
+        writer.close()
+        reader.close()
+        if started:
+            _stop(process, finished=finished)
+    return cast(T, unpack(data))

calltimeout/_signal.py

@@ -0,0 +1,131 @@
+"""Interrupt a call in place with SIGALRM (POSIX, main thread only)."""
+
+from __future__ import annotations
+
+import signal
+import sys
+import threading
+import time
+from collections.abc import Callable, Mapping
+from types import FrameType
+from typing import Any, TypeVar
+
+from ._errors import CallTimeout, Expired
+from ._validate import reject_coroutine
+
+T = TypeVar("T")
+
+# Smallest delay used to re-arm a timer that is already due: zero would disarm it.
+_SOON = 1e-6
+
+_NO_SIGALRM = "mode 'signal' needs SIGALRM, which Windows lacks; use 'thread' or 'process'"
+
+
+def check_signal_mode() -> None:
+    """Raise if this platform or thread cannot use SIGALRM."""
+    if sys.platform == "win32":
+        raise NotImplementedError(_NO_SIGALRM)
+    if threading.current_thread() is not threading.main_thread():
+        raise RuntimeError("mode 'signal' only works in the main thread")
+
+
+def _caused_by(exc: BaseException, raised: CallTimeout) -> bool:
+    """True if exc is our timeout or an Exception raised while handling it."""
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        if current is raised:
+            return True
+        if not isinstance(current, Exception):
+            return False  # KeyboardInterrupt, SystemExit and friends always propagate
+        seen.add(id(current))
+        current = current.__cause__ or current.__context__
+    return False
+
+
+def _pass_on(previous: Any, signum: int, frame: FrameType | None) -> None:
+    """Give an enclosing timer's tick to the handler that was there before."""
+    if callable(previous):
+        previous(signum, frame)
+    elif previous == signal.SIG_DFL:
+        # The default action ends the process, which is what that timer was set up for.
+        signal.signal(signum, signal.SIG_DFL)
+        signal.raise_signal(signum)
+
+
+def run_with_signal(
+    fn: Callable[..., T],
+    timeout: float,
+    args: tuple[object, ...],
+    kwargs: Mapping[str, object],
+) -> T:
+    """Run fn in this thread and raise CallTimeout inside it when the budget runs out.
+
+    Pure Python code and blocking system calls are interrupted where they are (PEP 475:
+    a handler that raises stops the retry). Code running in C without returning to the
+    interpreter is only interrupted once it does. A timer that was already armed keeps
+    its schedule and its handler still runs when it is due.
+    """
+    check_signal_mode()
+    if sys.platform == "win32":  # repeated so type checkers on Windows skip the rest
+        raise NotImplementedError(_NO_SIGALRM)
+    start = time.monotonic()
+    deadline = start + timeout
+    outer_delay, outer_interval = signal.getitimer(signal.ITIMER_REAL)
+    outer_due = start + outer_delay if outer_delay > 0 else None
+    fired = False
+    raised = CallTimeout(timeout)
+
+    def arm(now: float) -> None:
+        due = deadline if outer_due is None else min(deadline, outer_due)
+        signal.setitimer(signal.ITIMER_REAL, max(due - now, _SOON))
+
+    def expire(signum: int, frame: FrameType | None) -> None:
+        nonlocal fired, outer_due, outer_interval
+        now = time.monotonic()
+        if now >= deadline:
+            fired = True
+            raise raised
+        if outer_due is not None and now >= outer_due:
+            signal.setitimer(signal.ITIMER_REAL, 0)
+            # This tick is consumed even if the handler raises: never deliver it twice.
+            outer_due = now + outer_interval if outer_interval > 0 else None
+            try:
+                _pass_on(previous, signum, frame)
+            finally:
+                # The enclosing handler may have re-armed the timer: its new schedule.
+                delay, interval = signal.getitimer(signal.ITIMER_REAL)
+                now = time.monotonic()
+                if delay > 0:
+                    outer_due, outer_interval = now + delay, interval
+                arm(now)
+            return
+        arm(now)  # woke a little early: wait for whichever is due next
+
+    if signal.getsignal(signal.SIGALRM) is None:
+        raise RuntimeError("SIGALRM has a handler set outside Python that could not be restored")
+    previous = signal.signal(signal.SIGALRM, expire)
+    try:
+        arm(start)
+        try:
+            value = fn(*args, **kwargs)
+        except BaseException as exc:
+            if fired and _caused_by(exc, raised):
+                raise Expired from exc
+            raise
+        finally:
+            signal.setitimer(signal.ITIMER_REAL, 0)
+    except CallTimeout as exc:
+        # The alarm can land after the call returned but before the timer was disarmed.
+        if exc is raised:
+            raise Expired from exc
+        raise
+    finally:
+        signal.signal(signal.SIGALRM, signal.SIG_DFL if previous is None else previous)
+        if outer_due is not None:
+            left = outer_due - time.monotonic()
+            signal.setitimer(signal.ITIMER_REAL, max(left, _SOON), outer_interval)
+    if fired:
+        # The call caught the timeout and returned later; the budget was still exceeded.
+        raise Expired
+    return reject_coroutine(value)

calltimeout/_thread.py

@@ -0,0 +1,52 @@
+"""Run a callable in a daemon thread and wait for it with a timeout."""
+
+from __future__ import annotations
+
+import contextvars
+import threading
+from collections.abc import Callable, Mapping
+from typing import TypeVar
+
+from ._errors import Expired
+from ._validate import reject_coroutine
+
+T = TypeVar("T")
+
+
+def thread_name(fn: object) -> str:
+    """Name a worker thread after its call so a lingering one is recognisable."""
+    name = getattr(fn, "__qualname__", None) or type(fn).__qualname__
+    return f"calltimeout:{name}"
+
+
+def run_in_thread(
+    fn: Callable[..., T],
+    timeout: float,
+    args: tuple[object, ...],
+    kwargs: Mapping[str, object],
+) -> T:
+    """Run fn in a daemon thread and return its result within the budget.
+
+    A timed-out call is not killed: Python cannot interrupt a running thread. The
+    caller stops waiting and raises, but a non-cooperative call keeps running in
+    the background until it returns on its own or the process exits.
+    """
+    result: list[T] = []
+    error: list[BaseException] = []
+    # Same as asyncio.to_thread: the call sees the caller's context variables.
+    context = contextvars.copy_context()
+
+    def target() -> None:
+        try:
+            result.append(context.run(fn, *args, **kwargs))
+        except BaseException as exc:
+            error.append(exc)
+
+    thread = threading.Thread(target=target, name=thread_name(fn), daemon=True)
+    thread.start()
+    thread.join(timeout)
+    if thread.is_alive():
+        raise Expired
+    if error:
+        raise error[0]
+    return reject_coroutine(result[0])

calltimeout/_validate.py

@@ -0,0 +1,60 @@
+"""Argument checks shared by every mode."""
+
+from __future__ import annotations
+
+import inspect
+import math
+import threading
+from collections.abc import Iterable, Mapping
+from numbers import Real
+from typing import TypeVar
+
+T = TypeVar("T")
+
+_ASYNC_HINT = "use asyncio.timeout() for coroutines; calltimeout runs blocking callables"
+
+
+def check_timeout(timeout: object) -> float:
+    """Return the budget as a float, or raise if it is not a usable number of seconds."""
+    if isinstance(timeout, bool) or not isinstance(timeout, Real):
+        raise TypeError(f"timeout must be a number of seconds, not {type(timeout).__name__}")
+    try:
+        seconds = float(timeout) + 0.0  # + 0.0 turns -0.0 into 0.0
+    except OverflowError:
+        raise ValueError(f"timeout must be at most {threading.TIMEOUT_MAX} seconds") from None
+    if math.isnan(seconds):
+        raise ValueError("timeout must be a number, not NaN")
+    if seconds < 0:
+        raise ValueError("timeout must not be negative")
+    if seconds > threading.TIMEOUT_MAX:
+        # Covers infinity too: every wait primitive rejects values above this limit.
+        raise ValueError(f"timeout must be at most {threading.TIMEOUT_MAX} seconds")
+    return seconds
+
+
+def check_call(fn: object, args: object, kwargs: object) -> None:
+    """Reject arguments the call could never run with, before anything is started."""
+    if not callable(fn):
+        raise TypeError(f"fn must be callable, not {type(fn).__name__}")
+    if inspect.iscoroutinefunction(fn):
+        raise TypeError(f"{fn!r} is a coroutine function: {_ASYNC_HINT}")
+    if not isinstance(args, tuple):
+        raise TypeError(f"args must be a tuple, not {type(args).__name__}")
+    if kwargs is not None and not isinstance(kwargs, Mapping):
+        raise TypeError(f"kwargs must be a mapping, not {type(kwargs).__name__}")
+    if kwargs is not None and not all(isinstance(key, str) for key in kwargs):
+        raise TypeError("kwargs keys must be strings")
+
+
+def check_mode(mode: object, modes: Iterable[str]) -> None:
+    """Reject anything but one of the mode names, including unhashable values."""
+    if not isinstance(mode, str) or mode not in modes:
+        raise ValueError(f"unknown mode: {mode!r}")
+
+
+def reject_coroutine(value: T) -> T:
+    """Refuse a coroutine result: it would never run and warn later as unawaited."""
+    if inspect.iscoroutine(value):
+        value.close()
+        raise TypeError(f"the call returned a coroutine: {_ASYNC_HINT}")
+    return value

calltimeout/_wire.py

@@ -0,0 +1,76 @@
+"""What crosses the process boundary: the call going in, the outcome coming back."""
+
+from __future__ import annotations
+
+import pickle
+import traceback
+from multiprocessing.reduction import ForkingPickler
+from typing import cast
+
+
+class RemoteTraceback(Exception):
+    """Carries the child's formatted traceback as the cause of a re-raised error."""
+
+    def __init__(self, text: str) -> None:
+        super().__init__(text)
+        self.text = text
+
+    def __str__(self) -> str:
+        return self.text
+
+
+def prepickle(method: str, call: tuple[object, ...]) -> object:
+    """Pickle the call before any process exists, so a start cannot fail half way.
+
+    A start that failed while pickling (seen on Windows) left a half-built Popen whose
+    finalizer later closed handle numbers reused by the next call's pipe.
+    """
+    if method == "fork":
+        return call  # nothing is pickled
+    try:
+        return bytes(ForkingPickler.dumps(call))
+    except RuntimeError:
+        # Locks, queues and the like only pickle inside Process.start(): pass them as is.
+        return call
+
+
+def pack_error(exc: BaseException) -> bytes:
+    """Pickle an exception with its traceback text, or a stand-in if it cannot travel."""
+    text = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+    try:
+        data = pickle.dumps((False, exc, text))
+        pickle.loads(data)  # an exception can pickle and still fail to rebuild
+    except Exception as problem:
+        name = f"{type(exc).__module__}.{type(exc).__qualname__}"
+        try:
+            message = str(exc)
+        except Exception:
+            message = "<str() failed>"
+        stand_in = RuntimeError(f"{name}: {message} (not picklable: {problem!r})")
+        data = pickle.dumps((False, stand_in, text))
+    return data
+
+
+def pack_result(value: object) -> bytes:
+    """Pickle a result, or a PicklingError explaining why it cannot be sent back."""
+    try:
+        return pickle.dumps((True, value, ""))
+    except Exception as problem:
+        return pack_error(
+            pickle.PicklingError(f"the call's result cannot be sent back: {problem!r}")
+        )
+
+
+def unpack(data: bytes) -> object:
+    """Return the child's result or raise its exception with the child's traceback."""
+    try:
+        ok, payload, text = pickle.loads(data)
+    except Exception as problem:
+        raise pickle.UnpicklingError(
+            f"the call's result cannot be rebuilt in this process: {problem!r}"
+        ) from problem
+    if ok:
+        return cast(object, payload)
+    error = cast(BaseException, payload)
+    error.__cause__ = RemoteTraceback(text)
+    raise error

calltimeout-0.2.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: calltimeout
+Version: 0.2.0
+Summary: Run a callable with a wall-clock timeout in a thread, a process or under SIGALRM, typed, with an honest choice of mechanism
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/calltimeout
+Project-URL: Issues, https://github.com/JaviLianes8/calltimeout/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/calltimeout/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deadline,decorator,multiprocessing,paramspec,sigalrm,signal,thread,timeout
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# calltimeout
+
+Run a callable with a wall-clock timeout and get a typed result or a clean
+`TimeoutError`, with an honest choice of mechanism.
+
+## Install
+
+```
+pip install calltimeout
+```
+
+Python 3.10 or newer, no dependencies.
+
+## Usage
+
+```python
+import time
+
+from calltimeout import CallTimeout, run
+
+
+def fetch(delay: float) -> str:
+    time.sleep(delay)
+    return "payload"
+
+
+# The result, when the call finishes in time.
+print(run(fetch, 2.0, args=(0.01,)))  # payload
+
+# CallTimeout, a subclass of TimeoutError, when it does not.
+try:
+    run(fetch, 0.05, args=(1.0,))
+except CallTimeout as exc:
+    print(f"gave up after {exc.timeout} seconds")  # gave up after 0.05 seconds
+
+# Or a fallback instead of raising.
+print(run(fetch, 0.05, args=(1.0,), default="cached"))  # cached
+```
+
+`run(fn, timeout, *, args=(), kwargs=None, mode="thread", default=...)` passes `args`
+and `kwargs` to `fn`. The timeout is a number of seconds: an `int` or `float`, not
+negative, not NaN and not infinite. A zero timeout raises at once without starting the
+call. Exceptions raised by the call reach the caller (in process mode as a pickled copy,
+see below). `default` is only used
+for this call's own timeout: a `CallTimeout` from a nested call inside `fn` propagates.
+`Mode` is the `Literal` type of the three mode names, for annotating your own wrappers.
+
+### As a decorator
+
+`with_timeout` keeps the decorated function's parameters, so type checkers still check
+every call, and the result type becomes `T | D` when a default is given. In process mode
+under spawn or forkserver the child imports the function by name, so either the
+decorated function or the original must be reachable under its module and name (a
+plain `@with_timeout` at module level, or `fast = with_timeout(...)(slow)`):
+
+```python
+import time
+
+from calltimeout import with_timeout
+
+
+@with_timeout(2.0)
+def add(left: int, right: int) -> int:
+    return left + right
+
+
+@with_timeout(0.05, default=None)
+def lookup(key: str) -> str:
+    time.sleep(1.0)
+    return key.upper()
+
+
+print(add(2, 3))  # 5
+print(lookup("id"))  # None
+```
+
+## Choosing a mechanism
+
+The trade-off is the whole point of the library, so it is stated plainly:
+
+| | `"thread"` (default) | `"process"` | `"signal"` |
+|---|---|---|---|
+| Stops a runaway call | No: it keeps running in a daemon thread | Yes: terminated, and killed if still alive 1 second later | Python code and blocking system calls: yes. A long call inside C: once it returns |
+| Where it works | Everywhere | Everywhere | POSIX, main thread only |
+| Pickling | Not needed | `fn`, its arguments and its result | Not needed |
+| Cost | A thread | A new process, whose start counts against the budget | A timer |
+| Context variables | A copy of the caller's, like `asyncio.to_thread` | Not shared | Shared: same thread |
+
+**Thread mode** runs the call in a daemon thread named `calltimeout:<function>` and
+stops waiting after the timeout. Python cannot stop a running thread, so a call that
+ignores the clock (a tight loop, a blocking call without its own timeout) keeps running
+after `run` has raised, until it returns or the process exits. Daemon threads are
+stopped abruptly at shutdown, so do not leave one holding a file or a transaction.
+
+**Process mode** runs the call in a child process and really stops it on overrun. A
+child that exits without a result (a crash, `os._exit`, the out-of-memory killer)
+raises `CallCrashed` with its exit code as soon as it is gone, instead of a timeout. An
+exception from the child arrives with the child's traceback chained as its cause, and a
+result that cannot be pickled raises `pickle.PicklingError` straight away (and one the
+parent cannot rebuild, `pickle.UnpicklingError`). An exception that cannot be pickled
+arrives as a `RuntimeError` naming it, and `sys.exit()` in the call raises `SystemExit`
+in the caller like any other exception. After the result arrives the child gets up to
+1 second to shut down on its own (atexit handlers, non-daemon threads) before it is
+terminated. Locks, queues and other `multiprocessing` objects can be passed as
+arguments. Processes started by the call itself are not stopped with it. Targets must be importable, so
+define them at module level, and guard the entry point of a script with
+`if __name__ == "__main__":` as `multiprocessing` requires.
+
+```python
+import math
+import os
+import time
+
+from calltimeout import CallCrashed, run
+
+print(run(math.factorial, 30.0, args=(20,), mode="process"))  # 2432902008176640000
+
+# The child is terminated, not left running.
+print(run(time.sleep, 0.5, args=(60,), mode="process", default="stopped"))  # stopped
+
+try:
+    run(os._exit, 30.0, args=(3,), mode="process")
+except CallCrashed as exc:
+    print(f"exit code {exc.exitcode}")  # exit code 3
+```
+
+**Signal mode** arms a `SIGALRM` timer and raises `CallTimeout` inside the call, at the
+line it has reached. Since PEP 475 a signal handler that raises also stops blocking
+system calls such as `time.sleep` or a socket read. It needs no thread and no pickling,
+but it only works in the main thread on POSIX: elsewhere it raises `RuntimeError`, and
+on Windows `NotImplementedError`. A call that catches the timeout and carries on still
+ends in `CallTimeout`, but only once it returns: the timer fires once, so a loop that
+keeps catching `OSError` (which `TimeoutError` is) runs on until it gives up. An
+exception raised while handling the timeout counts as the timeout; `KeyboardInterrupt`,
+`SystemExit` and unrelated errors propagate. Timers already armed with `setitimer` or
+`alarm` keep their schedule, so signal-mode calls can be nested, but a call that resets
+`ITIMER_REAL` itself cancels the deadline.
+
+```python
+import sys
+import time
+
+from calltimeout import CallTimeout, run
+
+if sys.platform != "win32":
+    try:
+        run(time.sleep, 0.1, args=(60,), mode="signal")
+    except CallTimeout as exc:
+        # The timeout was raised inside time.sleep and is chained as the cause.
+        print(f"interrupted: {type(exc.__cause__).__name__}")  # interrupted: CallTimeout
+```
+
+## In async code
+
+Coroutines already have `asyncio.timeout()`, and `run` refuses coroutine functions
+with a pointer to it. For a blocking call, run `run` in a worker thread so the event
+loop stays free; process mode then really stops the call:
+
+```python
+import asyncio
+import time
+
+from calltimeout import run
+
+
+async def main() -> str:
+    return await asyncio.to_thread(
+        run, time.sleep, 0.5, args=(60,), mode="process", default="stopped"
+    )
+
+
+print(asyncio.run(main()))  # stopped
+```
+
+## Why
+
+Running a function under a timeout is a common need, but the usual packages have
+gone stale and ship no type information:
+
+- [`func-timeout`](https://pypi.org/project/func-timeout/): last release 2019.
+- [`stopit`](https://pypi.org/project/stopit/): last release 2018.
+- [`timeout-decorator`](https://pypi.org/project/timeout-decorator/): last
+  release 2020.
+
+Beyond age, most of them hide the mechanism and quietly imply they can always
+cancel the work, which a thread cannot. `calltimeout` is small, fully typed
+(`mypy --strict`, `py.typed`), depends on nothing, and makes the choice between
+thread, process and signal explicit rather than a hidden surprise.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

calltimeout-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+calltimeout/__init__.py,sha256=OREQxV36_n-z3t5tuI0QKZHIsUZngTX2fJSOnGnBI6s,332
+calltimeout/_api.py,sha256=gA7zHKoGrSyKPiW8SpcQLi1qpAJ9IUyohFFoWhv3ZGU,2595
+calltimeout/_decorator.py,sha256=id30guqNmUL1C3cZ4XhnWpB285YW8WrDZTj_9MGohuw,2824
+calltimeout/_errors.py,sha256=MHh1ez9u_pQVFx1t91HLoXA3WbE1_Ix2UioAM3HNb0A,1103
+calltimeout/_process.py,sha256=zRFx5tpkzBeotjv1-v17WJ5ndwCH-cmwziecWPIBMYo,4814
+calltimeout/_signal.py,sha256=4jQXS7vIjglzyS1kXn-CSYioc5OxLPnsXoWK51xUfi8,5115
+calltimeout/_thread.py,sha256=ZrYMPgEvJApSXbJ7fV9Vs5aX3e6D5w9D9S43PKjgBo0,1580
+calltimeout/_validate.py,sha256=t89BMSrnelSwMJApEXgeT8dBd_pYTPDy57-QoGo1Z_o,2503
+calltimeout/_wire.py,sha256=CHP0iioN01VAqa_UvES72pGKKS5NbSKjh7_yhbefK6Q,2647
+calltimeout/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+calltimeout-0.2.0.dist-info/METADATA,sha256=33xMz6jGTfnhEhkctXvPN74z9tPv9LYVrhwYajY2-CQ,9023
+calltimeout-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+calltimeout-0.2.0.dist-info/licenses/LICENSE,sha256=_WmABlQG__oqlx4Rzp-qDJ10xND5KCLScftbhXbLC_c,1070
+calltimeout-0.2.0.dist-info/RECORD,,

calltimeout-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

calltimeout-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.