interruptible 1.0.0__py3-none-any.whl

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')

interruptible/_child.py

@@ -0,0 +1,118 @@
+"""Code that runs inside the child process.
+
+This module must be importable by a spawned child.  On platforms that use the
+``spawn`` start method (notably Windows and macOS since 3.8) the child
+re-imports the target as a pickle reference, so everything here must be
+importable without side effects and must not depend on the parent's state.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import sys
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+if sys.platform == 'win32':  # pragma: no cover - platform dispatch
+    from . import _windows as _platform
+else:
+    from . import _posix as _platform
+
+__all__ = ['child_main', 'run_inline']
+
+
+def configure_child() -> None:
+    """Platform hook run in the child before the target starts."""
+    try:
+        _platform.configure_child()
+    except Exception:  # pragma: no cover - never let setup break the child
+        pass
+
+
+def child_main(
+    target: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    inherit_environ: bool = True,
+) -> None:
+    """Entry point executed in the child process.
+
+    The target's return value becomes the child's exit code.  ``multiprocessing``
+    ignores a target's return value, so the code is applied via ``sys.exit``.
+    A ``SystemExit`` raised by the target is honoured (its code is used), and any
+    other exception is reported to stderr with a traceback before exiting with
+    code 1 -- mirroring what an uncaught exception does in a plain Python
+    program.
+    """
+    # Mark the environment so nested ``interruptible.run`` calls run inline
+    # rather than spawning another child.  This happens before any environment
+    # clearing so the marker is always present in the child.
+    os.environ['INTERRUPTIBLE_CHILD'] = '1'
+    if not inherit_environ:
+        # Present an empty environment to the target, matching what a program
+        # started with ``env -i`` would see.  The marker is kept so nested runs
+        # are still detected.
+        marker = {key: os.environ[key] for key in ('INTERRUPTIBLE_CHILD',) if key in os.environ}
+        os.environ.clear()
+        os.environ.update(marker)
+    # Detach into our own process group (POSIX) so the parent can signal the
+    # whole subtree -- including any grandchildren -- during cleanup.
+    configure_child()
+    try:
+        result = target(*args, **kwargs)
+    except SystemExit as exc:
+        sys.exit(normalize_exit_code(exc.code))
+    except KeyboardInterrupt:
+        # Match CPython's behaviour for a program interrupted by Ctrl+C: print
+        # the traceback and exit with ``128 + SIGINT``.  Reporting 1 here would
+        # break the transparency guarantee, since a plain program reports 130.
+        traceback.print_exc()
+        sys.stderr.flush()
+        sys.exit(128 + signal.SIGINT)
+    except BaseException:
+        traceback.print_exc()
+        sys.stderr.flush()
+        sys.exit(1)
+    sys.exit(normalize_exit_code(result))
+
+
+def run_inline(target: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]) -> int:
+    """Run ``target`` in the current process and return its exit code.
+
+    Used for nested ``run`` calls inside an existing child, where spawning
+    another process would be pointless.  Exceptions behave as in ``child_main``
+    except that they are not swallowed: an uncaught exception is printed and
+    reported as exit code 1, matching what the surrounding program would see.
+    """
+    try:
+        result = target(*args, **kwargs)
+    except SystemExit as exc:
+        return normalize_exit_code(exc.code)
+    except KeyboardInterrupt:
+        # As in ``child_main``, an interrupt reports ``128 + SIGINT``.
+        traceback.print_exc()
+        sys.stderr.flush()
+        return 128 + signal.SIGINT
+    except BaseException:
+        traceback.print_exc()
+        sys.stderr.flush()
+        return 1
+    return normalize_exit_code(result)
+
+
+def normalize_exit_code(code: Any) -> int:
+    """Coerce a user-provided exit code into an 8-bit process exit status."""
+    if code is None:
+        return 0
+    if isinstance(code, bool):
+        return int(code)
+    if isinstance(code, int):
+        # POSIX exit statuses are 8-bit; emulate that truncation so behaviour
+        # matches a plain ``sys.exit(n)``.
+        return code & 0xFF
+    # Non-integer, non-None values passed to SystemExit are printed and the
+    # process exits with status 1, exactly as CPython does.
+    print(code, file=sys.stderr)
+    return 1

interruptible/_posix.py

@@ -0,0 +1,38 @@
+"""POSIX-specific process group helpers."""
+
+from __future__ import annotations
+
+import os
+import subprocess  # noqa: F401  (imported for typing clarity only)
+from typing import Any
+
+__all__ = ['configure_child', 'kill_tree']
+
+
+def configure_child() -> None:
+    """Run in the child, before the target, to detach its process group.
+
+    Making the child a process-group leader means we can signal the entire
+    group (the child plus anything it spawned) with a single call, which is
+    what makes cleanup reliable when the target spawns its own children.
+    """
+    try:
+        os.setpgid(0, 0)
+    except OSError:
+        # Already a group leader, or the platform lacks setpgid.  Not fatal:
+        # we fall back to signalling the child pid directly.
+        pass
+
+
+def kill_tree(process: Any, sig: int) -> None:
+    """Send ``sig`` to the child's process group, falling back to the pid."""
+    pid = process.pid
+    if pid is None:  # pragma: no cover - defensive
+        return
+    try:
+        os.killpg(pid, sig)
+    except OSError:
+        try:
+            os.kill(pid, sig)
+        except OSError:
+            pass

