interruptible 1.0.0__tar.gz

interruptible-1.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Build artefacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Generated version file (setuptools-scm)
+src/interruptible/_version.py
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Editor swap files
+*.swp

interruptible-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Manthey
+
+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.

interruptible-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# Include the manual platform check in the sdist.  README.md and LICENSE are
+# included automatically by setuptools.  PLAN.md is developer documentation and
+# deliberately not shipped, as are the developer tooling configs.
+recursive-include examples *.py
+exclude PLAN.md
+exclude .flake8
+exclude .pre-commit-config.yaml
+exclude .ruff.toml
+recursive-exclude .github *
+recursive-exclude .tox *

interruptible-1.0.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: interruptible
+Version: 1.0.0
+Summary: Guaranteed, transparent Ctrl+C for Python programs
+Author-email: David Manthey <manthey@orbitals.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/manthey/interruptible
+Project-URL: Repository, https://github.com/manthey/interruptible
+Project-URL: Issues, https://github.com/manthey/interruptible/issues
+Keywords: ctrl-c,sigint,signal,interrupt,keyboardinterrupt,subprocess,timeout
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+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 :: Python Modules
+Classifier: Topic :: System :: Operating System Kernels
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# interruptible
+
+**Guaranteed, transparent Ctrl+C for Python programs.**
+
+`interruptible` makes Ctrl+C work *promptly* even when your program is blocked
+inside a native C/Rust extension that never returns to the Python bytecode
+evaluator -- for example an HTTP request through a library that does not poll
+for interrupts, a database driver, or a long-running computation in NumPy.
+
+```python
+import sys
+import interruptible
+
+def main():
+    # Anything at all here, including blocking C calls.
+    ...
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(interruptible.run(main))
+```
+
+Press Ctrl+C and the program stops, now.
+
+## Why this is needed
+
+Python delivers signals by setting a flag that the interpreter checks *between
+bytecodes*.  If your code is blocked inside a C extension, the interpreter is
+never reached, so `KeyboardInterrupt` is not raised until the call returns --
+which may be never.  On Windows it is worse: a blocking call is not interrupted
+at all.
+
+There is no way to fix this from inside the blocked process.  So `interruptible`
+runs your `main` in a child process.  The parent does nothing but wait, so it is
+always able to react to Ctrl+C immediately; on interrupt it forwards the signal
+to the child and, if the child is one of the ill-behaved ones, forcibly
+terminates the child's entire process tree.
+
+## Transparency
+
+The design goal is that a wrapped program is indistinguishable from an unwrapped
+one, apart from interrupts always working:
+
+| Behaviour | `interruptible` result |
+| --- | --- |
+| `main()` returns `0` | exit code `0` |
+| `main()` returns `N` | exit code `N` |
+| `main()` raises | traceback on stderr, exit code `1` |
+| `sys.exit(N)` | exit code `N` |
+| Ctrl+C, child exits on its own | exit code `130` (`128 + SIGINT`) |
+| `SIGTERM` | exit code `143` (`128 + SIGTERM`) |
+| Ctrl+C, child ignores it | child tree killed after `kill_timeout`; exit code `130` |
+| `timeout=` expires | child signalled, exit code `127` |
+| stdout/stderr | forwarded live to the parent's streams |
+
+The signal the *user* sent determines the exit code, so Ctrl+C always reports
+`130`, exactly as an unwrapped program would.
+
+## Install
+
+```sh
+pip install interruptible
+```
+
+No runtime dependencies.  Python 3.10+.
+
+## Usage
+
+### Function
+
+```python
+sys.exit(interruptible.run(main, timeout=60, kill_timeout=5.0))
+```
+
+### Decorator
+
+```python
+@interruptible.interruptible(timeout=300)
+def main():
+    ...
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+### API
+
+```python
+def run(
+    target: Callable[..., int | None],
+    *args,
+    timeout: float | None = None,
+    kill_timeout: float = 5.0,
+    passthrough_signals: tuple[int, ...] = (signal.SIGINT, signal.SIGTERM),
+    inherit_environ: bool = True,
+    **kwargs,
+) -> int: ...
+```
+
+* `target` -- the function to run.  On spawn platforms (Windows, macOS) it must
+  be picklable, which means a module-level function in a real file; see the FAQ.
+* `timeout` -- maximum runtime in seconds (`None` = unlimited).  On expiry the
+  child is signalled and `127` is returned.
+* `kill_timeout` -- seconds to wait for a graceful exit after forwarding a
+  signal before force-killing the child's process tree.
+* `passthrough_signals` -- signals received by the parent that are forwarded to
+  the child.
+* `inherit_environ` -- whether the child inherits the environment.
+
+## FAQ
+
+**Why a subprocess?**  Because there is no other way to be responsive while the
+main thread is stuck inside native code.  A thread or an asyncio task cannot
+help: they cannot preempt a blocked C call either.
+
+**Doesn't `signal.set_wakeup_fd` / `faulthandler` solve this?**  Those change how
+the *interpreter* notices signals; they do not make a blocked native call
+return.
+
+**What about child processes I spawn myself?**  On POSIX the child runs in its
+own process group, and the whole group is signalled during cleanup.  On Windows
+the child is attached to a Job Object configured to kill all member processes
+when the job closes, so grandchildren die too.
+
+**Nested use.** If `run()` is called from inside a child (detected via the
+`INTERRUPTIBLE_CHILD` environment variable), the target runs inline instead of
+spawning another process.
+
+**Why did I get `Can't pickle local object`?**  On Windows, and on macOS since
+Python 3.8, the child is started with `spawn`, which sends the target to the new
+interpreter by pickling it *by module and name*.  Two things therefore cannot be
+used as a target:
+
+* a nested function, lambda, closure, or bound method defined inside another
+  function;
+* a function defined in a `python -c` string or an interactive session, because
+  its `__main__` has no importable name.
+
+Both fail with `AttributeError` once the child tries to unpickle the target.  Use
+a module-level function in a real file:
+
+```python
+# do this
+def main():
+    ...
+
+if __name__ == '__main__':
+    sys.exit(interruptible.run(main))
+
+
+# not this -- main cannot be pickled
+if __name__ == '__main__':
+    def main():
+        ...
+
+    sys.exit(interruptible.run(main))
+```
+
+## Platform notes
+
+`run()` uses the platform's default `multiprocessing` start method.  That is
+`spawn` on Windows and macOS and `fork` on Linux, and the difference matters:
+`spawn` requires a picklable (module-level) target, while `fork` accepts
+anything.  Forcing `fork` on Linux was deliberately rejected -- it is unsafe in
+a process with threads and it would hide this requirement from anyone
+developing on Linux.  To check your code under the stricter `spawn` rules on
+Linux, set the start method before calling `run()`:
+
+```python
+import multiprocessing
+
+multiprocessing.set_start_method('spawn')
+```
+
+* **Spawn platforms (Windows, macOS)** -- the target must be picklable.
+* **POSIX** -- the parent forwards the exact signal it received (so the child
+  sees a normal `KeyboardInterrupt`), then `SIGKILL`s the process group if the
+  child has not exited within `kill_timeout`.
+* **Windows** -- a child started by `multiprocessing` shares the parent's
+  console process group, so the console delivers Ctrl+C to it directly; no
+  explicit forwarding is needed.  The Job Object guarantees the whole tree is
+  cleaned up if the child ignores it.
+
+## License
+
+MIT

