python-dmon 0.2.0__py3-none-any.whl

dmon/runner.py

@@ -0,0 +1,188 @@
+import argparse
+from datetime import datetime
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+import signal
+import subprocess
+import sys
+
+
+logger = logging.getLogger("dmon.runner")
+
+
+class FixedSizeRotatingFileHandler(RotatingFileHandler):
+    """
+    Custom RotatingFileHandler that renames the old log file with a timestamp suffix
+    instead of deleting it.
+    """
+
+    def __init__(self, filename, maxBytes):
+        super().__init__(filename, maxBytes=maxBytes)
+
+    def doRollover(self):
+        if self.stream:
+            self.stream.close()
+        # Create timestamped filename for the rollover logs
+        current_time = datetime.now().strftime(".%Y%m%d-%H:%M:%S")
+        self.rotate(self.baseFilename, self.baseFilename + current_time)
+        self.stream = self._open()
+
+
+def get_file_dir(file_path):
+    return os.path.dirname(file_path)
+
+
+def make_dir(dir):
+    dir = os.path.abspath(dir)
+    if not os.path.exists(dir):
+        os.makedirs(dir, exist_ok=True)
+
+
+def make_file_dir(file_path):
+    par_dir = get_file_dir(file_path)
+    make_dir(par_dir)
+
+
+def need_rotate(log_path, max_log_size):
+    return os.path.getsize(log_path) >= max_log_size and max_log_size > 0
+
+
+def rotate_log(log_path):
+    current_time = datetime.now().strftime(".%Y%m%d-%H%M%S")
+    new_name = log_path + current_time
+    logger.info(f"Rotating {log_path} to {new_name}")
+    if os.path.exists(new_name):
+        logger.warning(f"{new_name} already exists, skip renaming")
+    else:
+        make_file_dir(new_name)
+        os.rename(log_path, new_name)
+
+
+def loop_to_log(bin_fd, log_path, max_log_size):
+    while True:  # loop once whenever need to rotate
+        with open(log_path, "ab") as log_file:
+            while True:
+                try:
+                    # read byte by byte in binary mode to avoid decoding
+                    # error caused by utf8 character truncation
+                    byte = bin_fd.read(1)
+                    if byte:
+                        log_file.write(byte)
+                        log_file.flush()  # immediately write the content to the file
+                        # When a newline character is read, check if
+                        # rotation is needed; if so, break the loop
+                        if byte == b"\n" and need_rotate(log_path, max_log_size):
+                            break
+                    else:
+                        logger.info("Read EOF, now closing...")
+                        return
+                except Exception as e:
+                    logger.exception(f"Exception in while loop: {e}")
+        rotate_log(log_path)  # rotate log file
+
+
+def catch_exception(func):
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.exception(f"Exception in {func.__name__}: {e}")
+
+    return wrapper
+
+
+@catch_exception
+def main(
+    cmd,
+    log_path,
+    max_log_size,
+    rotate_log_path,
+    max_rotate_log_size,
+):
+    # Configure logging
+    rh = None
+    if rotate_log_path:
+        rh = FixedSizeRotatingFileHandler(rotate_log_path, maxBytes=max_rotate_log_size)
+    logging.basicConfig(
+        format="%(asctime)s.%(msecs)03d - %(process)d - %(levelname)s - %(message)s",
+        level=logging.INFO,
+        datefmt="%Y-%m-%d %H:%M:%S",
+        handlers=[rh] if rh else None,
+    )
+
+    logger.info(
+        f"Prepare for rotating logs: {log_path=} {max_log_size=} {rotate_log_path=} {max_rotate_log_size=}"
+    )
+
+    shell = isinstance(cmd, str)
+    # Start the child process with stdout/stderr redirected to the log
+    # env will be inherited from parent process
+    # cwd will be inherited from parent process
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        shell=shell,
+        text=False,  # binary mode
+        bufsize=0,  # unbuffered
+    )
+
+    # register signal handler to terminate the child process
+    def signal_handler(signum, frame):
+        logger.info(f"Received signal {signum}, forwarding to child process...")
+        # proc.terminate()
+        proc.send_signal(signum)
+        logger.info("Waiting for child process to exit...")
+        proc.wait()
+        logger.info("Child process exited, all done.")
+        sys.exit(0)
+
+    # Set up signal handlers
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+    logger.info(f"Started process {proc.pid} with command: {cmd} (shell={shell})")
+
+    make_file_dir(log_path)
+    loop_to_log(proc.stdout, log_path, max_log_size)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Dmon task runner with log rotation utility",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "command",
+        nargs=argparse.ONE_OR_MORE,
+        help="Command with arguments to run",
+    )
+    parser.add_argument("--shell", action="store_true", help="Run command in shell")
+    parser.add_argument("--log-path", help="Log file path", required=True)
+    parser.add_argument(
+        "--max-log-size",
+        help="Max log file size (MB); 0 for no rotation",
+        type=int,
+        default=5,
+    )
+    parser.add_argument(
+        "--rotate-log-path",
+        help="Path of the log output of this rotation process; if not provided, output to stdout",
+        default=None,
+    )
+    parser.add_argument(
+        "--max-rotate-log-size",
+        help="Max file size (MB) for this rotation log; 0 for no rotation",
+        type=int,
+        default=5,
+    )
+    args = parser.parse_args()
+    main(
+        " ".join(args.command) if args.shell else args.command,
+        args.log_path,
+        args.max_log_size * 1024 * 1024,
+        args.rotate_log_path,
+        args.max_rotate_log_size * 1024 * 1024,
+    )
+    logger.info("Process finished.")

