python-dmon 0.2.0__tar.gz

python_dmon-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "python-dmon"
+version = "0.2.0"
+description = "A lightweight, cross-platform daemon manager that runs any command as a background process."
+readme = "README.md"
+authors = [
+    { name = "Atomie CHEN", email = "atomic_cwh@163.com" }
+]
+requires-python = ">=3.8"
+dependencies = [
+    "colorama>=0.4.6",
+    "psutil>=7.1.0",
+    "pyyaml>=6.0.3",
+    "termcolor>=2.4.0",
+    "tomli>=2.2.1 ; python_full_version < '3.11'",
+]
+keywords = ["python-dmon", "dmon", "daemon", "background", "detach", "process management"]
+
+[project.urls]
+"Homepage" = "https://github.com/atomiechen/python-dmon"
+"Bug Tracker" = "https://github.com/atomiechen/python-dmon/issues"
+Changelog = "https://github.com/atomiechen/python-dmon/blob/master/CHANGELOG.md"
+
+[project.scripts]
+dmon = "dmon.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dmon"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.13.3",
+]

python_dmon-0.2.0/src/dmon/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

python_dmon-0.2.0/src/dmon/cli.py

@@ -0,0 +1,232 @@
+import argparse
+import shlex
+import sys
+
+from colorama import just_fix_windows_console
+
+from .config import check_name_in_config, get_task_config
+from .control import list_processes, restart, start, stop, status
+from .constants import (
+    DEFAULT_META_DIR,
+    DEFAULT_RUN_NAME,
+    LOG_PATH_TEMPLATE,
+    META_PATH_TEMPLATE,
+    ROTATE_LOG_PATH_TEMPLATE,
+)
+from .types import DmonTaskConfig
+
+
+def main():
+    just_fix_windows_console()
+
+    parser = argparse.ArgumentParser(
+        prog="dmon",
+        description="Minimal cross-platform daemon manager",
+        # formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # start subcommand
+    sp_start = subparsers.add_parser(
+        "start",
+        help="Start a configured task as a background process",
+        description="Start a configured task as a background process",
+        # formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp_start.add_argument(
+        "name",
+        help="Configured task name (default: the only task if there's just one)",
+        nargs="?",
+    )
+    sp_start.add_argument(
+        "--meta-file",
+        help=f"Path to meta file (default: {META_PATH_TEMPLATE})",
+    )
+    sp_start.add_argument(
+        "--log-file",
+        help=f"Path to log file (default: task configured or {LOG_PATH_TEMPLATE})",
+    )
+
+    # stop subcommand
+    sp_stop = subparsers.add_parser(
+        "stop",
+        help="Stop a background process",
+        description="Stop a background process given name or meta file",
+        # formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp_stop.add_argument(
+        "name",
+        help="Configured task name (default: the only task if there's just one)",
+        nargs="?",
+    )
+    sp_stop.add_argument("--meta-file", help="Path to meta file")
+
+    # restart subcommand
+    sp_restart = subparsers.add_parser(
+        "restart",
+        help="Restart a configured task as a background process",
+        description="Restart a configured task as a background process",
+        # formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp_restart.add_argument(
+        "name",
+        help="Configured task name (default: the only task if there's just one)",
+        nargs="?",
+    )
+    sp_restart.add_argument(
+        "--meta-file",
+        help=f"Path to meta file (default: {META_PATH_TEMPLATE})",
+    )
+    sp_restart.add_argument(
+        "--log-file",
+        help=f"Path to log file (default: task configured or {LOG_PATH_TEMPLATE})",
+    )
+
+    # status subcommand
+    sp_status = subparsers.add_parser(
+        "status",
+        help="Check process status",
+        description="Check status of a background process given name or meta file",
+        # formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp_status.add_argument(
+        "name",
+        help="Configured task name (default: the only task if there's just one)",
+        nargs="?",
+    )
+    sp_status.add_argument(
+        "--meta-file",
+        help=f"Path to meta file (default: {META_PATH_TEMPLATE})",
+    )
+
+    # list subcommand
+    sp_list = subparsers.add_parser(
+        "list",
+        help="List all processes and their status",
+        description="List all processes and their status managed by dmon in the given directory",
+        # formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp_list.add_argument(
+        "dir",
+        help=f"Directory to look for meta files (default: {DEFAULT_META_DIR})",
+        nargs="?",
+    )
+    sp_list.add_argument(
+        "--full",
+        action="store_true",
+        help="Show full width without truncating column (default: False)",
+    )
+
+    # run subcommand
+    sp_run = subparsers.add_parser(
+        "run",
+        help="Run a custom task (not in config) as a background process",
+        description="Run a custom task (not in config) as a background process",
+        # formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp_run.add_argument(
+        "--name",
+        "-n",
+        default=DEFAULT_RUN_NAME,
+        help=f"Name for this task (default: {DEFAULT_RUN_NAME})",
+    )
+    sp_run.add_argument(
+        "--cwd",
+        help="Working directory to run the command in (default: current directory)",
+        default="",
+    )
+    sp_run.add_argument(
+        "--shell", action="store_true", help="Run task in shell (default: False)"
+    )
+    sp_run.add_argument(
+        "--meta-file",
+        help=f"Path to meta file (default: {META_PATH_TEMPLATE})",
+    )
+    sp_run.add_argument(
+        "--log-file",
+        help=f"Path to log file (default: {LOG_PATH_TEMPLATE})",
+    )
+    sp_run.add_argument(
+        "--log-rotate",
+        action="store_true",
+        help="Whether to rotate log file (default: False)",
+    )
+    sp_run.add_argument(
+        "--rotate-log-path",
+        help=f"Path to rotation log file (default: {ROTATE_LOG_PATH_TEMPLATE})",
+    )
+    sp_run.add_argument(
+        "command_list",
+        metavar="command",
+        nargs=argparse.ONE_OR_MORE,
+        help="Command (with args) to run",
+    )
+
+    args = parser.parse_args()
+
+    if args.command in ["start", "restart"]:
+        sp = sp_start if args.command == "start" else sp_restart
+        try:
+            name, task_cfg = get_task_config(args.name)
+        except Exception as e:
+            sp.error(str(e))
+
+        task_cfg.meta_path = (
+            args.meta_file or task_cfg.meta_path or META_PATH_TEMPLATE.format(name=name)
+        )
+        task_cfg.log_path = (
+            args.log_file or task_cfg.log_path or LOG_PATH_TEMPLATE.format(name=name)
+        )
+        task_cfg.rotate_log_path = (
+            task_cfg.rotate_log_path or ROTATE_LOG_PATH_TEMPLATE.format(name=name)
+        )
+        if args.command == "start":
+            sys.exit(start(task_cfg))
+        else:
+            sys.exit(restart(task_cfg))
+    elif args.command in ["stop", "status"]:
+        sp = sp_stop if args.command == "stop" else sp_status
+        if args.meta_file:
+            meta_path = args.meta_file
+        else:
+            if args.name:
+                name = args.name
+            else:
+                try:
+                    name, _ = get_task_config(args.name)
+                except Exception as e:
+                    sp.error(str(e))
+            meta_path = META_PATH_TEMPLATE.format(name=name)
+        if args.command == "stop":
+            sys.exit(stop(meta_path))
+        else:
+            sys.exit(status(meta_path))
+    elif args.command == "list":
+        dir = args.dir or DEFAULT_META_DIR
+        sys.exit(list_processes(dir, args.full))
+    elif args.command == "run":
+        if not args.name:
+            sp_run.error("Please provide a non-empty name for the task.")
+        elif check_name_in_config(args.name):
+            sp_run.error(
+                f"Name '{args.name}' already exists in config. Please choose another name."
+            )
+
+        task_cfg = DmonTaskConfig(
+            name=args.name,
+            cmd=shlex.join(args.command_list) if args.shell else args.command_list,
+            cwd=args.cwd,
+            meta_path=args.meta_file or META_PATH_TEMPLATE.format(name=args.name),
+            log_path=args.log_file or LOG_PATH_TEMPLATE.format(name=args.name),
+            log_rotate=args.log_rotate,
+            rotate_log_path=args.rotate_log_path
+            or ROTATE_LOG_PATH_TEMPLATE.format(name=args.name),
+        )
+        sys.exit(start(task_cfg))
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()