timeout-dead 0.1.0__py3-none-any.whl

timeout_dead/__init__.py

@@ -0,0 +1,6 @@
+"""timeout-dead — lightweight command timeout utility."""
+
+from timeout_dead.cli import main
+
+
+__all__ = ["main"]

timeout_dead/_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 = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

timeout_dead/cli.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+
+"""Легковесная утилита для запуска команд с таймаутом."""
+
+import argparse
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+import time
+
+
+# MARK: Constants
+# ------------------------------------------------
+
+
+class _Const:
+  DEFAULT_TIMEOUT_S: int = 60
+  GRACE_PERIOD_S: float = 1.0
+  HEADER_SEPARATOR: str = "-" * 60
+
+  MSG_NO_COMMAND: str = "Error: no command specified"
+  MSG_BASH_NOT_FOUND: str = "bash not found in PATH — Git Bash is required"
+  MSG_TIMEOUT: str = "Timeout exceeded {} seconds"
+  MSG_EXEC_ERROR: str = "Execution error: {}"
+
+  SIGNAL_NAMES: tuple[str, ...] = ("TERM", "KILL", "HUP", "INT")
+
+  SIGNAL_MAP: dict[str, int] = {
+    "TERM": signal.SIGTERM,
+    "KILL": getattr(signal, "SIGKILL", signal.SIGTERM),
+    "HUP": getattr(signal, "SIGHUP", signal.SIGTERM),
+    "INT": signal.SIGINT,
+  }
+
+
+# MARK: Private Helpers
+# ------------------------------------------------
+
+
+def _is_windows() -> bool:
+  return os.name == "nt"
+
+
+# ------------------------------------------------
+
+
+def _find_bash() -> str:
+  """
+  Ищет bash в PATH.
+
+  Returns:
+    str: путь к исполняемому файлу bash
+
+  Raises:
+    SystemExit: если bash не найден
+  """
+
+  bash_path = shutil.which("bash")
+
+  if bash_path is None:
+    print(f"\n{_Const.MSG_BASH_NOT_FOUND}", file=sys.stderr)
+    sys.exit(1)
+
+  return bash_path
+
+
+# MARK: Process termination
+# ------------------------------------------------
+
+
+def _terminate_process(
+  process: subprocess.Popen[bytes] | subprocess.Popen[str],
+  *,
+  force: bool = False,
+  signal_num: int = signal.SIGTERM,
+) -> None:
+  """Завершает процесс — мягко (выбранным сигналом) или жёстко."""
+
+  if process.poll() is not None:
+    return
+
+  try:
+    if _is_windows():
+      if force:
+        process.kill()
+
+      elif signal_num == signal.SIGINT:
+        process.send_signal(signal.SIGINT)
+
+      else:
+        ctrl_break = getattr(signal, "CTRL_BREAK_EVENT", signal.SIGTERM)
+        process.send_signal(ctrl_break)
+
+    else:
+      pgid = os.getpgid(process.pid)  # pyright: ignore[reportAttributeAccessIssue]
+
+      if force:
+        os.killpg(pgid, signal.SIGKILL)  # pyright: ignore[reportAttributeAccessIssue]
+
+      else:
+        os.killpg(pgid, signal_num)  # pyright: ignore[reportAttributeAccessIssue]
+
+  except (ProcessLookupError, OSError):
+    pass
+
+
+# ------------------------------------------------
+
+
+def _kill_with_timeout(
+  process: subprocess.Popen[bytes] | subprocess.Popen[str],
+  timeout: int,
+  signal_num: int = signal.SIGTERM,
+) -> None:
+  """Убивает процесс по таймауту с двухэтапной логикой."""
+
+  if process.poll() is not None:
+    return
+
+  _terminate_process(process, signal_num=signal_num)
+  time.sleep(_Const.GRACE_PERIOD_S)
+
+  if process.poll() is None:
+    _terminate_process(process, force=True)
+
+  print(f"\n{_Const.MSG_TIMEOUT.format(timeout)}", file=sys.stderr)
+
+
+# MARK: Public API
+# ------------------------------------------------
+
+
+def run_command(
+  command_string: str,
+  timeout: int = _Const.DEFAULT_TIMEOUT_S,
+  signal_name: str = "TERM",
+  no_output: bool = False,
+) -> int:
+  """
+  Запускает команду с таймаутом через bash.
+
+  Args:
+    command_string (str): команда для выполнения
+    timeout (int): таймаут в секундах
+    signal_name (str): имя сигнала для мягкого завершения
+    no_output (bool): подавлять ли обычный вывод
+
+  Returns:
+    int: код возврата процесса (-1 при ошибке запуска)
+  """
+
+  signal_num = _Const.SIGNAL_MAP.get(signal_name, signal.SIGTERM)
+  process: subprocess.Popen[bytes] | subprocess.Popen[str] | None = None
+  timer: threading.Timer | None = None
+
+  try:
+    creationflags = subprocess.CREATE_NEW_PROCESS_GROUP if _is_windows() else 0
+    start_new_session = not _is_windows()
+
+    process = subprocess.Popen(
+      [_find_bash(), "-c", command_string],
+      stdout=subprocess.PIPE,
+      stderr=subprocess.PIPE,
+      text=True,
+      creationflags=creationflags,
+      start_new_session=start_new_session,
+    )
+
+    timer = threading.Timer(
+      timeout,
+      _kill_with_timeout,
+      args=(process, timeout, signal_num),
+    )
+    timer.start()
+
+    stdout, stderr = process.communicate()
+    timer.cancel()
+
+    if not no_output:
+      if stdout:
+        print(stdout, end="")
+      if stderr:
+        print(stderr, end="", file=sys.stderr)
+
+    return process.returncode
+
+  except Exception as e:
+    if timer:
+      timer.cancel()
+    if process and process.poll() is None:
+      try:
+        _terminate_process(process, force=True)
+
+      except Exception:
+        pass
+
+    print(f"{_Const.MSG_EXEC_ERROR.format(e)}", file=sys.stderr)
+
+    return -1
+
+
+# ------------------------------------------------
+
+
+def parse_arguments(argv: list[str] | None = None) -> argparse.Namespace:
+  """Разбирает аргументы командной строки."""
+
+  parser = argparse.ArgumentParser(
+    description="Lightweight command timeout utility.",
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+  )
+
+  parser.add_argument(
+    "--sec",
+    type=int,
+    default=_Const.DEFAULT_TIMEOUT_S,
+    help=f"timeout in seconds (default: {_Const.DEFAULT_TIMEOUT_S})",
+    metavar="SECONDS",
+  )
+
+  parser.add_argument(
+    "--signal",
+    type=str.upper,
+    default="TERM",
+    choices=list(_Const.SIGNAL_NAMES),
+    help="signal to send on timeout (default: TERM)",
+    metavar="SIGNAL",
+  )
+
+  parser.add_argument(
+    "--no-output",
+    action="store_true",
+    default=False,
+    help="suppress normal output (stdout, stderr, header, footer)",
+  )
+
+  parser.add_argument(
+    "command",
+    nargs=argparse.REMAINDER,
+    help="command to execute",
+    metavar="COMMAND",
+  )
+
+  return parser.parse_args(argv)
+
+
+# ------------------------------------------------
+
+
+def print_header(command: str, timeout: int) -> None:
+  """Выводит заголовок выполнения."""
+
+  print(f"Running: {command}")
+  print(f"Timeout: {timeout} seconds")
+  print(_Const.HEADER_SEPARATOR)
+
+
+# ------------------------------------------------
+
+
+def print_footer(return_code: int) -> None:
+  """Выводит футер выполнения."""
+
+  print(_Const.HEADER_SEPARATOR)
+  print(f"Exit code: {return_code}")
+
+
+# ------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> None:
+  """Главная точка входа."""
+
+  args = parse_arguments(argv)
+
+  if not args.command:
+    print(f"{_Const.MSG_NO_COMMAND}", file=sys.stderr)
+    sys.exit(1)
+
+  command_string = " ".join(args.command)
+
+  if not args.no_output:
+    print_header(command_string, args.sec)
+
+  return_code = run_command(
+    command_string,
+    timeout=args.sec,
+    signal_name=args.signal,
+    no_output=args.no_output,
+  )
+
+  if not args.no_output:
+    print_footer(return_code)
+
+  sys.exit(return_code)
+
+
+if __name__ == "__main__":
+  main()