interruptible-1.0.0/README.md

@@ -0,0 +1,186 @@
+# interruptible
+
+**Guaranteed, transparent Ctrl+C for Python programs.**
+
+`interruptible` makes Ctrl+C work *promptly* even when your program is blocked
+inside a native C/Rust extension that never returns to the Python bytecode
+evaluator -- for example an HTTP request through a library that does not poll
+for interrupts, a database driver, or a long-running computation in NumPy.
+
+```python
+import sys
+import interruptible
+
+def main():
+    # Anything at all here, including blocking C calls.
+    ...
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(interruptible.run(main))
+```
+
+Press Ctrl+C and the program stops, now.
+
+## Why this is needed
+
+Python delivers signals by setting a flag that the interpreter checks *between
+bytecodes*.  If your code is blocked inside a C extension, the interpreter is
+never reached, so `KeyboardInterrupt` is not raised until the call returns --
+which may be never.  On Windows it is worse: a blocking call is not interrupted
+at all.
+
+There is no way to fix this from inside the blocked process.  So `interruptible`
+runs your `main` in a child process.  The parent does nothing but wait, so it is
+always able to react to Ctrl+C immediately; on interrupt it forwards the signal
+to the child and, if the child is one of the ill-behaved ones, forcibly
+terminates the child's entire process tree.
+
+## Transparency
+
+The design goal is that a wrapped program is indistinguishable from an unwrapped
+one, apart from interrupts always working:
+
+| Behaviour | `interruptible` result |
+| --- | --- |
+| `main()` returns `0` | exit code `0` |
+| `main()` returns `N` | exit code `N` |
+| `main()` raises | traceback on stderr, exit code `1` |
+| `sys.exit(N)` | exit code `N` |
+| Ctrl+C, child exits on its own | exit code `130` (`128 + SIGINT`) |
+| `SIGTERM` | exit code `143` (`128 + SIGTERM`) |
+| Ctrl+C, child ignores it | child tree killed after `kill_timeout`; exit code `130` |
+| `timeout=` expires | child signalled, exit code `127` |
+| stdout/stderr | forwarded live to the parent's streams |
+
+The signal the *user* sent determines the exit code, so Ctrl+C always reports
+`130`, exactly as an unwrapped program would.
+
+## Install
+
+```sh
+pip install interruptible
+```
+
+No runtime dependencies.  Python 3.10+.
+
+## Usage
+
+### Function
+
+```python
+sys.exit(interruptible.run(main, timeout=60, kill_timeout=5.0))
+```
+
+### Decorator
+
+```python
+@interruptible.interruptible(timeout=300)
+def main():
+    ...
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+### API
+
+```python
+def run(
+    target: Callable[..., int | None],
+    *args,
+    timeout: float | None = None,
+    kill_timeout: float = 5.0,
+    passthrough_signals: tuple[int, ...] = (signal.SIGINT, signal.SIGTERM),
+    inherit_environ: bool = True,
+    **kwargs,
+) -> int: ...
+```
+
+* `target` -- the function to run.  On spawn platforms (Windows, macOS) it must
+  be picklable, which means a module-level function in a real file; see the FAQ.
+* `timeout` -- maximum runtime in seconds (`None` = unlimited).  On expiry the
+  child is signalled and `127` is returned.
+* `kill_timeout` -- seconds to wait for a graceful exit after forwarding a
+  signal before force-killing the child's process tree.
+* `passthrough_signals` -- signals received by the parent that are forwarded to
+  the child.
+* `inherit_environ` -- whether the child inherits the environment.
+
+## FAQ
+
+**Why a subprocess?**  Because there is no other way to be responsive while the
+main thread is stuck inside native code.  A thread or an asyncio task cannot
+help: they cannot preempt a blocked C call either.
+
+**Doesn't `signal.set_wakeup_fd` / `faulthandler` solve this?**  Those change how
+the *interpreter* notices signals; they do not make a blocked native call
+return.
+
+**What about child processes I spawn myself?**  On POSIX the child runs in its
+own process group, and the whole group is signalled during cleanup.  On Windows
+the child is attached to a Job Object configured to kill all member processes
+when the job closes, so grandchildren die too.
+
+**Nested use.** If `run()` is called from inside a child (detected via the
+`INTERRUPTIBLE_CHILD` environment variable), the target runs inline instead of
+spawning another process.
+
+**Why did I get `Can't pickle local object`?**  On Windows, and on macOS since
+Python 3.8, the child is started with `spawn`, which sends the target to the new
+interpreter by pickling it *by module and name*.  Two things therefore cannot be
+used as a target:
+
+* a nested function, lambda, closure, or bound method defined inside another
+  function;
+* a function defined in a `python -c` string or an interactive session, because
+  its `__main__` has no importable name.
+
+Both fail with `AttributeError` once the child tries to unpickle the target.  Use
+a module-level function in a real file:
+
+```python
+# do this
+def main():
+    ...
+
+if __name__ == '__main__':
+    sys.exit(interruptible.run(main))
+
+
+# not this -- main cannot be pickled
+if __name__ == '__main__':
+    def main():
+        ...
+
+    sys.exit(interruptible.run(main))
+```
+
+## Platform notes
+
+`run()` uses the platform's default `multiprocessing` start method.  That is
+`spawn` on Windows and macOS and `fork` on Linux, and the difference matters:
+`spawn` requires a picklable (module-level) target, while `fork` accepts
+anything.  Forcing `fork` on Linux was deliberately rejected -- it is unsafe in
+a process with threads and it would hide this requirement from anyone
+developing on Linux.  To check your code under the stricter `spawn` rules on
+Linux, set the start method before calling `run()`:
+
+```python
+import multiprocessing
+
+multiprocessing.set_start_method('spawn')
+```
+
+* **Spawn platforms (Windows, macOS)** -- the target must be picklable.
+* **POSIX** -- the parent forwards the exact signal it received (so the child
+  sees a normal `KeyboardInterrupt`), then `SIGKILL`s the process group if the
+  child has not exited within `kill_timeout`.
+* **Windows** -- a child started by `multiprocessing` shares the parent's
+  console process group, so the console delivers Ctrl+C to it directly; no
+  explicit forwarding is needed.  The Job Object guarantees the whole tree is
+  cleaned up if the child ignores it.
+
+## License
+
+MIT