interruptible/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = None

interruptible/_windows.py

@@ -0,0 +1,186 @@
+"""Windows-specific helpers built on ctypes (no third-party dependencies).
+
+Two problems must be solved on Windows:
+
+1. Ctrl+C must reach the child.  A child started by ``multiprocessing`` on
+   Windows is created without ``CREATE_NEW_PROCESS_GROUP``, so it shares the
+   parent's console process group.  A console Ctrl+C is therefore delivered by
+   Windows to the child *directly*, at the same moment the parent sees it, and
+   the child raises ``KeyboardInterrupt`` as a normal program would.  No
+   explicit forwarding is needed on the normal path; ``send_ctrl_event``
+   exists only for a child deliberately started in its own group, and
+   ``forward`` does not call it.
+
+2. When the child ignores the signal (the entire reason this package exists), we
+   must terminate the *whole process tree*.  ``Process.kill`` only kills the
+   direct child; grandchildren survive.  We attach the child to a Windows Job
+   Object with ``JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE``, so the tree dies with the
+   job.
+
+Everything here is imported unconditionally, so it must work (as inert stubs)
+on non-Windows platforms.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from ctypes import wintypes
+from typing import Any
+
+__all__ = [
+    'create_job',
+    'assign_process_to_job',
+    'close_job',
+    'configure_child',
+    'kill_tree',
+    'send_ctrl_event',
+    'IS_WINDOWS',
+]
+IS_WINDOWS = sys.platform == 'win32'
+
+# Access rights used by OpenProcess.
+PROCESS_SET_QUOTA = 0x0100
+PROCESS_TERMINATE = 0x0001
+PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+
+JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
+JobObjectExtendedLimitInformation = 9
+CTRL_C_EVENT = 0
+CTRL_BREAK_EVENT = 1
+if IS_WINDOWS:  # pragma: no cover - Windows only
+    _kernel32 = ctypes.WinDLL('kernel32', use_last_error=True)
+
+    class _IO_COUNTERS(ctypes.Structure):
+        _fields_ = [
+            ('ReadOperationCount', ctypes.c_ulonglong),
+            ('WriteOperationCount', ctypes.c_ulonglong),
+            ('OtherOperationCount', ctypes.c_ulonglong),
+            ('ReadTransferCount', ctypes.c_ulonglong),
+            ('WriteTransferCount', ctypes.c_ulonglong),
+            ('OtherTransferCount', ctypes.c_ulonglong),
+        ]
+
+    class _JOBOBJECT_BASIC_LIMIT_INFORMATION(ctypes.Structure):
+        _fields_ = [
+            ('PerProcessUserTimeLimit', wintypes.LARGE_INTEGER),
+            ('PerJobUserTimeLimit', wintypes.LARGE_INTEGER),
+            ('LimitFlags', wintypes.DWORD),
+            ('MinimumWorkingSetSize', ctypes.c_size_t),
+            ('MaximumWorkingSetSize', ctypes.c_size_t),
+            ('ActiveProcessLimit', wintypes.DWORD),
+            ('Affinity', ctypes.c_size_t),
+            ('PriorityClass', wintypes.DWORD),
+            ('SchedulingClass', wintypes.DWORD),
+        ]
+
+    class _JOBOBJECT_EXTENDED_LIMIT_INFORMATION(ctypes.Structure):
+        _fields_ = [
+            ('BasicLimitInformation', _JOBOBJECT_BASIC_LIMIT_INFORMATION),
+            ('IoInfo', _IO_COUNTERS),
+            ('ProcessMemoryLimit', ctypes.c_size_t),
+            ('JobMemoryLimit', ctypes.c_size_t),
+            ('PeakProcessMemoryUsed', ctypes.c_size_t),
+            ('PeakJobMemoryUsed', ctypes.c_size_t),
+        ]
+
+    _kernel32.CreateJobObjectW.restype = wintypes.HANDLE
+    _kernel32.CreateJobObjectW.argtypes = [wintypes.LPVOID, wintypes.LPCWSTR]
+    _kernel32.SetInformationJobObject.restype = wintypes.BOOL
+    _kernel32.SetInformationJobObject.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_int,
+        wintypes.LPVOID,
+        wintypes.DWORD,
+    ]
+    _kernel32.OpenProcess.restype = wintypes.HANDLE
+    _kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    _kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
+    _kernel32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
+    _kernel32.TerminateJobObject.restype = wintypes.BOOL
+    _kernel32.TerminateJobObject.argtypes = [wintypes.HANDLE, wintypes.UINT]
+    _kernel32.CloseHandle.restype = wintypes.BOOL
+    _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    _kernel32.GenerateConsoleCtrlEvent.restype = wintypes.BOOL
+    _kernel32.GenerateConsoleCtrlEvent.argtypes = [wintypes.DWORD, wintypes.DWORD]
+
+
+def create_job() -> int | None:
+    """Create a kill-on-close job object; return its handle, or ``None``."""
+    if not IS_WINDOWS:  # pragma: no cover
+        return None
+    handle = _kernel32.CreateJobObjectW(None, None)
+    if not handle:
+        return None
+    info = _JOBOBJECT_EXTENDED_LIMIT_INFORMATION()
+    info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+    ok = _kernel32.SetInformationJobObject(
+        handle,
+        JobObjectExtendedLimitInformation,
+        ctypes.byref(info),
+        ctypes.sizeof(info),
+    )
+    if not ok:
+        _kernel32.CloseHandle(handle)
+        return None
+    return handle
+
+
+def assign_process_to_job(job: int | None, pid: int) -> bool:
+    """Attach the process (and thus its future children) to ``job``."""
+    if not IS_WINDOWS or job is None:  # pragma: no cover
+        return False
+    access = PROCESS_SET_QUOTA | PROCESS_TERMINATE | PROCESS_QUERY_LIMITED_INFORMATION
+    process_handle = _kernel32.OpenProcess(access, False, pid)
+    if not process_handle:
+        return False
+    try:
+        return bool(_kernel32.AssignProcessToJobObject(job, process_handle))
+    finally:
+        _kernel32.CloseHandle(process_handle)
+
+
+def close_job(job: int | None) -> None:
+    """Close the job handle, which kills any surviving processes in it."""
+    if not IS_WINDOWS or job is None:  # pragma: no cover
+        return
+    _kernel32.CloseHandle(job)
+
+
+def send_ctrl_event(process_group_id: int, sig: int) -> bool:
+    """Send a console control event to a process group.
+
+    ``GenerateConsoleCtrlEvent`` addresses a process *group* id, and it only
+    succeeds when the caller and the target group share a console.  Returns
+    ``True`` when the event was delivered.
+
+    Only meaningful for a group created with ``CREATE_NEW_PROCESS_GROUP``, whose
+    group id is the pid of the process that created it.  ``multiprocessing``
+    does not create such a group on Windows, so this is not used for the normal
+    path -- the console delivers Ctrl+C to the whole group on its own.
+    """
+    if not IS_WINDOWS:  # pragma: no cover
+        return False
+    event = CTRL_C_EVENT if sig == 2 else CTRL_BREAK_EVENT
+    return bool(_kernel32.GenerateConsoleCtrlEvent(event, process_group_id))
+
+
+def configure_child() -> None:
+    """No-op on Windows; console/group handling is done by the parent."""
+    return
+
+
+def kill_tree(process: Any, sig: int) -> None:
+    """Force-terminate the child tree.
+
+    Used only after the child has ignored the graceful signal for
+    ``kill_timeout`` seconds.  The job object is closed by the caller, which
+    kills the whole tree; this additionally kills the direct child so a failure
+    to create/assign the job still cleans up.
+    """
+    if not IS_WINDOWS:  # pragma: no cover
+        return
+    try:
+        process.kill()
+    except Exception:
+        pass

interruptible/core.py

@@ -0,0 +1,331 @@
+"""Core implementation of the transparent Ctrl+C guarantee.
+
+Design principle: *the module should be invisible*.  A program wrapped with
+``interruptible.run`` must behave, from the outside, exactly like a program
+without it -- same exit codes, same output, same signal semantics -- with the
+single addition that Ctrl+C is honoured *promptly* even when the target is stuck
+inside a native extension that never returns to the bytecode evaluator.
+
+How that is achieved:
+
+* The target runs in a child process.  The parent does almost nothing except
+  wait, so it is never blocked inside a native call and always reacts to signals
+  immediately.
+* On SIGINT/SIGTERM the parent forwards the *same* signal to the child.  A
+  well-behaved program (including plain CPython) turns SIGINT into
+  ``KeyboardInterrupt`` and unwinds normally -- indistinguishable from no
+  wrapper at all.
+* If the child does not exit within ``kill_timeout`` -- the case this package
+  exists for -- the parent escalates to SIGKILL (POSIX, killing the whole
+  process group) or job-object termination (Windows, killing the whole tree).
+* The reported exit code follows the shell convention ``128 + signum`` for
+  signal-induced death, matching what the user would have seen without the
+  wrapper.
+"""
+
+from __future__ import annotations
+
+import multiprocessing
+import os
+import signal
+import sys
+import time
+from collections.abc import Callable
+from typing import Any
+
+from . import _child
+
+if sys.platform == 'win32':  # pragma: no cover - platform dispatch
+    from . import _windows as _platform
+else:
+    from . import _posix as _platform
+
+__all__ = ['run', 'interruptible']
+#: Set in the child environment to detect that a run is already inside a
+#: child, so nested ``run`` calls execute inline rather than spawning.
+CHILD_ENV_VAR = 'INTERRUPTIBLE_CHILD'
+#: Exit code reported when the ``timeout`` argument expires.
+TIMEOUT_EXIT_CODE = 127
+#: Default number of seconds to wait for the child to exit gracefully before
+#: escalating to a forced kill.
+DEFAULT_KILL_TIMEOUT = 5.0
+#: How often the parent wakes to check for pending signals or deadline expiry.
+#: Small enough to feel instant to a human pressing Ctrl+C.
+POLL_INTERVAL = 0.05
+
+
+def run(
+    target: Callable[..., int | None],
+    *args: Any,
+    timeout: float | None = None,
+    kill_timeout: float = DEFAULT_KILL_TIMEOUT,
+    passthrough_signals: tuple[int, ...] = (signal.SIGINT, signal.SIGTERM),
+    inherit_environ: bool = True,
+    **kwargs: Any,
+) -> int:
+    """Run ``target(*args, **kwargs)`` with guaranteed interruptibility.
+
+    Args:
+        target: The function to run, typically a program's ``main``.
+        *args: Positional arguments forwarded to ``target``.
+        timeout: Maximum runtime in seconds, or ``None`` for unlimited.  On
+            expiry the child is signalled and ``127`` is returned.
+        kill_timeout: Seconds to wait after forwarding a signal before forcing
+            the child (and its process tree) to die.
+        passthrough_signals: Signals that, when received by the parent, are
+            forwarded to the child (and escalated if ignored).
+        inherit_environ: Whether the child inherits the parent's environment.
+        **kwargs: Keyword arguments forwarded to ``target``.
+
+    Returns:
+        The child's exit code.  Signal-induced deaths are reported as
+        ``128 + signum`` (SIGINT -> 130, SIGTERM -> 143), matching shell and
+        CPython conventions.  A timeout returns ``127``.
+
+    Nested calls (i.e. ``run`` executed inside a child) run ``target`` inline.
+
+    Note:
+        On platforms whose start method is ``spawn`` -- Windows, and macOS since
+        Python 3.8 -- ``target`` must be **picklable**, which in practice means
+        a module-level function.  A nested function, lambda, closure, or bound
+        method defined inside another function cannot be sent to the child and
+        raises ``AttributeError: Can't pickle local object``.  Pass a
+        module-level function instead::
+
+            def main():
+                ...
+
+            if __name__ == '__main__':
+                sys.exit(interruptible.run(main))
+
+    """
+    if os.environ.get(CHILD_ENV_VAR):
+        # Already inside a child process; do not nest.  Run the target inline
+        # and return its exit code, exactly as CPython would from a plain
+        # ``main()`` call.
+        return _child.run_inline(target, args, kwargs)
+
+    # Use the platform's default start method.  Windows and macOS (since 3.8)
+    # use ``spawn``, which requires the target to be picklable -- see the
+    # docstring on ``run``.  Forcing ``fork`` on POSIX was rejected: it is
+    # unsafe in a process with threads, it makes behaviour differ between
+    # platforms, and it hides this requirement from anyone developing on Linux.
+    ctx = multiprocessing.get_context()
+    process = ctx.Process(
+        target=_child.child_main,
+        args=(target, args, kwargs, inherit_environ),
+        daemon=False,
+    )
+    job = None
+    if sys.platform == 'win32':  # pragma: no cover - Windows only
+        job = windows_job()
+
+    process.start()
+    if job is not None:  # pragma: no cover - Windows only
+        windows_assign(job, process.pid)
+
+    try:
+        return wait(process, timeout, kill_timeout, passthrough_signals, job)
+    finally:
+        # Never leave a zombie or a live grandchild behind.
+        cleanup(process, job)
+
+
+def wait(
+    process: Any,
+    timeout: float | None,
+    kill_timeout: float,
+    passthrough_signals: tuple[int, ...],
+    job: Any,
+) -> int:
+    """Wait for the child, forwarding signals, with timeout and escalation."""
+    state: dict[str, Any] = {'pending_signal': None}
+
+    def handler(signum: int, _frame: Any) -> None:
+        state['pending_signal'] = signum
+
+    installed: list[tuple[int, Any]] = []
+    for sig in passthrough_signals:
+        try:
+            previous = signal.signal(sig, handler)
+        except (OSError, ValueError):
+            # Signals that cannot be installed in this context (e.g. SIGTERM is
+            # fine, but a non-main thread or an unsupported signum is not).
+            continue
+        installed.append((sig, previous))
+
+    try:
+        # Wait for the child.  Poll in short slices so that a signal arriving
+        # mid-wait is noticed promptly rather than only when a large timeout
+        # expires.  ``deadline`` is None for an unlimited wait.
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            if join(process, POLL_INTERVAL):
+                return process.exitcode & 0xFF
+            if state['pending_signal'] is not None:
+                break
+            if deadline is not None and time.monotonic() >= deadline:
+                break
+
+        pending = state['pending_signal']
+        if pending is None:
+            # Timed out with no signal: treat as a timeout.
+            escalate(process, signal.SIGTERM, kill_timeout, job)
+            return TIMEOUT_EXIT_CODE
+
+        # A signal arrived: forward it, then wait for a graceful exit.
+        forward(process, pending, job)
+        if join(process, kill_timeout):
+            return signal_exit_code(process, pending)
+
+        # The child ignored the forwarded signal -- force it.
+        force_kill(process, job)
+        join(process, kill_timeout)
+        return signal_exit_code(process, pending)
+    finally:
+        for sig, previous in installed:
+            try:
+                signal.signal(sig, previous)
+            except (OSError, ValueError):  # pragma: no cover - defensive
+                pass
+
+
+def join(process: Any, timeout: float | None) -> bool:
+    """Join the child, returning ``True`` if it exited."""
+    process.join(timeout)
+    return not process.is_alive()
+
+
+def forward(process: Any, signum: int, job: Any) -> None:
+    """React to ``signum`` by making the child stop.
+
+    On Windows a child spawned by ``multiprocessing`` is created in the
+    parent's console process group, so a console Ctrl+C is delivered to the
+    child *by the console itself*, at the same moment the parent sees it.
+    Forwarding is therefore unnecessary for the common case and harmful when
+    attempted incorrectly: ``GenerateConsoleCtrlEvent`` takes a process *group*
+    id, not a pid, and an invalid id makes the call fail.
+
+    So the child is given the chance to handle the interrupt on its own, which
+    is what a well-behaved program does (raising ``KeyboardInterrupt``).  If it
+    is still alive when the caller's ``kill_timeout`` expires, the caller
+    force-kills the process tree.
+
+    The one case needing an explicit event is a child that is *not* in our
+    console group, which is what ``GenerateConsoleCtrlEvent`` is for; it is
+    attempted with the child's process group id, and a failure simply leaves
+    the escalation path to clean up.
+    """
+    if sys.platform == 'win32':  # pragma: no cover - Windows only
+        # Nothing to forward: see the docstring above.  The child has already
+        # been signalled by the console if it shares our console group, and the
+        # caller escalates if it is still alive after ``kill_timeout``.
+        return
+
+    _platform.kill_tree(process, signum)
+
+
+def escalate(process: Any, signum: int, kill_timeout: float, job: Any) -> None:
+    """Forward ``signum`` and force-kill if the child lingers."""
+    forward(process, signum, job)
+    if not join(process, kill_timeout):
+        force_kill(process, job)
+        join(process, kill_timeout)
+
+
+def force_kill(process: Any, job: Any) -> None:
+    """Unconditionally terminate the child and its descendants."""
+    if sys.platform == 'win32':  # pragma: no cover - Windows only
+        windows_close_job(job)
+        _platform.kill_tree(process, signal.SIGTERM)
+        return
+    _platform.kill_tree(process, signal.SIGKILL)
+
+
+def signal_exit_code(process: Any, signum: int) -> int:
+    """Return the exit code to report after a signal-triggered shutdown.
+
+    Transparency means reporting what a plain program would have reported: the
+    signal *the user sent* (so Ctrl+C always yields 130), regardless of which
+    signal happened to actually kill the child during cleanup.
+    """
+    return 128 + int(signum)
+
+
+def cleanup(process: Any, job: Any) -> None:
+    """Ensure no child or grandchild survives this call."""
+    if process.is_alive():  # pragma: no cover - defensive
+        force_kill(process, job)
+        join(process, DEFAULT_KILL_TIMEOUT)
+    if sys.platform == 'win32':  # pragma: no cover - Windows only
+        windows_close_job(job)
+
+
+def interruptible(
+    *dargs: Any,
+    timeout: float | None = None,
+    kill_timeout: float = DEFAULT_KILL_TIMEOUT,
+    passthrough_signals: tuple[int, ...] = (signal.SIGINT, signal.SIGTERM),
+    inherit_environ: bool = True,
+    **dkwargs: Any,
+) -> Callable[..., Any]:
+    """Decorator form of :func:`run`.
+
+    Can be used bare (::
+
+        @interruptible
+        def main(): ...
+
+    ) or with configuration::
+
+        @interruptible(timeout=60)
+        def main(): ...
+
+    The decorated function returns the child's exit code as an ``int``.
+    """
+
+    def decorate(func: Callable[..., Any]) -> Callable[..., Any]:
+        def wrapper(*args: Any, **kwargs: Any) -> int:
+            return run(
+                func,
+                *args,
+                timeout=timeout,
+                kill_timeout=kill_timeout,
+                passthrough_signals=passthrough_signals,
+                inherit_environ=inherit_environ,
+                **kwargs,
+            )
+
+        wrapper.__wrapped__ = func  # type: ignore[attr-defined]
+        wrapper.__name__ = getattr(func, '__name__', 'wrapper')
+        wrapper.__doc__ = getattr(func, '__doc__', None)
+        wrapper.__module__ = getattr(func, '__module__', wrapper.__module__)
+        return wrapper
+
+    if len(dargs) == 1 and callable(dargs[0]) and not dkwargs:
+        # Used bare: @interruptible
+        return decorate(dargs[0])
+    return decorate
+
+
+# Imported here rather than at module import time so that a missing/broken
+# ctypes binding cannot break the package on Windows until it is actually used.
+
+
+def windows_job() -> Any:  # pragma: no cover - Windows only
+    from . import _windows
+
+    return _windows.create_job()
+
+
+def windows_assign(job: Any, pid: int | None) -> None:  # pragma: no cover
+    from . import _windows
+
+    if pid is not None:
+        _windows.assign_process_to_job(job, pid)
+
+
+def windows_close_job(job: Any) -> None:  # pragma: no cover - Windows only
+    from . import _windows
+
+    _windows.close_job(job)

interruptible-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+interruptible/__init__.py,sha256=IONX1mMHo5ghuoeTdERIkd6b-PTkDSRWncbewvSQ4d0,1009
+interruptible/_child.py,sha256=Tl5YAdKiOBKKQsCDySDIerMAUl53IBIan42nH2wZc1U,4501
+interruptible/_posix.py,sha256=NLcbdMCPFAfDEGy1ONwIQEqnpRHjmqJfkhdKUxtNCyM,1127
+interruptible/_version.py,sha256=JAAyU3al4wmBf3BF-Umm1J_GrCIT-yS_yWEGHqKRVHc,520
+interruptible/_windows.py,sha256=0TBy8kZQvzcOjdA6PS1Y4_OItIWre0kWiY6oWfij3jY,7092
+interruptible/core.py,sha256=uqG2PPHEXmgAs8zWk9TaTMtiNcW_BU6j_fqv506AwxA,12573
+interruptible-1.0.0.dist-info/licenses/LICENSE,sha256=7KeTyrmHpDRxetbz5o2eMV6Ss4rcf2A9mG_UqTgZbf0,1070
+interruptible-1.0.0.dist-info/METADATA,sha256=eowfPcoO3BfazrskKVUPUxMtAUUvFtUt0KkhoOvQ15A,7446
+interruptible-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+interruptible-1.0.0.dist-info/top_level.txt,sha256=rNthht8IykZLVulnlj_RWLcf4BSvoi2EsE5sKYZXlEA,14
+interruptible-1.0.0.dist-info/RECORD,,

interruptible-1.0.0.dist-info/WHEEL

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

interruptible-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+interruptible