timeout_dead-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: timeout-dead
+Version: 0.1.0
+Summary: Lightweight command timeout utility with zero runtime dependencies
+Author-email: Dmitry Krivoruchko <umbrella.leaf.for.work@gmail.com>
+License-Expression: Unlicense
+Project-URL: Repository, https://github.com/UmbrellaLeaf5/timeout-dead
+Project-URL: Issues, https://github.com/UmbrellaLeaf5/timeout-dead/issues
+Keywords: timeout,cli,command,process,kill,signal,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Topic :: System :: System Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pyright>=1.1.409; extra == "dev"
+Dynamic: license-file
+
+# timeout-dead
+
+[![PyPI version](https://img.shields.io/pypi/v/timeout-dead)](https://pypi.org/project/timeout-dead/)
+[![Python](https://img.shields.io/badge/Python-3.10+-yellow?logo=python)](https://python.org)
+[![License](https://img.shields.io/badge/license-Unlicense-blue.svg)](LICENSE)
+[![Tests](https://github.com/UmbrellaLeaf5/timeout-dead/actions/workflows/tests.yml/badge.svg)](https://github.com/UmbrellaLeaf5/timeout-dead/actions/workflows/tests.yml)
+[![Ruff](https://github.com/UmbrellaLeaf5/timeout-dead/actions/workflows/ruff.yml/badge.svg)](https://github.com/UmbrellaLeaf5/timeout-dead/actions/workflows/ruff.yml)
+[![Pyright](https://github.com/UmbrellaLeaf5/timeout-dead/actions/workflows/pyright.yml/badge.svg)](https://github.com/UmbrellaLeaf5/timeout-dead/actions/workflows/pyright.yml)
+
+<img align="right" height="256" src="icon.png"/>
+
+**Lightweight command timeout utility with zero runtime dependencies.**
+Runs any shell command with a configurable time limit and termination signal.
+If the command exceeds the timeout, `timeout-dead` sends the chosen signal,
+waits a 1-second grace period, then force-kills the process.
+Works on Linux, macOS, and Windows (Git Bash / WSL).
+
+## Installation
+
+```bash
+pip install timeout-dead
+```
+
+Or via uv:
+
+```bash
+uv tool install timeout-dead
+```
+
+Requires Python 3.10 or later. Zero runtime dependencies — pure Python standard library.
+
+## Quick start
+
+```bash
+# Run a command with default 60s timeout
+timeout-dead "python -c 'print(42)'"
+
+# Short alias also works
+time-d "echo hello"
+
+# Specify a custom timeout
+timeout-dead --sec 120 "npm run build"
+
+# Use SIGINT instead of default SIGTERM
+timeout-dead --signal INT --sec 30 "long-running-server"
+
+# Run silently — suppress all normal output
+timeout-dead --no-output "curl -s https://example.com"
+```
+
+## Usage
+
+```
+usage: timeout-dead [-h] [--sec SECONDS] [--signal SIGNAL] [--no-output] COMMAND ...
+
+Lightweight command timeout utility.
+
+positional arguments:
+  COMMAND               command to execute
+
+options:
+  -h, --help            show this help message and exit
+  --sec SECONDS         timeout in seconds (default: 60)
+  --signal SIGNAL       signal to send on timeout (TERM, KILL, HUP, INT)
+  --no-output           suppress normal output (stdout, stderr, header, footer)
+```
+
+## How it works
+
+1. `timeout-dead` starts the command in a new process group (Unix) / console group (Windows).
+2. A background timer waits for the specified timeout.
+3. If the command finishes in time, its output and exit code are forwarded.
+4. If the timeout expires:
+   - The chosen signal is sent to the process group.
+   - After 1 second, if the process is still running, `SIGKILL` (Unix) or `process.kill()` (Windows) is sent.
+   - A `Timeout exceeded` message is printed to stderr.
+
+## Signal reference
+
+| 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 |
+
+## Development
+
+```bash
+git clone https://github.com/UmbrellaLeaf5/timeout-dead
+cd timeout-dead
+uv sync --extra dev
+uv run pytest tests/ -v
+uv run ruff check src/timeout_dead/ tests/
+uv run ruff format --check .
+uv run pyright src/timeout_dead/
+```
+
+## License
+
+[Unlicense](LICENSE) — public domain.
+
+<a href="https://www.flaticon.com/free-icons/timeout" title="timeout icons">Timeout icons created by Those Icons - Flaticon</a>

timeout_dead-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+timeout_dead/__init__.py,sha256=dmORBMW91c-w2ZmNOTNP1scTT7Sj_I4Uiirv4UswMGM,116
+timeout_dead/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+timeout_dead/cli.py,sha256=4Ox74_htWGjD9S6c2cbfdlV7LS8nAzQcP44Fyz6lsZs,7180
+timeout_dead-0.1.0.dist-info/licenses/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
+timeout_dead-0.1.0.dist-info/METADATA,sha256=O-IYUmoKvSiEVNvrJVC8TrgTLNQas7qfoBbmXx5A8uY,4705
+timeout_dead-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+timeout_dead-0.1.0.dist-info/entry_points.txt,sha256=pYdLZaqgi6T6EE6woFSUVY2_tlVeNmZL-ciU5zm0aYg,123
+timeout_dead-0.1.0.dist-info/top_level.txt,sha256=86YL6ohLAQPyhX9lDRLqOVrhBozouE8w97PgfFRMaSc,13
+timeout_dead-0.1.0.dist-info/RECORD,,

timeout_dead-0.1.0.dist-info/WHEEL

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

timeout_dead-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+time-d = timeout_dead.cli:main
+timeout-dead = timeout_dead.cli:main
+timeout_dead = timeout_dead.cli:main

timeout_dead-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

timeout_dead-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+timeout_dead