python-dmon 0.3.0__tar.gz → 0.3.1__tar.gz

{python_dmon-0.3.0 → python_dmon-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-dmon
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -37,7 +37,7 @@ It is a Python-based and more powerful successor to the [handy-backend shell scr
 - 🖥️ **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.
+- 🪵 **Logging & log rotation:** Keep active log files manageable, with optional archive retention limits.
 
 ![dmon-demo-gif](https://github.com/user-attachments/assets/9bae2f46-5ef4-4784-aced-18d573204efc)
 
@@ -126,6 +126,11 @@ dmon exec app
 
 You can specify multiple tasks at once, e.g.: `dmon start app1 app2 app3`, except for `dmon exec` which only accepts one task.
 
+Multi-task `start` is best-effort: dmon attempts every requested task and leaves
+successful tasks running if another task cannot start. The command returns a
+non-zero status and prints a summary naming the failed tasks. This is useful for
+independent background services and does not provide atomic stack semantics.
+
 Or use `--all` to operate on all tasks:
 
 ```sh
@@ -145,12 +150,12 @@ dmon status
 dmon exec
 ```
 
-You can use `--config` to specify a custom config file or the directory containing it:
+You can use `-c` / `--config` to specify a custom config file or the directory containing it:
 
 ```sh
 dmon start --config /path/to/dmon.yaml app  # YAML
 dmon start --config /path/to/pyproject.toml app  # or TOML
-dmon start --config /path/to/dir app  # dir with `dmon.y(a)ml` or `pyproject.toml`
+dmon start -c /path/to/dir app  # shorter, dir with `dmon.y(a)ml` or `pyproject.toml`
 ```
 
 And yes, you can use `dmon` to run in a nested manner:
@@ -172,6 +177,9 @@ tasks:
 # Run a command with arguments in the background
 dmon run --name myserver python -u server.py
 
+# Optionally use -- to make the child-command boundary explicit
+dmon run --name timer -- python -c 'import time; time.sleep(30)'
+
 # Run a shell command in the background
 dmon run --shell echo "Hello World"
 
@@ -194,6 +202,16 @@ dmon list
 
 A task can be a **string**, **list**, or **dictionary**.
 
+When rotation is enabled, dmon keeps timestamped archives such as
+`app.log.20260807-142106`. Both task and runner logs use this cross-platform
+format; a same-second collision adds `.1`, `.2`, and so on. Archives are never
+deleted by default. Set a backup count explicitly to enable retention cleanup.
+`log_path` contains task output; `rotate_log_path` contains diagnostics from the
+dmon process that captures and rotates that output. They are independent log
+streams and use independent retention settings.
+The size limit is checked at line boundaries, so a single long line may exceed
+the configured limit.
+
 Here is a more complete example with default values:
 
 ```yaml
@@ -208,8 +226,10 @@ tasks:
     log_path: "logs/<task>.log" # path to log file
     log_rotate: false  # enable log rotation
     log_max_size: 5  # max log file size before rotation in MB
+    # log_backup_count: 10  # optional; omit to retain all task log archives
     rotate_log_path: "logs/<task>.rotate.log"  # path to rotation log
     rotate_log_max_size: 5  # max rotation log file size in MB
+    # rotate_log_backup_count: 10  # optional; omit to retain all runner log archives
     meta_path: ".dmon/<task>.meta.json"  # path to meta file
 default_task: your_task_name  # the default task name
 ```
@@ -227,6 +247,8 @@ another_task = "cd subdir && ls && bash start.sh"
 default_task = "your_task_name"
 ```
 
+All paths can be absolute or relative to the **config file location**.
+
 
 ## Under the Hood
 
@@ -234,6 +256,10 @@ Each task is associated with a meta file (e.g. `.dmon/<task>.meta.json`) stored
 The file contains details such as the command, PID, log path, and more.
 **Do not** modify or delete these files manually.
 
+`dmon status` returns a non-zero status if a recorded task has exited. Starting
+that task again removes its stale metadata automatically. `dmon stop` terminates
+the complete process tree and also cleans stale metadata left by an exited task.
+
 
 ## License
 

{python_dmon-0.3.0 → python_dmon-0.3.1}/README.md

@@ -19,7 +19,7 @@ It is a Python-based and more powerful successor to the [handy-backend shell scr
 - 🖥️ **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.
+- 🪵 **Logging & log rotation:** Keep active log files manageable, with optional archive retention limits.
 
 ![dmon-demo-gif](https://github.com/user-attachments/assets/9bae2f46-5ef4-4784-aced-18d573204efc)
 
@@ -108,6 +108,11 @@ dmon exec app
 
 You can specify multiple tasks at once, e.g.: `dmon start app1 app2 app3`, except for `dmon exec` which only accepts one task.
 
+Multi-task `start` is best-effort: dmon attempts every requested task and leaves
+successful tasks running if another task cannot start. The command returns a
+non-zero status and prints a summary naming the failed tasks. This is useful for
+independent background services and does not provide atomic stack semantics.
+
 Or use `--all` to operate on all tasks:
 
 ```sh
@@ -127,12 +132,12 @@ dmon status
 dmon exec
 ```
 
-You can use `--config` to specify a custom config file or the directory containing it:
+You can use `-c` / `--config` to specify a custom config file or the directory containing it:
 
 ```sh
 dmon start --config /path/to/dmon.yaml app  # YAML
 dmon start --config /path/to/pyproject.toml app  # or TOML
-dmon start --config /path/to/dir app  # dir with `dmon.y(a)ml` or `pyproject.toml`
+dmon start -c /path/to/dir app  # shorter, dir with `dmon.y(a)ml` or `pyproject.toml`
 ```
 
 And yes, you can use `dmon` to run in a nested manner:
@@ -154,6 +159,9 @@ tasks:
 # Run a command with arguments in the background
 dmon run --name myserver python -u server.py
 
+# Optionally use -- to make the child-command boundary explicit
+dmon run --name timer -- python -c 'import time; time.sleep(30)'
+
 # Run a shell command in the background
 dmon run --shell echo "Hello World"
 
@@ -176,6 +184,16 @@ dmon list
 
 A task can be a **string**, **list**, or **dictionary**.
 
+When rotation is enabled, dmon keeps timestamped archives such as
+`app.log.20260807-142106`. Both task and runner logs use this cross-platform
+format; a same-second collision adds `.1`, `.2`, and so on. Archives are never
+deleted by default. Set a backup count explicitly to enable retention cleanup.
+`log_path` contains task output; `rotate_log_path` contains diagnostics from the
+dmon process that captures and rotates that output. They are independent log
+streams and use independent retention settings.
+The size limit is checked at line boundaries, so a single long line may exceed
+the configured limit.
+
 Here is a more complete example with default values:
 
 ```yaml
@@ -190,8 +208,10 @@ tasks:
     log_path: "logs/<task>.log" # path to log file
     log_rotate: false  # enable log rotation
     log_max_size: 5  # max log file size before rotation in MB
+    # log_backup_count: 10  # optional; omit to retain all task log archives
     rotate_log_path: "logs/<task>.rotate.log"  # path to rotation log
     rotate_log_max_size: 5  # max rotation log file size in MB
+    # rotate_log_backup_count: 10  # optional; omit to retain all runner log archives
     meta_path: ".dmon/<task>.meta.json"  # path to meta file
 default_task: your_task_name  # the default task name
 ```
@@ -209,6 +229,8 @@ another_task = "cd subdir && ls && bash start.sh"
 default_task = "your_task_name"
 ```
 
+All paths can be absolute or relative to the **config file location**.
+
 
 ## Under the Hood
 
@@ -216,6 +238,10 @@ Each task is associated with a meta file (e.g. `.dmon/<task>.meta.json`) stored
 The file contains details such as the command, PID, log path, and more.
 **Do not** modify or delete these files manually.
 
+`dmon status` returns a non-zero status if a recorded task has exited. Starting
+that task again removes its stale metadata automatically. `dmon stop` terminates
+the complete process tree and also cleans stale metadata left by an exited task.
+
 
 ## License
 

{python_dmon-0.3.0 → python_dmon-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-dmon"
-version = "0.3.0"
+version = "0.3.1"
 description = "A lightweight, cross-platform daemon manager that runs any command as a background process."
 readme = "README.md"
 authors = [

{python_dmon-0.3.0 → python_dmon-0.3.1}/src/dmon/cli.py

@@ -1,11 +1,11 @@
 import argparse
+import os
 from pathlib import Path
 import shlex
-import sys
 
 from colorama import just_fix_windows_console
 
-from .config import check_name_in_config, get_task_config
+from .config import check_name_in_config, get_task_config, load_config
 from .control import (
     execute,
     get_meta_paths,
@@ -193,9 +193,9 @@ def main():
     )
     sp_run.add_argument(
         "command_list",
-        metavar="command",
-        nargs=argparse.ONE_OR_MORE,
-        help="Command (with args) to run",
+        metavar="COMMAND",
+        nargs=argparse.REMAINDER,
+        help="Command and arguments to run; '--' is an optional separator",
     )
 
     sp_exec = subparsers.add_parser(
@@ -212,7 +212,9 @@ def main():
     # add custom config file option
     for sp in [sp_start, sp_stop, sp_restart, sp_status, sp_exec]:
         sp.add_argument(
+            "-c",
             "--config",
+            metavar="PATH",
             help="Path to config file or the directory containing it (default: search from current directory upwards)",
         )
 
@@ -221,7 +223,10 @@ def main():
     if args.command in ["start", "restart"]:
         sp = sp_start if args.command == "start" else sp_restart
         try:
-            tasks, task_cfgs = get_task_config(args.task, args.config, args.all)
+            tasks, task_cfgs, cfg_path = get_task_config(
+                args.task, args.config, args.all
+            )
+            os.chdir(cfg_path.parent)
         except Exception as e:
             sp.error(str(e))
 
@@ -245,19 +250,34 @@ def main():
                 task_cfg.rotate_log_path or ROTATE_LOG_PATH_TEMPLATE.format(task=task)
             )
         if args.command == "start":
-            sys.exit(start(task_cfgs))
+            sp.exit(start(task_cfgs))
         else:
-            sys.exit(restart(task_cfgs))
+            sp.exit(restart(task_cfgs))
     elif args.command == "exec":
         try:
-            _, task_cfgs = get_task_config(args.task, args.config)
+            _, task_cfgs, cfg_path = get_task_config(args.task, args.config)
+            os.chdir(cfg_path.parent)
         except Exception as e:
             sp_exec.error(str(e))
-        sys.exit(execute(task_cfgs[0]))
+        sp_exec.exit(execute(task_cfgs[0]))
     elif args.command in ["stop", "status"]:
         sp = sp_stop if args.command == "stop" else sp_status
         meta_paths = []
 
+        tasks = args.task
+        if args.task:
+            try:
+                tasks, _, cfg_path = get_task_config(args.task, args.config)
+                os.chdir(cfg_path.parent)
+            except Exception as e:
+                sp.error(str(e))
+        elif args.config:
+            try:
+                _, cfg_path = load_config(args.config)
+                os.chdir(cfg_path.parent)
+            except Exception as e:
+                sp.error(str(e))
+
         # Collect meta paths from --all
         if args.all:
             meta_paths.extend(get_meta_paths(DEFAULT_META_DIR))
@@ -267,14 +287,14 @@ def main():
             meta_paths.append(args.meta_file)
 
         # Collect meta paths from task names
-        if len(args.task) > 0:
-            tasks = args.task
+        if len(tasks) > 0:
             meta_paths.extend([META_PATH_TEMPLATE.format(task=task) for task in tasks])
 
         # If no meta paths collected, use default task
         if len(meta_paths) == 0:
             try:
-                tasks, _ = get_task_config(args.task, args.config)
+                tasks, _, cfg_path = get_task_config(args.task, args.config)
+                os.chdir(cfg_path.parent)
             except Exception as e:
                 sp.error(str(e))
             meta_paths.extend([META_PATH_TEMPLATE.format(task=task) for task in tasks])
@@ -283,13 +303,18 @@ def main():
         unique_meta_paths = sorted(set(Path(p).resolve() for p in meta_paths))
 
         if args.command == "stop":
-            sys.exit(stop(unique_meta_paths))
+            sp.exit(stop(unique_meta_paths))
         else:
-            sys.exit(status(unique_meta_paths))
+            sp.exit(status(unique_meta_paths))
     elif args.command == "list":
         dir = args.dir or DEFAULT_META_DIR
-        sys.exit(list_processes(dir, args.full))
+        sp_list.exit(list_processes(dir, args.full))
     elif args.command == "run":
+        command_list = args.command_list
+        if command_list and command_list[0] == "--":
+            command_list = command_list[1:]
+        if not command_list:
+            sp_run.error("Please provide a command to run.")
         if not args.name:
             sp_run.error("Please provide a non-empty name for the task.")
         elif check_name_in_config(args.name):
@@ -299,7 +324,7 @@ def main():
 
         task_cfg = DmonTaskConfig(
             task=args.name,
-            cmd=shlex.join(args.command_list) if args.shell else args.command_list,
+            cmd=shlex.join(command_list) if args.shell else command_list,
             cwd=args.cwd,
             meta_path=args.meta_file or META_PATH_TEMPLATE.format(task=args.name),
             log_path=args.log_file or LOG_PATH_TEMPLATE.format(task=args.name),
@@ -307,10 +332,10 @@ def main():
             rotate_log_path=args.rotate_log_path
             or ROTATE_LOG_PATH_TEMPLATE.format(task=args.name),
         )
-        sys.exit(start([task_cfg]))
+        sp_run.exit(start([task_cfg]))
     else:
         parser.print_help()
-        sys.exit(1)
+        parser.exit(1)
 
 
 if __name__ == "__main__":

{python_dmon-0.3.0 → python_dmon-0.3.1}/src/dmon/config.py

@@ -64,6 +64,10 @@ def load_config(cfg_path: Optional[str] = None):
         cfg = cfg.get("tool", {}).get("dmon", {})
     else:
         raise ValueError("Config file must be YAML (.yaml/.yml) or TOML (.toml)")
+    if cfg is None:
+        cfg = {}
+    if not isinstance(cfg, dict):
+        raise TypeError(f"Config in '{path}' must be a table")
     return cfg, path
 
 
@@ -130,6 +134,14 @@ def validate_task(task, name: str) -> DmonTaskConfig:
                 )
             ret.log_max_size = task["log_max_size"]
 
+        if "log_backup_count" in task:
+            value = task["log_backup_count"]
+            if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+                raise TypeError(
+                    f"Task '{name}' 'log_backup_count' field must be a positive integer"
+                )
+            ret.log_backup_count = value
+
         if "rotate_log_path" in task:
             if not isinstance(task["rotate_log_path"], str):
                 raise TypeError(
@@ -147,6 +159,14 @@ def validate_task(task, name: str) -> DmonTaskConfig:
                 )
             ret.rotate_log_max_size = task["rotate_log_max_size"]
 
+        if "rotate_log_backup_count" in task:
+            value = task["rotate_log_backup_count"]
+            if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+                raise TypeError(
+                    f"Task '{name}' 'rotate_log_backup_count' field must be a positive integer"
+                )
+            ret.rotate_log_backup_count = value
+
         if "meta_path" in task:
             if not isinstance(task["meta_path"], str):
                 raise TypeError(f"Task '{name}' 'meta_path' field must be a string")
@@ -160,7 +180,7 @@ def validate_task(task, name: str) -> DmonTaskConfig:
 
 def get_task_config(
     names: Union[Sequence[str], str, None], cfg_path: Optional[str], all: bool = False
-) -> Tuple[Sequence[str], List[DmonTaskConfig]]:
+) -> Tuple[Sequence[str], List[DmonTaskConfig], Path]:
     """
     Get the validated task configurations for the given task names.
     If 'all' is True, return all tasks.
@@ -195,6 +215,7 @@ def get_task_config(
             else:
                 raise ValueError(f"Multiple tasks found in {path}; please specify one.")
 
+    ret_names = []
     ret_tasks = []
     for name in names:
         name = name.lower()
@@ -202,8 +223,9 @@ def get_task_config(
             raise ValueError(f"Task '{name}' not found in {path}")
 
         task = validate_task(tasks[name], name)
+        ret_names.append(name)
         ret_tasks.append(task)
-    return names, ret_tasks
+    return ret_names, ret_tasks, path
 
 
 def check_name_in_config(name: str) -> bool:
@@ -211,7 +233,10 @@ def check_name_in_config(name: str) -> bool:
     Check if the given task name exists in the tasks.
     Return True if found, False otherwise.
     """
-    cfg, _ = load_config()
+    try:
+        cfg, _ = load_config()
+    except FileNotFoundError:
+        return False
     tasks = cfg.get("tasks", {})
 
     if not isinstance(tasks, dict):