calltimeout 0.2.0__tar.gz → 1.0.0__tar.gz

calltimeout-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Third-party documents, fetched locally by scripts/fetch_upstream.py; only the manifest is tracked.
+tests/upstream/*
+!tests/upstream/MANIFEST.json

calltimeout-1.0.0/CHANGELOG.md

@@ -0,0 +1,244 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-02
+
+The public API is now stable: `run`, `with_timeout`, `CallTimeout`, `CallCrashed`,
+`RemoteTraceback` and `Mode`, with their parameter names, defaults and exception types,
+follow Semantic Versioning from this release on. The changes below are against PyPI
+0.2.0, published on 2026-10-31 from commit 9b6975c on `main`. Neither 0.1.0 nor 0.2.0
+was tagged. Exceptions stored by 0.2.0 remain loadable after upgrading.
+
+### Added
+
+- `RemoteTraceback`, the cause chained to an exception raised by a process-mode call,
+  whose text (`.text`) is the child's traceback, is public and shown and pickled as
+  `calltimeout.RemoteTraceback`. It was a private class, shown in every such traceback
+  as `calltimeout._wire.RemoteTraceback`.
+
+### Changed
+
+- A `mode` that is not a `str` raises `TypeError` (it raised `ValueError`); an unknown
+  mode name still raises `ValueError`, and the message lists the three valid names. A
+  `str` subclass is read as the plain name.
+- `CallTimeout` and `CallCrashed` are shown and pickled as `calltimeout.CallTimeout` and
+  `calltimeout.CallCrashed`, so a pickle never names a private module, and they keep
+  extra attributes (such as notes) through pickle and copy. `run` and `with_timeout` are
+  shown and pickled as `calltimeout.run` and `calltimeout.with_timeout` too (a stored
+  `functools.partial(run, ...)` named `calltimeout._api`).
+- `CallCrashed.exitcode` is typed `int`: it was `int | None`, though `run` raises
+  `CallCrashed` only once the child has exited, with its code. A `RemoteTraceback` built
+  with a text that is not a `str` shows it bounded; its `str()` raised `TypeError`.
+- Generator functions and async generator functions raise `TypeError` in `run` and
+  `with_timeout` (an async one with the pointer to `asyncio`), and so does a call that
+  returns an async generator. They were accepted: the call returned the generator at
+  once, and its body then ran with no time limit as it was iterated.
+- Thread mode: a call that ends after the budget ran out is a timeout, even when the
+  caller notices only later. A call holding the GIL could end after its deadline and
+  before the caller ran again, and its value was returned (a 1 ms budget gave values
+  from calls that ran 3 to 10 ms).
+- A real-number timeout whose conversion to `float` fails raises `TypeError` (the
+  conversion's own error is not retained as a cause or context).
+- A negative timeout too large for a `float` (`-10**400`) raises "timeout must not be
+  negative"; it was reported as above `threading.TIMEOUT_MAX`.
+- Tiny negative real-number timeouts are rejected before float conversion can round
+  them to zero, including `Fraction(-1, 10**400)` in both public entry points.
+- Invalid mode messages list valid names without quoting the input. Timeout conversion
+  and keyword mapping failures use fixed, value-free diagnostics and retain no original
+  cause or context. Ordinary mapping-access failures now raise `TypeError`.
+- Validation checks actual types without consulting overridable `__class__` properties,
+  while accepting genuine subclasses and registered real-number and mapping types.
+- `kwargs` is read once into a plain `dict` before the budget starts. Keys are validated
+  and string subclasses normalized before insertion, so overridden hashes and equality
+  cannot cause quadratic insertion work. Mapping views cannot bypass key validation.
+- Existing built-in keyword dictionaries are copied from their stored key/value pairs,
+  avoiding quadratic source lookups for colliding string-subclass keys, even with a
+  zero timeout. Keys are still normalized and values preserved.
+- Dictionary subclasses with inherited read behavior and dictionary-backed mapping
+  proxies also avoid repeated source lookups for colliding keyword keys. Custom key
+  selection and value lookup retain their semantics, including through proxies.
+- An instance's `keys()` selection is preserved when its dictionary subclass aliases
+  a parent's `__dict__` descriptor, including through nested mapping proxies. Such
+  aliases previously caused excluded keywords to be passed to the callable.
+- Aliased instance namespace descriptors no longer force repeated keyword lookups
+  when dictionary reads are unmodified. Colliding string-subclass keys use stored
+  pairs directly, while instance `keys()` selection remains respected.
+- Validation and transport errors do not copy arbitrary exception text or notes.
+  Callable and type names in other diagnostics remain bounded to 60 characters; a
+  stand-in for an unpicklable callable exception keeps at most 300 characters of its
+  message. Ordinary callable exceptions and remote tracebacks retain their text.
+- Process mode: the budget also covers pickling the call and starting the child, and a
+  call whose pickling used it up is never started. A call that pickles in the caller but
+  cannot be loaded in the child (a function defined under the main guard, in
+  `python -c` or a notebook, or in a module the child cannot import; an argument whose
+  rebuild raises) raises `pickle.UnpicklingError` ("the call cannot be loaded in the
+  child process", with a safe category and library traceback chained as the cause)
+  instead of a crash with exit code 1. A child that dies while
+  sending its result raises `CallCrashed`, and waiting for a crashed child's exit code
+  never runs past the budget. A result that cannot be pickled raises
+  `pickle.PicklingError` with the child's library traceback, and a result that cannot
+  be rebuilt raises `pickle.UnpicklingError`. Both use value-free transport causes.
+- Process mode: the budget also covers receiving the result. On POSIX a long result is
+  written in two parts, and a child that stalled between or during them (stopped, or
+  blocked in a profile hook) blocked `run` for good; it is now stopped at the deadline
+  (terminated, and killed 1 second later) and the call raises `CallTimeout`.
+- Process mode: a child error whose pickle rebuilds as something other than an exception
+  arrives as the `RuntimeError` stand-in naming its type; `run` raised an
+  `AttributeError` or `TypeError` from inside calltimeout, and the child's error was lost.
+- Process mode: a call whose function or arguments cannot be pickled raises
+  `pickle.PicklingError` before any process starts, chained from a fresh standard
+  exception with fixed text. The cause preserves only a safe standard error category;
+  custom errors use `RuntimeError`. Original text, notes, frames and exception chains
+  are discarded without mutating the original error. This also applies to call loading,
+  result sending and result rebuilding failures. A call
+  holding objects that `multiprocessing` only pickles while a child starts (locks,
+  queues, shared values), any number of them, is first rehearsed as the start will
+  pickle it, so one whose contents cannot pickle (a `Value` guarded by a
+  `threading.Lock`) fails the same way, and one that still fails when the start pickles
+  it again (an object that pickles only once, a manager proxy whose pickling raises)
+  raises the same error, its child
+  stopped before it runs anything; a `KeyboardInterrupt` or `SystemExit` raised there is
+  raised as it is, once that child is stopped, instead of escaping half way through the
+  start, which on Windows could break later calls passing pipe ends. Under forkserver, a
+  call holding more than 248 descriptors (pipe ends, sockets, two per queue, one per block
+  of shared memory behind `Value` and `Array` objects, all named in the message), more than
+  one message to the fork server carries, raises `pickle.PicklingError` before any
+  process starts instead of an undocumented `OSError` or `ValueError` from the start. An
+  argument whose pickling raised `NotImplementedError` (a pool), `RecursionError` or a
+  `RuntimeError` used to fail after the child was created, and on Windows it then broke
+  the next process-mode call.
+- Process mode: the call's function and arguments are pickled once, before the start;
+  only its pipe ends, sockets and manager proxies, or the whole call when it holds locks
+  or queues, are pickled by the start itself. Pipe ends and sockets are handed to the
+  child by that start (POSIX passes the descriptors with it, Windows duplicates them
+  straight into the child), so none is left open in the caller, even when the budget
+  runs out while pickling the call or before the child has loaded it. Such a call left a
+  duplicate of each one open in the caller (on Windows also one of the result pipe,
+  whatever the call held; under forkserver the caller also printed `ConnectionResetError`
+  tracebacks), so the reader of that pipe never saw its end and handles ran out. A
+  manager proxy goes with its manager's authkey, as `multiprocessing` sends it: one of a
+  manager with its own authkey failed in the child with `AuthenticationError` unless the
+  call also held a lock. An argument whose `__class__` raises is sent as it pickles.
+- Process mode frees the child's handles as soon as the call ends. A call that raised
+  kept its child's process object, and its two descriptors or handles, alive in a
+  reference cycle until the next garbage collection, so a loop of failing calls could
+  run out of file descriptors (`OSError: [Errno 24] Too many open files`).
+- A generic process-mode `run` preserves a supplied callable's process timeout
+  decorator, including its independent deadline, fallback and zero-budget no-call rule.
+  Wrapper bypass is authorized once only by a child call initiated by that decorator.
+- `with_timeout` in process mode sends a callable that pickles by value (a
+  `functools.partial`, a callable object) as it is, as `run` does; it failed with
+  `AttributeError` under spawn and forkserver.
+- `with_timeout` in process mode works under a `classmethod` under spawn and forkserver
+  (the wrapper is sent through its class); it raised `pickle.PicklingError`.
+- Process mode: a child error whose type's own attributes raise (its traceback cannot be
+  formatted, its type cannot be named or pickled) arrives as a `RuntimeError` quoting its
+  text; the child crashed with exit code 1 and `run` raised `CallCrashed`.
+- A callable whose `__getattr__` raises something other than `AttributeError` is run
+  like any other; that error escaped from the coroutine check in `run` and
+  `with_timeout`.
+- `timeout` is annotated `float | numbers.Real` in `run` and `with_timeout`, so type
+  checkers accept a `Fraction`, which already worked.
+- Signal mode: an exception raised with an explicit cause while handling the timeout
+  (`raise E from other`) counts as the timeout, like `raise E` and `raise E from None`;
+  it escaped as `E`.
+- Signal mode: no timer is armed for less than 1 ms, so a timer tick less than 1 ms
+  before the deadline ends the call there, a timeout under 1 ms ends it at once without
+  starting it (like a zero timeout), and an enclosing timer due sooner than 1 ms has its
+  handler run up to 1 ms late. A timer that short could fire before the interrupted
+  system call blocked again, so a blocking call overran by its whole length.
+- Signal mode: a timer tick that lands after the call has finished can no longer re-arm
+  the timer.
+- Signal mode: an interval timer that was already running keeps its own schedule. Each
+  tick due during a call was counted from when it ran instead of when it was due, so up
+  to 1 ms of lateness per tick added up and ticks were lost (400 calls of 5 ms under a
+  10 ms timer: about 10 ticks lost, the last 120 to 130 ms late). On Linux a timer read
+  in the instant between a tick and its delivery shows no time left, and the call then
+  left it disarmed for good; it is now kept.
+- Signal mode: a `SIGALRM` taken as a call starts, before its timer is set (a tick of an
+  enclosing timer already on its way, also from an enclosing signal-mode call), goes to
+  the handler that was there before. It reached the call's own handler half set up: that
+  raised `NameError` and stayed installed for good (later code, even a plain
+  `time.sleep`, raised `NameError`), or it took the tick as its own and dropped it, so an
+  enclosing signal-mode deadline could be lost and the call run forever. A `SIGALRM`
+  that is not the call's own timer's (sent with `kill`) also goes to that handler.
+- Signal mode: an enclosing timer keeps its schedule over any number of calls. The call
+  reads and replaces it in one step, gives back the exact schedule it took, and waits
+  for a tick due within 0.2 ms before taking the timer (Linux 6.6 can drop a tick whose
+  timer is replaced in the instant it fires). Each call moved the timer by the time spent
+  reading and setting it, so over many calls a one-shot timer fired up to 18 ms early
+  (about 90,000 quick calls) and an interval timer drifted by milliseconds, lost ticks
+  (39 of 300 under calls that each timed out) and delivered some twice.
+- Every mode starts its budget after argument validation and keyword copying. Those
+  caller-side hooks are not interrupted. Thread mode includes starting the thread.
+- The coroutine error names `asyncio.wait_for()` as well as `asyncio.timeout()`, which
+  only exists from Python 3.11.
+- Every public name has a docstring with an example that runs as a doctest, `Mode` in
+  the package docstring (typing caches `Literal` aliases, so a docstring of its own would
+  relabel the caller's identical aliases), and a new GUIDE covers each mode, every
+  error and use from async code. The process-mode examples guard their entry point and
+  are tested as scripts.
+- `Development Status :: 5 - Production/Stable`.
+
+## [0.2.0] - 2026-10-12
+
+Published on PyPI on 2026-10-31; no git tag (commit 9b6975c on `main`).
+
+### Added
+
+- `mode="signal"`: a SIGALRM timer raises `CallTimeout` inside the call, which stops
+  pure Python code and blocking system calls in place. POSIX main thread only; other
+  threads get `RuntimeError` and Windows `NotImplementedError`. Timers already armed
+  keep their schedule (a raising outer handler runs once), so calls can be nested, and
+  a call that swallows the timeout still ends in `CallTimeout` when it returns, while
+  `KeyboardInterrupt`, `SystemExit` and unrelated errors propagate.
+- `with_timeout(timeout, *, mode, default)`: a decorator that keeps the wrapped
+  function's signature for type checkers (`ParamSpec`), in every mode including process
+  mode for functions the child can import by name (decorated in place or assigned to a
+  new name).
+- `CallCrashed`: raised in process mode when the child exits without a result, with its
+  exit code, as soon as it is gone.
+
+### Changed
+
+- Process mode waits on the result pipe and the process together, pickles results and
+  errors in the child (an unpicklable result raises `pickle.PicklingError` at once, an
+  unpicklable exception arrives as a `RuntimeError` stand-in), chains the child's
+  traceback as the cause, kills a child that ignores SIGTERM after 1 second, and stops
+  the child whenever the caller leaves early, including on `KeyboardInterrupt`.
+- Process mode notices a crashed child even while a grandchild it forked keeps the
+  pipes open.
+- Process mode pickles the call before starting the child, so a failed start cannot
+  leave the next call reading from a stale pipe on Windows; locks and queues, which
+  only pickle during start, are still passed through.
+- A finished child gets up to 1 second to exit on its own before it is terminated; a
+  result the parent cannot unpickle raises `pickle.UnpicklingError`.
+- `default` is returned only for the call's own timeout; a `CallTimeout` from a nested
+  call propagates.
+- Thread mode runs the call in a copy of the caller's context variables and names the
+  thread `calltimeout:<function>`.
+- `timeout` must be a real number (not a bool), not NaN and at most
+  `threading.TIMEOUT_MAX`; a zero timeout raises without starting the call. Coroutine
+  functions and coroutine results are rejected with a pointer to `asyncio.timeout`.
+  `kwargs` must be a mapping, and `run` and `with_timeout` reject modes the same way.
+- `CallTimeout` keeps its `timeout` through pickle and copy, and reports the validated
+  number of seconds.
+
+## [0.1.0] - 2026-10-11
+
+Never published or tagged (commit a3b7c15).
+
+- First version.
+- `run(fn, timeout, *, args, kwargs, mode, default)` runs a callable under a
+  wall-clock timeout and returns its typed result.
+- Raises `CallTimeout` (a subclass of `TimeoutError`) on overrun, or returns
+  `default` when one is given.
+- `mode="thread"` (default) stops waiting but cannot kill a stuck,
+  non-cooperative call: the thread lingers until it returns or the process exits.
+- `mode="process"` truly terminates the call on overrun, at the cost of needing
+  picklable arguments and result.

{calltimeout-0.2.0 → calltimeout-1.0.0}/CONTRIBUTING.md

@@ -11,8 +11,10 @@ pip install -r requirements-dev.txt
 ## Before you open a pull request
 
 - Keep public API in `src/calltimeout/__init__.py`; internals live in `_`-prefixed modules.
-- Add a test for the behaviour you change. Tests inject time, disk and network; they
-  never touch the real thing.
+- Add a test for the behaviour you change. The library's promise is about real time, so
+  the suite measures real budgets with real threads, child processes and timers. Tests
+  use no network (sockets only as local pairs handed to a child), and write files only
+  under pytest's `tmp_path`.
 - Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
 - One logical change per commit, imperative subject line.
 

calltimeout-1.0.0/GUIDE.md

@@ -0,0 +1,292 @@
+# calltimeout guide
+
+The [README](https://github.com/JaviLianes8/calltimeout/blob/main/README.md) shows the
+basics. This guide covers each mechanism in depth, the errors, nesting and async code.
+Every example here is run as a script by the tests.
+
+## The call
+
+`run(fn, timeout, *, args=(), kwargs=None, mode="thread", default=...)` calls
+`fn(*args, **kwargs)` and returns its result. `timeout` is a number of seconds: an `int`,
+a `float` or another real number such as a `Fraction`, not a `bool`, not negative, not
+NaN and at most `threading.TIMEOUT_MAX` (so not infinite). A zero timeout raises at once
+without starting the call (in signal mode, so does any timeout under 1 ms). These
+checks, and the ones on `fn`, `args`, `kwargs` and `mode`, happen before anything
+starts, in every mode. `mode` is one of the three names of `Mode`,
+`Literal["thread", "process", "signal"]`, which you can use to annotate your own
+wrappers. `kwargs` is copied into a plain `dict` in the caller before the call starts, so
+a mapping changed later does not affect the call. String-subclass keys are normalized
+before insertion, so dictionary insertion uses base-string hashing and equality.
+Ordinary failures while reading the mapping raise `TypeError`.
+
+Validation and keyword copying precede the budget in every mode. User-defined numeric
+conversion and mapping hooks run in the caller and are not interrupted. The budget
+starts after those checks; thread startup is included.
+
+The budget covers the call itself, so `fn` must do its work when called. A coroutine
+function or an async generator function raises `TypeError` with a pointer to `asyncio`,
+and so does a call that returns a coroutine or an async generator. A generator function
+raises `TypeError` too: calling it only creates the generator, and its body would run as
+it is iterated, after `run` returned, outside the budget. Run a function that consumes it
+instead. A callable that returns some other lazy object (`map`, a file read later) is
+timed only until it returns that object.
+
+When the budget runs out, `run` raises `CallTimeout`, or returns `default` if one was
+given (`None` is a valid default). An exception raised by the call reaches the caller. A
+`CallTimeout` from a nested call inside `fn` is not this call's timeout: it propagates
+even when this call has a default.
+
+```python
+import time
+
+from calltimeout import CallTimeout, run
+
+
+def inner() -> None:
+    return run(time.sleep, 0.05, args=(10,))
+
+
+try:
+    run(inner, 5.0, default="outer default")
+except CallTimeout as exc:
+    print(f"the inner {exc.timeout} second budget ran out")  # the inner 0.05 second budget ran out
+```
+
+## Thread mode
+
+The default. The call runs in a daemon thread named `calltimeout:<function>`, in a copy
+of the caller's context variables (as `asyncio.to_thread` does), and `run` stops waiting
+when the budget runs out. Python cannot stop a running thread, so a call that ignores the
+clock 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. Use thread mode for calls that end on their own, eventually.
+
+Thread and process mode measure the budget with `time.monotonic()`, whose resolution
+`time.get_clock_info("monotonic")` reports. On Windows it is `GetTickCount64()`, about
+15.6 ms, up to Python 3.12, and `QueryPerformanceCounter()` from 3.13. In thread mode the
+GIL limits precision more than the clock: a call running Python code holds it, and lets
+the waiting caller run only every switch interval (`sys.getswitchinterval()`, 5 ms by
+default). So `CallTimeout` can come up to about two intervals after the budget ran out. A
+call that ends after the budget ran out, even before the caller noticed, is a timeout:
+what it returned or raised then is dropped, as in process mode. Free-threaded builds have
+no GIL and no such delay.
+
+## Process mode
+
+The call runs in a child process that is terminated when the budget runs out (SIGTERM on
+POSIX, `TerminateProcess` on Windows), and killed if it is still alive 1 second later.
+The budget covers pickling the call, starting the child and receiving its result.
+Pickling runs in the caller and is not interrupted: a slow `__reduce__` overruns the
+budget by as long as it takes (and one that never returns blocks `run`), but a call whose
+pickling used up the budget is never started. A result still arriving when the budget
+runs out (a huge one, or one whose child stalled half way through sending it) ends the
+call like any overrun: the child is stopped and `CallTimeout` raised. Rebuilding the
+result also runs in the caller, once it has arrived, and is neither counted against the
+budget nor interrupted: a result whose rebuild is slow delays `run` by as long (and one
+that never returns blocks it).
+
+- `fn`, its arguments and its result cross the process boundary, so they must pickle
+  (under fork only the result is pickled, see below).
+  Targets must be importable: define them at module level, and guard the entry point of
+  a script with `if __name__ == "__main__":` as `multiprocessing` requires. Locks, queues,
+  pipe ends, sockets, manager proxies and other `multiprocessing` objects can be passed as
+  arguments, any number of them, except under forkserver (below). Pipe ends and sockets
+  are handed over by the start itself (on Windows, duplicated straight into the child), so
+  none is left open in the caller, even when the budget runs out before the child has
+  loaded the call.
+- A forkserver start sends every descriptor of the call to the fork server in one
+  message, which Linux caps. So under forkserver a call carries at most 248 descriptors:
+  one per pipe end or socket, two per queue, and one per block of the shared memory that
+  `Value` and `Array` objects live in (many share one). A call holding more raises
+  `pickle.PicklingError` before any process starts.
+- Under spawn and forkserver a call that cannot be pickled (a lambda, a thread lock, a
+  pool, an argument nested too deeply) raises `pickle.PicklingError` before any process
+  starts, chained from a fresh exception containing only a safe category and fixed text.
+  A call holding locks or queues is rehearsed as the start will pickle it, so one whose
+  contents cannot pickle (a `Value` guarded by a `threading.Lock`) fails the same way.
+  One that still fails when the start pickles it again (an object that pickles only once,
+  a manager proxy whose pickling raises) raises the same error, and the child created for
+  it is stopped before it runs anything. A `KeyboardInterrupt` or other exception that is
+  not an `Exception`, raised there, is raised as it is once that child is stopped. Under
+  fork nothing is pickled on the way in.
+- Under spawn and forkserver a call that pickles in the caller but cannot be loaded in
+  the child (a function defined under `if __name__ == "__main__":`, in `python -c` or a
+  notebook, or in a module the child cannot import; an argument whose rebuild raises)
+  raises `pickle.UnpicklingError` with a safe error category and the child's
+  library traceback chained as its cause.
+- The child process is named `calltimeout:<function>`, like the thread of thread mode.
+- 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, not a timeout, and never
+  the default. The code is the one `multiprocessing` reports: the value given to
+  `os._exit`, or `-N` for a child killed by signal `N` on POSIX.
+- An exception from the child arrives with the child's traceback chained as its cause:
+  a `RemoteTraceback`, whose text (also its `text` attribute) is that traceback. One that
+  cannot be pickled, or that would arrive as something other than an exception, arrives
+  as a `RuntimeError` naming its type and quoting its text.
+  `sys.exit()` in the call raises `SystemExit` in the caller like any other exception.
+- A result that cannot be pickled raises `pickle.PicklingError` at once, and one the
+  parent cannot rebuild raises `pickle.UnpicklingError`.
+- After the result arrives the child gets up to 1 second to shut down on its own before
+  it is terminated: its non-daemon threads finish, and its atexit handlers run where
+  `multiprocessing` runs them in a child (under spawn, and under fork and forkserver from
+  Python 3.13).
+- Processes started by the call itself are not stopped with it.
+
+```python
+import os
+
+from calltimeout import CallCrashed, run
+
+
+def main() -> None:
+    try:
+        run(os._exit, 30.0, args=(3,), mode="process")
+    except CallCrashed as exc:
+        print(f"exit code {exc.exitcode}")  # exit code 3
+
+    try:
+        run(int, 30.0, args=("ten",), mode="process")
+    except ValueError as exc:
+        print(type(exc.__cause__).__name__)  # RemoteTraceback
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Signal mode
+
+A `SIGALRM` timer 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 only works in the
+main thread on POSIX: in another thread it raises `RuntimeError`, and on Windows
+`NotImplementedError`. Some C code checks for signals as it runs (a regular expression
+match does), but a long call inside C that does not (sorting a huge list, `sum()` over a
+long `range`) is only interrupted once it returns to Python.
+
+- A call that catches the timeout and carries on still ends in `CallTimeout`, 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, also one raised
+  `from` another cause; `KeyboardInterrupt`, `SystemExit` and unrelated errors propagate.
+- No timer is armed for less than 1 ms: a tick due that soon could land before an
+  interrupted system call blocks again and be lost, letting a blocking call run to its
+  end. So a tick that arrives less than 1 ms before the deadline (an enclosing timer, a
+  stray `SIGALRM`) ends the call there, and a timeout under 1 ms ends it at once without
+  starting it.
+- Timers already armed with `setitimer` or `alarm` keep their schedule and their handler
+  still runs when due (up to 1 ms late, by the rule above), so signal-mode calls can be
+  nested. An interval timer's ticks stay on its own schedule, over any number of calls:
+  none is lost or delivered twice, and the lateness of one tick does not carry over to
+  the next. A call that starts within 0.2 ms of such a tick lets it through first (Linux
+  can lose a tick whose timer is replaced in the instant it fires), which counts against
+  its budget. A `SIGALRM` that is not the call's own (a tick already on its way as the call
+  starts, or one sent with `kill`) goes to the handler that was there before. A call that
+  resets `ITIMER_REAL` itself, or installs
+  its own `SIGALRM` handler (`SIG_IGN` included, as an alarm-based helper may), cancels
+  the deadline: its result is then returned even if the budget ran out. A `SIGALRM`
+  handler installed outside Python is refused, because it could not be restored.
+
+```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
+```
+
+## The decorator
+
+`with_timeout(timeout, *, mode="thread", default=...)` makes every call of the decorated
+function go through `run`. Type checkers keep checking each call against the original
+parameters, and the result type becomes `T | D` with a default. The settings are checked
+when the decorator is made, and the function when it is applied. Signal mode's platform
+and main-thread checks run at each call instead, since a decorated function can be called
+from any thread: on Windows the decorator is made, and each call raises
+`NotImplementedError`.
+
+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)`. A
+method of a module-level class works too, as an instance method, a `staticmethod` or a
+`classmethod` (with `with_timeout` applied first, under the method decorator). A
+callable that pickles by value (a `functools.partial`, a callable object) is sent as it is.
+Each call runs in its own child, also a call made from inside the function's own child
+(a recursive function gets a new child, with its own budget, for every level).
+Passing a decorated function to `run(..., mode="process")` preserves the decorator's
+independent timeout, fallback and zero-budget guarantee. Only the child started by
+that decorator itself may bypass its wrapper once to execute the body.
+
+```python
+import time
+
+from calltimeout import with_timeout
+
+
+@with_timeout(0.05, default=None)
+def lookup(key: str) -> str:
+    time.sleep(1.0)
+    return key.upper()
+
+
+print(lookup("id"))  # None
+```
+
+## Errors
+
+| Raised | When |
+|---|---|
+| `CallTimeout` (a `TimeoutError`) | The budget ran out and no default was given |
+| `CallCrashed` (a `RuntimeError`) | Process mode: the child exited without a result |
+| `TypeError` | `timeout` is not a real number (or one that fails to convert to `float`), `fn` is not callable or is a coroutine, async generator or generator function, `args` is not a tuple, `kwargs` is not a readable mapping of `str` keys, `mode` is not a `str`, or the call returned a coroutine or an async generator |
+| `ValueError` | `timeout` is negative, NaN or above `threading.TIMEOUT_MAX`, or `mode` is not one of the three names |
+| `RuntimeError` | Signal mode outside the main thread, or with a `SIGALRM` handler set outside Python; process mode: the call raised an exception that cannot be pickled, or that would arrive as something other than an exception (raised in its place, naming its type) |
+| `NotImplementedError` | Signal mode on Windows |
+| `pickle.PicklingError` | Process mode: `fn` or an argument cannot be sent to the child (raised before the call runs: before any process starts, or once the child is stopped for a call that fails only when the start pickles it), a forkserver call holds more than 248 descriptors, or the result cannot be sent back |
+| `pickle.UnpicklingError` | Process mode: the call cannot be loaded in the child (it pickles in the caller, but the child cannot import its function or rebuild an argument), or the result cannot be rebuilt in the caller |
+
+Both exceptions keep their attribute through pickle and copy, so they can cross process
+boundaries themselves. Invalid mode errors list the accepted names without echoing the
+supplied value. Failed timeout conversions and mapping reads produce fixed `TypeError`
+messages without retaining the original exception as a cause or context.
+
+Transport diagnostics identify the operation and a safe standard exception category.
+Their causes contain only fixed text: original messages, notes, traceback frames and
+exception chains are discarded, including errors from pickling or rebuilding either
+the call or its result. Custom exception types become `RuntimeError` causes. Original
+exceptions are not modified. Truncation alone would still expose short secrets.
+
+These protections apply to library-generated validation and transport diagnostics.
+Exceptions deliberately raised by the callable retain their own messages and, in
+process mode, their remote traceback; that text may contain caller data. Callable and
+type names used in other diagnostics are bounded to 60 characters, and the stand-in
+for an unpicklable callable exception keeps up to 300 characters of its message.
+
+## In async code
+
+Coroutines already have `asyncio.timeout()` (Python 3.11+) and `asyncio.wait_for()`, and
+`run` refuses coroutine and async generator functions with a pointer to them. 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 | None:
+    return await asyncio.to_thread(
+        run, time.sleep, 0.5, args=(60,), mode="process", default="stopped"
+    )
+
+
+if __name__ == "__main__":
+    print(asyncio.run(main()))  # stopped
+```