interruptible-1.0.0/examples/manual_ctrlc.py

@@ -0,0 +1,58 @@
+"""Manual Ctrl+C check.
+
+Run this in a real console window and press Ctrl+C.  It is the one check that
+cannot be automated: CI runners are non-interactive and cannot generate a
+genuine console interrupt, so this must be done by hand on each platform, and
+especially on Windows.
+
+Expected result either way: the program stops within about a second and exits
+with code 130 (128 + SIGINT), leaving no surviving process.
+
+The default target deliberately *ignores* SIGINT and SIGTERM, simulating the
+native extension this package exists for.  Pass ``--graceful`` to use a
+well-behaved target instead: it must print a KeyboardInterrupt traceback, which
+proves the child was interrupted rather than hard-killed.
+
+Usage:
+    python examples/manual_ctrlc.py            # child ignores the signal
+    python examples/manual_ctrlc.py --graceful # child handles it
+
+Then press Ctrl+C.  To see the exit code:
+    cmd:        ... ; echo exit=%errorlevel%
+    PowerShell: ... ; echo "exit=$LASTEXITCODE"
+"""
+
+from __future__ import annotations
+
+import signal
+import sys
+import time
+
+import interruptible
+
+# Kill after this many seconds if the child refuses to die.  Kept short so the
+# manual test is quick.
+KILL_TIMEOUT = 1.0
+
+
+def stubborn_target() -> int:
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    signal.signal(signal.SIGTERM, signal.SIG_IGN)
+    print('Press Ctrl+C.  The process should stop within a second.', flush=True)
+    while True:
+        time.sleep(0.05)
+
+
+def graceful_target() -> int:
+    print('Press Ctrl+C.  Expect a KeyboardInterrupt traceback, then exit 130.', flush=True)
+    while True:
+        time.sleep(0.05)
+
+
+def main() -> int:
+    target = graceful_target if '--graceful' in sys.argv[1:] else stubborn_target
+    return interruptible.run(target, kill_timeout=KILL_TIMEOUT)
+
+
+if __name__ == '__main__':
+    sys.exit(main())

