timeout-dead 0.1.2__tar.gz → 0.2.0__tar.gz

{timeout_dead-0.1.2 → timeout_dead-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timeout-dead
-Version: 0.1.2
+Version: 0.2.0
 Summary: Lightweight command timeout utility with zero runtime dependencies
 Author-email: Dmitry Krivoruchko <umbrella.leaf.for.work@gmail.com>
 License-Expression: Unlicense
@@ -67,6 +67,9 @@ time-d "echo hello"
 # Specify a custom timeout
 timeout-dead --sec 120 "npm run build"
 
+# Sub-second timeouts work too
+timeout-dead --sec 0.5 "potentially-hanging-tool"
+
 # Use SIGINT instead of default SIGTERM
 timeout-dead --signal INT --sec 30 "long-running-server"
 
@@ -87,7 +90,7 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   -v, --version         show version and exit
-  --sec SECONDS         timeout in seconds (default: 60)
+  --sec SECONDS         timeout in seconds (default: 60.0, accepts floats)
   --signal SIGNAL       signal to send on timeout (TERM, KILL, HUP, INT)
   --no-output           suppress normal output (stdout, stderr, header, footer)
 ```
@@ -104,12 +107,41 @@ options:
 
 ## Signal reference
 
-| Signal | Unix | Windows |
-|--------|------|---------|
+| Signal | Unix                                  | Windows                            |
+| ------ | ------------------------------------- | ---------------------------------- |
 | `TERM` | `SIGTERM` (15) — terminate gracefully | `CTRL_BREAK_EVENT` — console break |
-| `KILL` | `SIGKILL` (9) — force kill | Falls back to `TerminateProcess` |
-| `HUP`  | `SIGHUP` (1) — hangup | Falls back to `TerminateProcess` |
-| `INT`  | `SIGINT` (2) — interrupt (Ctrl+C) | `CTRL_C_EVENT` — console interrupt |
+| `KILL` | `SIGKILL` (9) — force kill            | Falls back to `TerminateProcess`   |
+| `HUP`  | `SIGHUP` (1) — hangup                 | Falls back to `TerminateProcess`   |
+| `INT`  | `SIGINT` (2) — interrupt (Ctrl+C)     | `CTRL_C_EVENT` — console interrupt |
+
+## Why `subprocess` timeout is not enough
+
+Python's built-in `subprocess` timeout only kills the direct child, not its entire process tree. If your command spawns subprocesses (`npm install`, `make`, `docker build`), children survive the parent kill.
+
+`timeout-dead` uses **process groups** to terminate everything — every subprocess, pipeline, and child.
+
+## Real-world scenarios
+
+| Scenario         | Command                   | Why it hangs                                            | `timeout-dead`                                           |
+| ---------------- | ------------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
+| Gradle build     | `./gradlew build`         | 20+ min fresh build, agent generates duplicate commands | `timeout-dead --sec 600 "./gradlew build"`               |
+| CMake build      | `cmake --build .`         | Locks waiting for dependency resolution                 | `timeout-dead --sec 180 "cmake --build ."`               |
+| Spring Boot      | `./gradlew bootRun`       | Server never exits, agent won't proceed                 | `timeout-dead --sec 30 --signal INT "./gradlew bootRun"` |
+| Docker build     | `docker build -t myapp .` | Network timeout, internal retries, no progress          | `timeout-dead --sec 600 "docker build -t myapp ."`       |
+| npm install      | `npm install`             | Corrupted cache or registry auth hang                   | `timeout-dead --sec 300 "npm install"`                   |
+| Interactive REPL | `python` / `node` / `irb` | Waits for input, agent doesn't know                     | `timeout-dead --sec 5 "python"`                          |
+
+## For AI agents
+
+If you build agents that execute shell commands, `timeout-dead` is essential infrastructure. Agents frequently generate commands that hang — waiting for input, entering infinite loops, or starting interactive programs.
+
+Instead of agents freezing indefinitely, wrap every command:
+
+```bash
+timeout-dead --sec <timeout> --signal <signal> "<command>"
+```
+
+No dependencies, no code changes. Agent always gets a response — exit code + output — and can implement retry, fallback, or user notification.
 
 ## Development
 

{timeout_dead-0.1.2 → timeout_dead-0.2.0}/README.md

@@ -41,6 +41,9 @@ time-d "echo hello"
 # Specify a custom timeout
 timeout-dead --sec 120 "npm run build"
 
+# Sub-second timeouts work too
+timeout-dead --sec 0.5 "potentially-hanging-tool"
+
 # Use SIGINT instead of default SIGTERM
 timeout-dead --signal INT --sec 30 "long-running-server"
 
@@ -61,7 +64,7 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   -v, --version         show version and exit
-  --sec SECONDS         timeout in seconds (default: 60)
+  --sec SECONDS         timeout in seconds (default: 60.0, accepts floats)
   --signal SIGNAL       signal to send on timeout (TERM, KILL, HUP, INT)
   --no-output           suppress normal output (stdout, stderr, header, footer)
 ```
@@ -78,12 +81,41 @@ options:
 
 ## Signal reference
 
-| Signal | Unix | Windows |
-|--------|------|---------|
+| Signal | Unix                                  | Windows                            |
+| ------ | ------------------------------------- | ---------------------------------- |
 | `TERM` | `SIGTERM` (15) — terminate gracefully | `CTRL_BREAK_EVENT` — console break |
-| `KILL` | `SIGKILL` (9) — force kill | Falls back to `TerminateProcess` |
-| `HUP`  | `SIGHUP` (1) — hangup | Falls back to `TerminateProcess` |
-| `INT`  | `SIGINT` (2) — interrupt (Ctrl+C) | `CTRL_C_EVENT` — console interrupt |
+| `KILL` | `SIGKILL` (9) — force kill            | Falls back to `TerminateProcess`   |
+| `HUP`  | `SIGHUP` (1) — hangup                 | Falls back to `TerminateProcess`   |
+| `INT`  | `SIGINT` (2) — interrupt (Ctrl+C)     | `CTRL_C_EVENT` — console interrupt |
+
+## Why `subprocess` timeout is not enough
+
+Python's built-in `subprocess` timeout only kills the direct child, not its entire process tree. If your command spawns subprocesses (`npm install`, `make`, `docker build`), children survive the parent kill.
+
+`timeout-dead` uses **process groups** to terminate everything — every subprocess, pipeline, and child.
+
+## Real-world scenarios
+
+| Scenario         | Command                   | Why it hangs                                            | `timeout-dead`                                           |
+| ---------------- | ------------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
+| Gradle build     | `./gradlew build`         | 20+ min fresh build, agent generates duplicate commands | `timeout-dead --sec 600 "./gradlew build"`               |
+| CMake build      | `cmake --build .`         | Locks waiting for dependency resolution                 | `timeout-dead --sec 180 "cmake --build ."`               |
+| Spring Boot      | `./gradlew bootRun`       | Server never exits, agent won't proceed                 | `timeout-dead --sec 30 --signal INT "./gradlew bootRun"` |
+| Docker build     | `docker build -t myapp .` | Network timeout, internal retries, no progress          | `timeout-dead --sec 600 "docker build -t myapp ."`       |
+| npm install      | `npm install`             | Corrupted cache or registry auth hang                   | `timeout-dead --sec 300 "npm install"`                   |
+| Interactive REPL | `python` / `node` / `irb` | Waits for input, agent doesn't know                     | `timeout-dead --sec 5 "python"`                          |
+
+## For AI agents
+
+If you build agents that execute shell commands, `timeout-dead` is essential infrastructure. Agents frequently generate commands that hang — waiting for input, entering infinite loops, or starting interactive programs.
+
+Instead of agents freezing indefinitely, wrap every command:
+
+```bash
+timeout-dead --sec <timeout> --signal <signal> "<command>"
+```
+
+No dependencies, no code changes. Agent always gets a response — exit code + output — and can implement retry, fallback, or user notification.
 
 ## Development
 

{timeout_dead-0.1.2 → timeout_dead-0.2.0}/src/timeout_dead/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.2'
-__version_tuple__ = version_tuple = (0, 1, 2)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
-__commit_id__ = commit_id = 'g92736f7f7'
+__commit_id__ = commit_id = 'gd1dae1c5b'

{timeout_dead-0.1.2 → timeout_dead-0.2.0}/src/timeout_dead/cli.py

@@ -19,13 +19,13 @@ from importlib.metadata import version as _get_version
 
 
 class _Const:
-  DEFAULT_TIMEOUT_S: int = 60
+  DEFAULT_TIMEOUT_S: float = 60.0
   GRACE_PERIOD_S: float = 1.0
-  HEADER_SEPARATOR: str = "-" * 60
+  HEADER_SEPARATOR: str = "-" * 50
 
   MSG_NO_COMMAND: str = "Error: no command specified"
   MSG_BASH_NOT_FOUND: str = "bash not found in PATH"
-  MSG_TIMEOUT: str = "Timeout exceeded {} seconds"
+  MSG_TIMEOUT: str = "Timeout exceeded {}s"
   MSG_EXEC_ERROR: str = "Execution error: {}"
 
   SIGNAL_NAMES: tuple[str, ...] = ("TERM", "KILL", "HUP", "INT")
@@ -125,7 +125,7 @@ def _terminate_process(
 
 def _kill_with_timeout(
   process: subprocess.Popen[bytes] | subprocess.Popen[str],
-  timeout: int,
+  timeout: float,
   signal_num: int = signal.SIGTERM,
 ) -> None:
   """Kill the process after timeout with two-stage logic."""
@@ -148,7 +148,7 @@ def _kill_with_timeout(
 
 def run_command(
   command_string: str,
-  timeout: int = _Const.DEFAULT_TIMEOUT_S,
+  timeout: float = _Const.DEFAULT_TIMEOUT_S,
   signal_name: str = "TERM",
   no_output: bool = False,
 ) -> int:
@@ -157,7 +157,7 @@ def run_command(
 
   Args:
     command_string (str): command to execute
-    timeout (int): timeout in seconds
+    timeout (float): timeout in seconds
     signal_name (str): signal name for graceful termination
     no_output (bool): suppress normal output
 
@@ -170,7 +170,10 @@ def run_command(
   timer: threading.Timer | None = None
 
   try:
-    creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) if _is_windows() else 0
+    creationflags = (
+      getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) if _is_windows() else 0
+    )
+
     start_new_session = not _is_windows()
 
     process = subprocess.Popen(
@@ -236,7 +239,7 @@ def parse_arguments(argv: list[str] | None = None) -> argparse.Namespace:
 
   parser.add_argument(
     "--sec",
-    type=int,
+    type=float,
     default=_Const.DEFAULT_TIMEOUT_S,
     help=f"timeout in seconds (default: {_Const.DEFAULT_TIMEOUT_S})",
     metavar="SECONDS",
@@ -271,7 +274,7 @@ def parse_arguments(argv: list[str] | None = None) -> argparse.Namespace:
 # ------------------------------------------------
 
 
-def print_header(command: str, timeout: int) -> None:
+def print_header(command: str, timeout: float) -> None:
   """Print execution header."""
 
   print(f"Running: {command}")

{timeout_dead-0.1.2 → timeout_dead-0.2.0}/tests/test_cli.py

@@ -48,7 +48,7 @@ def _run_cli(
 class TestParseArguments:
   def test_defaults(self) -> None:
     args = parse_arguments(["echo", "hello"])
-    assert args.sec == 60
+    assert args.sec == 60.0
     assert args.signal == "TERM"
     assert args.no_output is False
     assert args.command == ["echo", "hello"]
@@ -57,7 +57,25 @@ class TestParseArguments:
 
   def test_custom_timeout(self) -> None:
     args = parse_arguments(["--sec", "120", "echo", "hello"])
-    assert args.sec == 120
+    assert args.sec == 120.0
+
+  # ------------------------------------------------
+
+  def test_float_timeout(self) -> None:
+    args = parse_arguments(["--sec", "2.5", "echo", "hello"])
+    assert args.sec == 2.5
+
+  # ------------------------------------------------
+
+  def test_subsecond_timeout(self) -> None:
+    args = parse_arguments(["--sec", "0.3", "sleep", "1"])
+    assert args.sec == 0.3
+
+  # ------------------------------------------------
+
+  def test_zero_timeout(self) -> None:
+    args = parse_arguments(["--sec", "0", "echo", "hello"])
+    assert args.sec == 0.0
 
   # ------------------------------------------------
 
@@ -217,6 +235,58 @@ class TestRunCommand:
     assert rc != 0
 
 
+# MARK: Float timeout tests
+# ------------------------------------------------
+
+
+class TestFloatTimeout:
+  def test_float_parsed_correctly(self) -> None:
+    rc = run_command("echo ok", timeout=2.5)
+    assert rc == 0
+
+  # ------------------------------------------------
+
+  def test_subsecond_timeout_triggers(self) -> None:
+    rc = run_command("sleep 10", timeout=0.3)
+    assert rc != 0
+
+  # ------------------------------------------------
+
+  def test_millisecond_timeout(self) -> None:
+    start = time.monotonic()
+    rc = run_command("sleep 10", timeout=0.5)
+    elapsed = time.monotonic() - start
+    assert rc != 0
+    assert elapsed < 4.0
+
+  # ------------------------------------------------
+
+  def test_float_in_message(self, capsys: pytest.CaptureFixture[str]) -> None:
+    run_command("sleep 10", timeout=1.5)
+    captured = capsys.readouterr()
+    assert "Timeout exceeded" in captured.err
+
+  # ------------------------------------------------
+
+  def test_cli_float_arg(self) -> None:
+    result = _run_cli("--sec", "0.3", "sleep", "10")
+    assert result.returncode != 0
+    assert "Timeout exceeded" in result.stderr
+
+  # ------------------------------------------------
+
+  def test_cli_float_with_signal(self) -> None:
+    result = _run_cli("--sec", "0.5", "--signal", "KILL", "sleep", "10")
+    assert result.returncode != 0
+
+  # ------------------------------------------------
+
+  def test_cli_float_no_output(self) -> None:
+    result = _run_cli("--no-output", "--sec", "0.3", "sleep", "10")
+    assert "Timeout exceeded" in result.stderr
+    assert "Running:" not in result.stdout
+
+
 # MARK: Signal selection tests
 # ------------------------------------------------
 
@@ -460,8 +530,8 @@ class TestIntegration:
 
 class TestConstants:
   def test_default_timeout(self) -> None:
-    assert _Const.DEFAULT_TIMEOUT_S == 60
-    assert isinstance(_Const.DEFAULT_TIMEOUT_S, int)
+    assert _Const.DEFAULT_TIMEOUT_S == 60.0
+    assert isinstance(_Const.DEFAULT_TIMEOUT_S, float)
 
   # ------------------------------------------------