dmon/types.py

@@ -0,0 +1,63 @@
+from dataclasses import asdict, dataclass, field
+import json
+from os import PathLike
+from pathlib import Path
+import sys
+from typing import Dict, List, Optional, Union
+
+
+if sys.version_info >= (3, 9):
+    PathType = Union[str, PathLike[str]]
+else:
+    PathType = Union[str, PathLike]
+
+
+CmdType = Union[str, List[str]]
+
+
+@dataclass
+class DmonTaskConfig:
+    name: str = ""
+    """Name of the task"""
+    cmd: CmdType = ""
+    """Command to run, either a string (for shell) or a list of strings (for exec)"""
+    cwd: str = ""
+    """Working directory to run the command in"""
+    env: Dict[str, str] = field(default_factory=dict)
+    """Environment variables to set for the command"""
+    override_env: bool = False
+    """Whether to override the entire environment with the provided env"""
+    log_path: str = ""
+    """Path to log file"""
+    log_rotate: bool = False
+    """Whether to rotate log file"""
+    log_max_size: int = 5
+    """Size in MB to rotate log file"""
+    rotate_log_path: str = ""
+    """Path to rotation log file"""
+    rotate_log_max_size: int = 5
+    """Size in MB to rotation log file"""
+    meta_path: str = ""
+    """Path to meta file"""
+
+
+@dataclass
+class DmonMeta(DmonTaskConfig):
+    pid: int = -1
+    shell: bool = False
+    popen_kwargs: Dict = field(default_factory=dict)
+    create_time: float = -1
+    create_time_human: str = "N/A"
+
+    def dump(self, path: PathType):
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(asdict(self), f, indent=2, ensure_ascii=False)
+
+    @staticmethod
+    def load(path: PathType) -> Optional["DmonMeta"]:
+        p = Path(path)
+        if p.exists():
+            with p.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+                return DmonMeta(**data)
+        return None

dmon/utils.py

@@ -0,0 +1,32 @@
+import re
+from typing import Literal
+
+
+ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def len_ansi(s: str) -> int:
+    return len(ANSI_RE.sub("", s))
+
+
+def pad_ansi(
+    s: str, width: int, align: Literal["<", ">", "^"] = "<", fill: str = " "
+) -> str:
+    """Pad a string with ANSI escape codes to a given width."""
+    real_len = len_ansi(s)
+    if real_len == width:
+        return s
+    if real_len > width:
+        return s[: width - 3] + "..."  # truncate and add ellipsis
+
+    pad_len = width - real_len
+    if align == "<":
+        return s + fill * pad_len
+    elif align == ">":
+        return fill * pad_len + s
+    elif align == "^":
+        left = pad_len // 2
+        right = pad_len - left
+        return fill * left + s + fill * right
+    else:
+        raise ValueError(f"Invalid align: {align}")