interruptible-1.0.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "interruptible"
+description = "Guaranteed, transparent Ctrl+C for Python programs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "David Manthey", email = "manthey@orbitals.com" }]
+keywords = [
+    "ctrl-c",
+    "sigint",
+    "signal",
+    "interrupt",
+    "keyboardinterrupt",
+    "subprocess",
+    "timeout",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Operating System Kernels",
+]
+dependencies = []
+dynamic = ["version"]
+
+[dependency-groups]
+test = [
+    "pytest>=8",
+]
+dev = [
+    { include-group = "test" },
+    "build>=1.2",
+    "tox>=4.20",
+]
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+env_list = py310, py311, py312, py313, py314, precommit
+isolated_build = True
+skip_missing_interpreters = True
+
+[testenv]
+package = editable
+dependency_groups = test
+commands = python -m pytest {posargs:-v}
+
+[testenv:precommit]
+package = skip
+deps = pre-commit
+description = run all pre-commit hooks
+skip_install = True
+commands = pre-commit run --all-files --show-diff-on-failure
+
+[testenv:build]
+package = skip
+deps = build
+description = build sdist and wheel
+commands = python -m build
+"""
+
+[project.urls]
+Homepage = "https://github.com/manthey/interruptible"
+Repository = "https://github.com/manthey/interruptible"
+Issues = "https://github.com/manthey/interruptible/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+version_file = "src/interruptible/_version.py"
+fallback_version = "0.0.0.dev0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

interruptible-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

interruptible-1.0.0/src/interruptible/__init__.py

@@ -0,0 +1,35 @@
+"""``interruptible`` -- reliable Ctrl+C for Python programs.
+
+Wrap a program's entry point to guarantee that Ctrl+C terminates it promptly,
+even when it is blocked inside a native C/Rust extension that fails to honour
+signals::
+
+    import sys
+    import interruptible
+
+    def main():
+        ...  # may block in a C extension
+        return 0
+
+    if __name__ == "__main__":
+        sys.exit(interruptible.run(main))
+
+The goal is transparency: the wrapped program behaves as though this module were
+not present, except that interrupts always work.
+"""
+
+from __future__ import annotations
+
+from .core import DEFAULT_KILL_TIMEOUT, TIMEOUT_EXIT_CODE, interruptible, run
+
+__all__ = [
+    'run',
+    'interruptible',
+    'DEFAULT_KILL_TIMEOUT',
+    'TIMEOUT_EXIT_CODE',
+]
+try:  # pragma: no cover - the version is generated by setuptools-scm
+    from ._version import __version__, __version_tuple__
+except ImportError:  # pragma: no cover
+    __version__ = '0.0.0.dev0'
+    __version_tuple__ = (0, 0, 0, 'dev0')