python_dmon-0.2.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.3
+Name: python-dmon
+Version: 0.2.0
+Summary: A lightweight, cross-platform daemon manager that runs any command as a background process.
+Keywords: python-dmon,dmon,daemon,background,detach,process management
+Author: Atomie CHEN
+Author-email: Atomie CHEN <atomic_cwh@163.com>
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: psutil>=7.1.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: termcolor>=2.4.0
+Requires-Dist: tomli>=2.2.1 ; python_full_version < '3.11'
+Requires-Python: >=3.8
+Project-URL: Bug Tracker, https://github.com/atomiechen/python-dmon/issues
+Project-URL: Changelog, https://github.com/atomiechen/python-dmon/blob/master/CHANGELOG.md
+Project-URL: Homepage, https://github.com/atomiechen/python-dmon
+Description-Content-Type: text/markdown
+
+# python-dmon
+
+
+[![GitHub](https://img.shields.io/badge/github-python--dmon-blue?logo=github)](https://github.com/atomiechen/python-dmon)
+[![PyPI](https://img.shields.io/pypi/v/python--dmon?logo=pypi&logoColor=white)](https://pypi.org/project/python-dmon/)
+
+
+A lightweight, cross-platform daemon manager that runs any command — called a *task* — as a background process. 
+It also supports logging and log rotation out of the box. 
+**No Docker or extra dependencies required**. 
+
+Shipped as the CLI tool `dmon`.
+It is a Python-based and more powerful successor to the [handy-backend shell scripts](https://github.com/atomiechen/handy-backend).
+
+
+## Features
+
+- 🖥️ **Cross-platform:** Works on Linux, macOS, and Windows.
+- ⚡ **Lightweight:** Pure Python, no Docker or external dependencies needed.
+- 🧩 **Flexible tasks:** Tasks can be configured in `pyproject.toml` or `dmon.yaml`; or run ad-hoc commands directly.
+- 🪵 **Logging & log rotation:** Automatically manage log files to prevent uncontrolled growth.
+
+
+## Installation
+
+```sh
+pip install python-dmon
+```
+
+To get the latest features, install from source:
+
+```sh
+pip install git+https://github.com/atomiechen/python-dmon.git
+```
+
+## Getting Started
+
+### Prepare Configuration
+
+Create a `dmon.yaml` file:
+
+```yaml
+tasks:
+  app: ["python", "-u", "server.py"]
+```
+
+Or add to your `pyproject.toml`:
+
+```toml
+[tool.dmon.tasks]
+app = ["python", "-u", "server.py"]
+```
+
+Commands can be a single string (run in shell), or list of strings (exec form).
+See [Example Task Configuration](#example-task-configuration) for more configuration options.
+
+
+### Run tasks
+
+Run a configured task by its name:
+
+```sh
+# Start a task
+dmon start app
+
+# Stop a running task
+dmon stop app
+
+# Check task status
+dmon status app
+```
+
+If only one task is defined in the config file, you can omit the task name:
+
+```sh
+dmon start
+dmon stop
+dmon status
+```
+
+
+### Run an ad-hoc command
+
+```sh
+# Run a command with arguments in the background
+dmon run --name myserver python -u server.py
+
+# Run a shell command in the background
+dmon run --shell echo "Hello World"
+
+# Run a shell script in the background
+dmon run --cwd /path/to/script bash myscript.sh
+```
+
+> [!NOTE]
+> If no name is provided, `dmon` automatically assigns a fixed task name `default_run` to prevent duplicate runs.
+
+
+### List all running tasks
+
+```sh
+dmon list
+```
+
+
+## Example Task Configuration
+
+A task can be a **string**, **list**, or **dictionary**.
+
+Here is a more complete example with default values:
+
+```yaml
+tasks:
+  your_task_name:
+    # Command to run; can be a string (run in shell) or list of strings (exec form)
+    cmd: ["python", "server.py"]  # required
+    cwd: "/path/to/working/dir"  # (default: current dir)
+    env:  # (default: inherit from parent process)
+      PYTHONUNBUFFERED: "1"
+    override_env: false  # override parent env and only use env defined here
+    log_path: "logs/<name>.log" # path to log file
+    log_rotate: false  # enable log rotation
+    log_max_size: 5  # max log file size before rotation in MB
+    rotate_log_path: "logs/<name>.rotate.log"  # path to rotation log
+    rotate_log_max_size: 5  # max rotation log file size in MB
+    meta_path: ".dmon/<name>.meta.json"  # path to meta file
+```
+
+## Under the Hood
+
+Each task is associated with a meta file (e.g. `.dmon/<name>.meta.json`) stored in the current working directory.
+The file contains details such as the command, PID, log path, and more.
+**Do not** modify or delete these files manually.
+
+
+## License
+
+[python-dmon](https://github.com/atomiechen/python-dmon) © 2025 by [Atomie CHEN](https://github.com/atomiechen) is licensed under the [MIT License](https://github.com/atomiechen/python-dmon/blob/main/LICENSE).

python_dmon-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+dmon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dmon/__main__.py,sha256=wu5N2wk8mvBgyvr2ghmQf4prezAe0_i-p123VVreyYc,62
+dmon/cli.py,sha256=IVJ5jCHkaLGTQjMmWCuJbhnt4MWEOaNWQajC-mm3LUQ,7599
+dmon/config.py,sha256=COzwN0Ms8q32pV6dqsZU59RFE2GQmqyAmfygDotc4CA,6610
+dmon/constants.py,sha256=y5S532iTeklaR28BFbvpdOHFj1udbEJ-reD1mTCcC6E,351
+dmon/control.py,sha256=0_NrrOA0sUM_lFHNyKGAmQsBbJhXwXfj8kxOp2S8Ni8,16311
+dmon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dmon/runner.py,sha256=zEW7TnHMfIw6g3UTjOTUcLFKueXpqSmNDP3ZOptXQKs,5892
+dmon/types.py,sha256=ZtTAK-cfs2MgUFRwDH61zeIU2B4dHZDbx1644tYI1h4,1795
+dmon/utils.py,sha256=zVQC9YNhMQu4hrAp9k2ds2egnbWZZv7S5w8i2oVIPJg,808
+python_dmon-0.2.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+python_dmon-0.2.0.dist-info/entry_points.txt,sha256=rad5ugz4K_IyNXS_IrFPu0tS-UXlBCSJRhJv-OWd_yk,45
+python_dmon-0.2.0.dist-info/METADATA,sha256=s1AoObf2NB_kK_Era10wpm0X6OwH-J0UVeAS8Dg6pcs,4498
+python_dmon-0.2.0.dist-info/RECORD,,

python_dmon-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

python_dmon-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dmon = dmon.__main__:main
+