python-dmon 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

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__":

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):

dmon/control.py

@@ -35,11 +35,24 @@ def ensure_log_dir(log_path: Path):
 
 def start(cfgs: Sequence[DmonTaskConfig]):
     ret = 0
+    failed = []
     for idx, cfg in enumerate(cfgs):
-        # non-zero if any start() fails
-        ret |= start_single(cfg)
+        result = start_single(cfg)
+        ret |= result
+        if result:
+            failed.append(cfg.task)
         if idx < len(cfgs) - 1:
             print("---", file=sys.stderr)  # print a blank line between tasks
+    if failed and len(cfgs) > 1:
+        succeeded = len(cfgs) - len(failed)
+        failed_tasks = ", ".join(
+            colored(f"'{task}'", color="cyan", attrs=["bold"]) for task in failed
+        )
+        print(
+            f"\nStarted {succeeded} task(s); failed to start: {failed_tasks}. "
+            "Multi-task start is best-effort, so successful tasks were left running.",
+            file=sys.stderr,
+        )
     return ret
 
 
@@ -49,47 +62,76 @@ def start_single(cfg: DmonTaskConfig):
     cwd = Path(cfg.cwd).resolve()
 
     try:
-        ret_meta = DmonMeta.load(meta_path)
-    except Exception:
-        ret_meta = None
-    if ret_meta:
+        existing_meta = DmonMeta.load(meta_path)
+    except (OSError, ValueError, TypeError) as error:
+        print(
+            colored(
+                f"Start failed: cannot read metadata {meta_path}: {error}",
+                color="red",
+                attrs=["bold"],
+            ),
+            file=sys.stderr,
+        )
+        return 1
+    if existing_meta and existing_meta.state == "starting":
+        print(
+            colored(
+                f"Start failed: task '{cfg.task}' is already being started by another dmon process.",
+                color="red",
+                attrs=["bold"],
+            ),
+            file=sys.stderr,
+        )
+        print(
+            "If the earlier start was interrupted, run 'dmon stop' to remove its reservation.",
+            file=sys.stderr,
+        )
+        return 1
+    if existing_meta and check_running(existing_meta.pid, existing_meta.create_time):
         print(
             f"{colored('Start failed: meta file already exists', color='red', attrs=['bold'])}",
             file=sys.stderr,
         )
-        print_status(ret_meta)
+        print_status(existing_meta)
         print(
             "\nRun 'dmon status' / 'dmon list' to check, or 'dmon stop' to stop it.",
             file=sys.stderr,
         )
         return 1
+    if existing_meta:
+        print(
+            colored(
+                f"Removing stale metadata for exited task '{cfg.task}'.",
+                color="yellow",
+            ),
+            file=sys.stderr,
+        )
+        meta_path.unlink(missing_ok=True)
 
     ensure_meta_dir(meta_path)
     ensure_log_dir(log_path)
 
-    env = None  # default behavior of Popen
-    if cfg.override_env:
-        env = cfg.env
-    elif cfg.env:
-        env = {**os.environ, **cfg.env}
+    env = task_environment(cfg)
 
     shell = isinstance(cfg.cmd, str)
 
     # Platform-specific parameters to run the process in background detached from parent
     kwargs = {}
+    command = cfg.cmd
     if ON_WINDOWS:
         # DETACHED_PROCESS = 0x00000008
         CREATE_NO_WINDOW = 0x08000000
         kwargs["creationflags"] = CREATE_NO_WINDOW
-        if isinstance(cfg.cmd, list) and len(cfg.cmd) > 0:
+        if isinstance(command, list) and len(command) > 0:
             # On Windows, use full path for the executable when shell=False
-            cfg.cmd[0] = shutil.which(cfg.cmd[0]) or cfg.cmd[0]
+            command = [shutil.which(command[0]) or command[0], *command[1:]]
     else:
         # Make the child process independent of the parent process in Unix-like systems
         kwargs["start_new_session"] = True
 
     meta = DmonMeta(
         task=cfg.task,
+        state="starting",
         meta_path=str(meta_path),
         log_path=str(log_path),
         log_rotate=cfg.log_rotate,
@@ -101,63 +143,97 @@ def start_single(cfg: DmonTaskConfig):
         popen_kwargs=kwargs,
     )
 
-    if cfg.log_rotate:
-        rotate_log_path = Path(cfg.rotate_log_path).resolve()
-
-        meta.rotate_log_path = str(rotate_log_path)
-        meta.log_max_size = cfg.log_max_size
-        meta.rotate_log_max_size = cfg.rotate_log_max_size
-
-        ensure_log_dir(rotate_log_path)
-
-        # use runner to start user process and handle log rotation
-        if isinstance(cfg.cmd, str):
-            # when cmd is str, we need to split it into list for subprocess
-            cmd = shlex.split(cfg.cmd)
-        else:
-            cmd = cfg.cmd
-        args = [
-            sys.executable,
-            "-m",
-            "dmon.runner",
-            "--log-path",
-            str(log_path),
-            "--max-log-size",
-            str(cfg.log_max_size),
-            "--rotate-log-path",
-            str(rotate_log_path),
-            "--max-rotate-log-size",
-            str(cfg.rotate_log_max_size),
-        ]
-        if shell:
-            args.append("--shell")
-        args.append("--")
-        args.extend(cmd)
-        proc = subprocess.Popen(
-            args,
-            cwd=cwd,
-            env=env,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.STDOUT,
-            **kwargs,
+    try:
+        meta.dump(meta_path, exclusive=True)
+    except FileExistsError:
+        print(
+            colored(
+                f"Start failed: another dmon process is starting task '{cfg.task}'.",
+                color="red",
+                attrs=["bold"],
+            ),
+            file=sys.stderr,
         )
-    else:
-        # Open the log file (append binary mode)
-        with open(log_path, "ab", buffering=0) as lof:
-            # Start the child process with stdout/stderr redirected to the log
+        return 1
+
+    try:
+        if cfg.log_rotate:
+            rotate_log_path = Path(cfg.rotate_log_path).resolve()
+
+            meta.rotate_log_path = str(rotate_log_path)
+            meta.log_max_size = cfg.log_max_size
+            meta.log_backup_count = cfg.log_backup_count
+            meta.rotate_log_max_size = cfg.rotate_log_max_size
+            meta.rotate_log_backup_count = cfg.rotate_log_backup_count
+
+            ensure_log_dir(rotate_log_path)
+
+            # use runner to start user process and handle log rotation
+            if isinstance(command, str):
+                # when cmd is str, we need to split it into list for subprocess
+                cmd = shlex.split(command)
+            else:
+                cmd = command
+            args = [
+                sys.executable,
+                "-m",
+                "dmon.runner",
+                "--log-path",
+                str(log_path),
+                "--max-log-size",
+                str(cfg.log_max_size),
+                "--rotate-log-path",
+                str(rotate_log_path),
+                "--max-rotate-log-size",
+                str(cfg.rotate_log_max_size),
+            ]
+            if cfg.log_backup_count is not None:
+                args.extend(["--log-backup-count", str(cfg.log_backup_count)])
+            if cfg.rotate_log_backup_count is not None:
+                args.extend(
+                    ["--rotate-log-backup-count", str(cfg.rotate_log_backup_count)]
+                )
+            if shell:
+                args.append("--shell")
+            args.append("--")
+            args.extend(cmd)
             proc = subprocess.Popen(
-                cfg.cmd,
-                stdout=lof,
-                stderr=subprocess.STDOUT,
+                args,
                 cwd=cwd,
                 env=env,
-                shell=shell,
-                text=False,  # binary mode
-                bufsize=0,  # unbuffered
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.STDOUT,
                 **kwargs,
             )
+        else:
+            # Open the log file (append binary mode)
+            with open(log_path, "ab", buffering=0) as lof:
+                # Start the child process with stdout/stderr redirected to the log
+                proc = subprocess.Popen(
+                    command,
+                    stdout=lof,
+                    stderr=subprocess.STDOUT,
+                    cwd=cwd,
+                    env=env,
+                    shell=shell,
+                    text=False,  # binary mode
+                    bufsize=0,  # unbuffered
+                    **kwargs,
+                )
+    except OSError as error:
+        meta_path.unlink(missing_ok=True)
+        print(
+            colored(
+                f"Start failed for task '{cfg.task}': {error}",
+                color="red",
+                attrs=["bold"],
+            ),
+            file=sys.stderr,
+        )
+        return 1
 
     meta.pid = proc.pid
+    meta.state = "running"
     try:
         p = psutil.Process(proc.pid)
         create_time = p.create_time()
@@ -166,16 +242,42 @@ def start_single(cfg: DmonTaskConfig):
         )
         meta.create_time = create_time
         meta.create_time_human = create_time_human
-    except psutil.NoSuchProcess:
+    except (psutil.NoSuchProcess, ValueError):
         # process already exited?
         pass
 
-    meta.dump(meta_path)
+    try:
+        meta.dump(meta_path)
+    except OSError as error:
+        try:
+            managed_process = psutil.Process(proc.pid)
+        except psutil.NoSuchProcess:
+            pass
+        else:
+            terminate_process(managed_process, timeout=2.0)
+        meta_path.unlink(missing_ok=True)
+        print(
+            colored(
+                f"Start failed: cannot save metadata for task '{cfg.task}': {error}",
+                color="red",
+                attrs=["bold"],
+            ),
+            file=sys.stderr,
+        )
+        return 1
 
     print_status(meta)
     return 0
 
 
+def task_environment(cfg: DmonTaskConfig):
+    if cfg.override_env:
+        return cfg.env
+    if cfg.env:
+        return {**os.environ, **cfg.env}
+    return None
+
+
 def stop(meta_paths: Sequence[PathType], timeout=5.0):
     ret = 0
     for idx, meta_path in enumerate(meta_paths):
@@ -191,7 +293,18 @@ def stop_single(
     timeout=5.0,
 ):
     meta_path = Path(meta_path).resolve()
-    meta = DmonMeta.load(meta_path)
+    try:
+        meta = DmonMeta.load(meta_path)
+    except (OSError, ValueError, TypeError) as error:
+        print(
+            colored(
+                f"Stop failed: cannot read metadata {meta_path}: {error}",
+                color="red",
+                attrs=["bold"],
+            ),
+            file=sys.stderr,
+        )
+        return 1
     if meta is None:
         print(
             colored(
@@ -207,7 +320,7 @@ def stop_single(
     pid = meta.pid
     try:
         proc = psutil.Process(pid)
-    except psutil.NoSuchProcess:
+    except (psutil.NoSuchProcess, ValueError):
         print(
             colored(
                 f"Process {pid} not found (already exited); removing stale meta file",
@@ -218,7 +331,7 @@ def stop_single(
         )
         print_status(meta)
         meta_path.unlink(missing_ok=True)
-        return 1
+        return 0
 
     # check if it's the same process by comparing create_time
     if not check_same_process(proc, meta.create_time):
@@ -232,135 +345,132 @@ def stop_single(
         )
         print_status(meta)
         meta_path.unlink(missing_ok=True)
-        return 1
+        return 0
+    if not process_is_alive(proc):
+        print(
+            colored(
+                f"Process {pid} already exited; removing stale meta file",
+                color="yellow",
+                attrs=["bold"],
+            ),
+            file=sys.stderr,
+        )
+        print_status(meta)
+        meta_path.unlink(missing_ok=True)
+        return 0
 
-    if ON_WINDOWS:
-        ret = terminate_win(proc, timeout)
-    else:
-        ret = terminate_posix(proc, timeout)
+    ret = terminate_process(proc, timeout)
     print_status(meta)
     if ret == 0:
         meta_path.unlink(missing_ok=True)
     return ret
 
 
-def terminate_posix(proc: psutil.Process, timeout):
-    # send SIGTERM first for graceful shutdown (if platform supports)
-    proc.terminate()
+def terminate_process(proc: psutil.Process, timeout: float) -> int:
+    if not ON_WINDOWS:
+        try:
+            process_group = os.getpgid(proc.pid)
+        except (ProcessLookupError, psutil.NoSuchProcess):
+            return 0
+        if process_group == proc.pid:
+            return terminate_posix_group(proc, process_group, timeout)
+    return terminate_process_tree(proc, timeout)
+
 
-    # wait for the process to exit or timeout
+def terminate_posix_group(
+    proc: psutil.Process, process_group: int, timeout: float
+) -> int:
     try:
-        ret = proc.wait(timeout)
-        print(
-            colored(
-                f"Process {proc.pid} exited with code {ret}; removing meta file",
-                color="green",
-                attrs=["bold"],
-            ),
-            file=sys.stderr,
-        )
-    except psutil.TimeoutExpired:
+        os.killpg(process_group, signal.SIGTERM)
+    except ProcessLookupError:
+        return 0
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline and process_group_exists(process_group):
+        try:
+            proc.wait(timeout=0)
+        except (psutil.NoSuchProcess, psutil.TimeoutExpired):
+            pass
+        time.sleep(0.05)
+    if process_group_exists(process_group):
         print(
             colored(
-                f"Process {proc.pid} did not exit in time; shutting down child processes",
+                f"Process group {process_group} did not exit in time; killing it",
                 color="yellow",
                 attrs=["bold"],
             ),
             file=sys.stderr,
         )
-
-        # first shut down child processes (leaf nodes first)
-        for child in reversed(proc.children(recursive=True)):
-            try:
-                child.terminate()
-                child.wait(timeout=2)
-            except Exception:
-                try:
-                    child.kill()
-                except Exception:
-                    pass
-        # then shut down the parent process
         try:
-            # check if process is already exited
-            ret = proc.wait(timeout=2)
-            print(
-                colored(
-                    f"Process {proc.pid} exited with code {ret} after terminating children; removing meta file",
-                    color="green",
-                    attrs=["bold"],
-                ),
-                file=sys.stderr,
-            )
-        except psutil.TimeoutExpired:
-            print(
-                colored(
-                    f"Process {proc.pid} did not exit in time after terminating children; killing it",
-                    color="yellow",
-                    attrs=["bold"],
-                ),
-                file=sys.stderr,
-            )
-            try:
-                proc.kill()
-                print(
-                    colored(
-                        f"Killed process {proc.pid}; removing meta file",
-                        color="green",
-                        attrs=["bold"],
-                    ),
-                    file=sys.stderr,
-                )
-            except Exception as e:
-                print(
-                    colored(
-                        f"Failed to kill process {proc.pid}: {e}",
-                        color="red",
-                        attrs=["bold"],
-                    ),
-                    file=sys.stderr,
-                )
+            os.killpg(process_group, signal.SIGKILL)
+        except ProcessLookupError:
+            return 0
+        except PermissionError:
+            if process_group_exists(process_group):
                 return 1
+    try:
+        proc.wait(timeout=1)
+    except (psutil.NoSuchProcess, psutil.TimeoutExpired):
+        pass
+    print(
+        colored(
+            f"Process group {process_group} stopped; removing meta file",
+            color="green",
+            attrs=["bold"],
+        ),
+        file=sys.stderr,
+    )
     return 0
 
 
-def terminate_win(proc: psutil.Process, timeout):
-    # On Windows, we need to stop child processes first
-    children = proc.children(recursive=True)
-    # reverse to kill leaf nodes first
-    for child in reversed(children):
+def process_group_exists(process_group: int) -> bool:
+    for process in psutil.process_iter(["pid", "status"]):
+        if process.info["status"] == psutil.STATUS_ZOMBIE:
+            continue
         try:
-            child.kill()
-            child.wait(timeout=2)
-        except Exception:
-            pass
+            if os.getpgid(process.info["pid"]) == process_group:
+                return True
+        except (OSError, psutil.NoSuchProcess):
+            continue
+    return False
+
+
+def terminate_process_tree(proc: psutil.Process, timeout: float) -> int:
     try:
-        ret = proc.wait(timeout=timeout)
-        print(
-            colored(
-                f"Process {proc.pid} exited with code {ret}; removing meta file",
-                color="green",
-                attrs=["bold"],
-            ),
-            file=sys.stderr,
-        )
-    except psutil.TimeoutExpired:
-        print(
-            colored(
-                f"Process {proc.pid} did not exit in time after killing children; killing it",
-                color="yellow",
-                attrs=["bold"],
-            ),
-            file=sys.stderr,
-        )
-        proc.kill()
+        processes = [*proc.children(recursive=True), proc]
+    except psutil.NoSuchProcess:
+        return 0
+    for process in reversed(processes):
+        try:
+            process.terminate()
+        except psutil.NoSuchProcess:
+            pass
+    _, alive = psutil.wait_procs(processes, timeout=timeout)
+    for process in alive:
+        try:
+            process.kill()
+        except psutil.NoSuchProcess:
+            pass
+    _, alive = psutil.wait_procs(alive, timeout=1)
+    if alive:
         print(
             colored(
-                f"Killed process {proc.pid}; removing meta file",
-                color="green",
+                "Failed to stop process tree: "
+                + ", ".join(str(process.pid) for process in alive),
+                color="red",
                 attrs=["bold"],
             ),
             file=sys.stderr,
         )
+        return 1
+    print(
+        colored(
+            f"Process tree {proc.pid} stopped; removing meta file",
+            color="green",
+            attrs=["bold"],
+        ),
+        file=sys.stderr,
+    )
     return 0
 
 
@@ -379,7 +489,21 @@ def status(meta_paths: Sequence[PathType]):
     metas = []
     for idx, meta_path in enumerate(meta_paths):
         meta_path = Path(meta_path).resolve()
-        meta = DmonMeta.load(meta_path)
+        try:
+            meta = DmonMeta.load(meta_path)
+        except (OSError, ValueError, TypeError) as error:
+            print(
+                colored(
+                    f"Status failed: cannot read metadata {meta_path}: {error}",
+                    color="red",
+                    attrs=["bold"],
+                ),
+                file=sys.stderr,
+            )
+            ret |= 1
+            if idx < len(meta_paths) - 1:
+                print("---", file=sys.stderr)
+            continue
         if meta is None:
             print(
                 colored(
@@ -394,6 +518,8 @@ def status(meta_paths: Sequence[PathType]):
         else:
             print_status(meta)
             metas.append(meta)
+            if not check_running(meta.pid, meta.create_time):
+                ret |= 1
         if idx < len(meta_paths) - 1:
             print("---", file=sys.stderr)
     if metas:
@@ -408,6 +534,13 @@ def check_same_process(proc: psutil.Process, create_time: float) -> bool:
     return abs(proc.create_time() - create_time) < 1e-3
 
 
+def process_is_alive(proc: psutil.Process) -> bool:
+    try:
+        return proc.is_running() and proc.status() != psutil.STATUS_ZOMBIE
+    except psutil.NoSuchProcess:
+        return False
+
+
 def get_unique_process(pid: int, create_time: float):
     """
     Get the process with given PID and create_time if it is still the same process.
@@ -415,7 +548,7 @@ def get_unique_process(pid: int, create_time: float):
     if create_time >= 0:
         try:
             p = psutil.Process(pid)
-            if check_same_process(p, create_time):
+            if check_same_process(p, create_time) and process_is_alive(p):
                 return p
         except psutil.NoSuchProcess:
             pass
@@ -431,7 +564,7 @@ def check_running(pid: int, create_time: float) -> bool:
         return False
     try:
         p = psutil.Process(pid)
-        return abs(p.create_time() - create_time) < 1e-3
+        return check_same_process(p, create_time) and process_is_alive(p)
     except psutil.NoSuchProcess:
         return False
 
@@ -458,7 +591,11 @@ def print_status(meta: DmonMeta):
     if meta.log_rotate:
         rows.append(("ROTATE LOG PATH", meta.rotate_log_path))
         rows.append(("LOG MAX SIZE", f"{meta.log_max_size} MB"))
+        if meta.log_backup_count is not None:
+            rows.append(("LOG BACKUP COUNT", meta.log_backup_count))
         rows.append(("ROTATE LOG MAX SIZE", f"{meta.rotate_log_max_size} MB"))
+        if meta.rotate_log_backup_count is not None:
+            rows.append(("ROTATE LOG BACKUP COUNT", meta.rotate_log_backup_count))
 
     # calculate the max width of the keys
     key_width = max(len(key) for key, _ in rows)
@@ -564,8 +701,21 @@ def list_processes(dir: PathType, full_width: bool):
     target_dmon_dir = Path(dir).resolve()
     meta_paths = get_meta_paths(target_dmon_dir)
     metas = []
+    errors = 0
     for meta_path in meta_paths:
-        meta = DmonMeta.load(meta_path)
+        try:
+            meta = DmonMeta.load(meta_path)
+        except (OSError, ValueError, TypeError) as error:
+            print(
+                colored(
+                    f"Cannot read metadata {meta_path}: {error}",
+                    color="red",
+                    attrs=["bold"],
+                ),
+                file=sys.stderr,
+            )
+            errors += 1
+            continue
         if meta is not None:
             metas.append(meta)
     # sort by name (case-insensitive)
@@ -577,7 +727,7 @@ def list_processes(dir: PathType, full_width: bool):
         f"\nFound {n_task} task{'s' if n_task > 1 else ''} ({n_proc} process{'es' if n_proc > 1 else ''}) in {target_dmon_dir}",
         file=sys.stderr,
     )
-    return 0
+    return 1 if errors else 0
 
 
 def execute(cfg: DmonTaskConfig):
@@ -587,25 +737,13 @@ def execute(cfg: DmonTaskConfig):
     """
     cwd = Path(cfg.cwd).resolve()
 
-    env = None  # default behavior of Popen
-    if cfg.override_env:
-        env = cfg.env
-    elif cfg.env:
-        env = {**os.environ, **cfg.env}
+    env = task_environment(cfg)
 
     shell = isinstance(cfg.cmd, str)
     if ON_WINDOWS and isinstance(cfg.cmd, list) and len(cfg.cmd) > 0:
         # On Windows, use full path for the executable when shell=False
         cfg.cmd[0] = shutil.which(cfg.cmd[0]) or cfg.cmd[0]
 
-    def signal_handler(signum: int, frame) -> None:
-        if ON_WINDOWS and signum == signal.SIGINT:
-            signum = signal.SIGTERM
-        proc.send_signal(signum)
-
-    prev_handle_int = signal.signal(signal.SIGINT, signal_handler)
-    prev_handle_term = signal.signal(signal.SIGTERM, signal_handler)
-
     proc = subprocess.Popen(
         cfg.cmd,
         cwd=cwd,
@@ -614,8 +752,24 @@ def execute(cfg: DmonTaskConfig):
         bufsize=0,  # unbuffered
         close_fds=False,
     )
-    ret = proc.wait()
 
-    signal.signal(signal.SIGTERM, prev_handle_term)
-    signal.signal(signal.SIGINT, prev_handle_int)
-    return ret
+    def signal_handler(signum: int, frame) -> None:
+        # POSIX terminals deliver SIGINT to both foreground processes. Forwarding
+        # it would make the child receive Ctrl-C twice. Windows needs explicit
+        # forwarding, translated to a signal subprocess can deliver reliably.
+        if not ON_WINDOWS and signum == signal.SIGINT:
+            return
+        if ON_WINDOWS and signum == signal.SIGINT:
+            signum = signal.SIGTERM
+        try:
+            proc.send_signal(signum)
+        except ProcessLookupError:
+            pass
+
+    prev_handle_int = signal.signal(signal.SIGINT, signal_handler)
+    prev_handle_term = signal.signal(signal.SIGTERM, signal_handler)
+    try:
+        return proc.wait()
+    finally:
+        signal.signal(signal.SIGTERM, prev_handle_term)
+        signal.signal(signal.SIGINT, prev_handle_int)

dmon/runner.py

@@ -3,30 +3,63 @@ from datetime import datetime
 import logging
 from logging.handlers import RotatingFileHandler
 import os
+from pathlib import Path
+import re
 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)
+TIMESTAMP_FORMAT = "%Y%m%d-%H%M%S"
+
+
+def timestamped_backups(log_path):
+    path = Path(log_path)
+    # Include the pre-0.3.1 runner-log format so opt-in retention can also
+    # clean up legacy archives on platforms where ':' was a valid filename.
+    timestamp = r"(?:\d{8}-\d{6}|\d{8}-\d{2}:\d{2}:\d{2})"
+    pattern = re.compile(rf"^{re.escape(path.name)}\.{timestamp}(?:\.\d+)?$")
+    return [
+        candidate
+        for candidate in path.parent.iterdir()
+        if pattern.fullmatch(candidate.name)
+    ]
+
+
+def rotate_file(log_path, timestamp=None, backup_count=None):
+    path = Path(log_path)
+    timestamp = timestamp or datetime.now().strftime(TIMESTAMP_FORMAT)
+    backup = Path(f"{path}.{timestamp}")
+    counter = 1
+    while backup.exists():
+        backup = Path(f"{path}.{timestamp}.{counter}")
+        counter += 1
+
+    os.replace(path, backup)
+    if backup_count is not None:
+        backups = sorted(
+            timestamped_backups(path),
+            key=lambda item: (item.stat().st_mtime_ns, item.name),
+        )
+        for old_backup in backups[:-backup_count]:
+            old_backup.unlink()
+    return backup
+
+
+class TimestampedRotatingFileHandler(RotatingFileHandler):
+    def __init__(self, filename, maxBytes, backup_count=None):
+        super().__init__(filename, maxBytes=maxBytes, backupCount=1)
+        self.backup_count = backup_count
 
     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()
+            self.stream = None
+        if os.path.exists(self.baseFilename):
+            rotate_file(self.baseFilename, backup_count=self.backup_count)
+        if not self.delay:
+            self.stream = self._open()
 
 
 def get_file_dir(file_path):
@@ -48,18 +81,12 @@ 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 rotate_log(log_path, backup_count=None):
+    logger.info(f"Rotating {log_path}")
+    rotate_file(log_path, backup_count=backup_count)
 
 
-def loop_to_log(bin_fd, log_path, max_log_size):
+def loop_to_log(bin_fd, log_path, max_log_size, backup_count=None):
     while True:  # loop once whenever need to rotate
         with open(log_path, "ab") as log_file:
             while True:
@@ -79,7 +106,7 @@ def loop_to_log(bin_fd, log_path, max_log_size):
                         return
                 except Exception as e:
                     logger.exception(f"Exception in while loop: {e}")
-        rotate_log(log_path)  # rotate log file
+        rotate_log(log_path, backup_count)  # rotate log file
 
 
 def catch_exception(func):
@@ -97,13 +124,19 @@ def main(
     cmd,
     log_path,
     max_log_size,
+    log_backup_count,
     rotate_log_path,
     max_rotate_log_size,
+    rotate_log_backup_count,
 ):
     # Configure logging
     rh = None
     if rotate_log_path:
-        rh = FixedSizeRotatingFileHandler(rotate_log_path, maxBytes=max_rotate_log_size)
+        rh = TimestampedRotatingFileHandler(
+            rotate_log_path,
+            maxBytes=max_rotate_log_size,
+            backup_count=rotate_log_backup_count,
+        )
     logging.basicConfig(
         format="%(asctime)s.%(msecs)03d - %(process)d - %(levelname)s - %(message)s",
         level=logging.INFO,
@@ -149,7 +182,7 @@ def main(
     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)
+    loop_to_log(proc.stdout, log_path, max_log_size, log_backup_count)
 
 
 if __name__ == "__main__":
@@ -175,18 +208,32 @@ if __name__ == "__main__":
         help="Path of the log output of this rotation process; if not provided, output to stdout",
         default=None,
     )
+    parser.add_argument(
+        "--log-backup-count",
+        help="Number of task log archives to retain; omit to retain all",
+        type=int,
+        default=None,
+    )
     parser.add_argument(
         "--max-rotate-log-size",
         help="Max file size (MB) for this rotation log; 0 for no rotation",
         type=float,
         default=5,
     )
+    parser.add_argument(
+        "--rotate-log-backup-count",
+        help="Number of runner log archives to retain; omit to retain all",
+        type=int,
+        default=None,
+    )
     args = parser.parse_args()
     main(
         " ".join(args.command) if args.shell else args.command,
         args.log_path,
         int(args.max_log_size * 1024 * 1024),
+        args.log_backup_count,
         args.rotate_log_path,
         int(args.max_rotate_log_size * 1024 * 1024),
+        args.rotate_log_backup_count,
     )
     logger.info("Process finished.")

dmon/types.py

@@ -1,8 +1,10 @@
 from dataclasses import asdict, dataclass, field
 import json
+import os
 from os import PathLike
 from pathlib import Path
 import sys
+import tempfile
 from typing import Dict, List, Optional, Union
 
 
@@ -33,10 +35,14 @@ class DmonTaskConfig:
     """Whether to rotate log file"""
     log_max_size: float = 5
     """Size in MB to rotate log file"""
+    log_backup_count: Optional[int] = None
+    """Number of task log archives to retain; None keeps all archives"""
     rotate_log_path: str = ""
     """Path to rotation log file"""
     rotate_log_max_size: float = 5
     """Size in MB to rotation log file"""
+    rotate_log_backup_count: Optional[int] = None
+    """Number of runner log archives to retain; None keeps all archives"""
     meta_path: str = ""
     """Path to meta file"""
 
@@ -44,14 +50,45 @@ class DmonTaskConfig:
 @dataclass
 class DmonMeta(DmonTaskConfig):
     pid: int = -1
+    state: str = "running"
     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)
+    def dump(self, path: PathType, *, exclusive: bool = False):
+        target = Path(path)
+        data = asdict(self)
+        if exclusive:
+            descriptor = os.open(
+                target,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+                0o600,
+            )
+            with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+                json.dump(data, stream, indent=2, ensure_ascii=False)
+                stream.flush()
+                os.fsync(stream.fileno())
+            return
+
+        temporary_path = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                dir=target.parent,
+                prefix=f".{target.name}.",
+                suffix=".tmp",
+                delete=False,
+            ) as stream:
+                temporary_path = Path(stream.name)
+                json.dump(data, stream, indent=2, ensure_ascii=False)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary_path, target)
+        finally:
+            if temporary_path is not None:
+                temporary_path.unlink(missing_ok=True)
 
     @staticmethod
     def load(path: PathType) -> Optional["DmonMeta"]:

{python_dmon-0.3.0.dist-info → python_dmon-0.3.1.dist-info}/METADATA

@@ -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.1.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=M4T7QY5fbeQ94Dx3_OA-FQKVXnJlEStIAtOefmoaaYg,11436
+dmon/config.py,sha256=cYK-KV3sSc6UqOm5cN1dgU-SWRBGoiNE_xFOg2D4GKU,8903
+dmon/constants.py,sha256=uJPI66IJvT6vhamqEDeqHjZQS12RxCPe3DD5yCU0UR8,407
+dmon/control.py,sha256=XaEz8JS2MnsztQC23Dj7guhg6IgNz3uavdfcAyWDbrE,24064
+dmon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dmon/runner.py,sha256=XNUbvw-eOZUQBQ_CLpZNLTFjjI3Uh0IDK_PgqggUPyk,7597
+dmon/types.py,sha256=0BoCkc1hyqriDrPleDVQ7Z53f-U5WeF_DyLLVCVru3k,3131
+dmon/utils.py,sha256=zVQC9YNhMQu4hrAp9k2ds2egnbWZZv7S5w8i2oVIPJg,808
+python_dmon-0.3.1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+python_dmon-0.3.1.dist-info/entry_points.txt,sha256=1XmEpyjShANXEHMIMa4p3WXpcllIZfGt5DQyTFuSI74,78
+python_dmon-0.3.1.dist-info/METADATA,sha256=W4_--3lc_zT4RkTC83susBVqNVUF5WZSBOgtAlY1QzU,8216
+python_dmon-0.3.1.dist-info/RECORD,,

python_dmon-0.3.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-dmon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dmon/__main__.py,sha256=wu5N2wk8mvBgyvr2ghmQf4prezAe0_i-p123VVreyYc,62
-dmon/cli.py,sha256=NgTrOsYjXRPI6BO1T9VReO__quyis91sY04nfk7OWTQ,10514
-dmon/config.py,sha256=JAxasW5G0NIok6hZUZVEpsvF3vp5iiDNr2pjnLpUmh4,7911
-dmon/constants.py,sha256=uJPI66IJvT6vhamqEDeqHjZQS12RxCPe3DD5yCU0UR8,407
-dmon/control.py,sha256=bjRv2YWSo4RFoUHNl1kU1S_XHjC3tWH0aR9QgQtpDY0,18758
-dmon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dmon/runner.py,sha256=zW5dPan0RFAlTsuHwCZ7Pklxt6M740Cu7y8m1f5U9xU,6096
-dmon/types.py,sha256=Cbppb5os7GoKCcwr66S5ge_DunuJepeefpnZGaSr788,1799
-dmon/utils.py,sha256=zVQC9YNhMQu4hrAp9k2ds2egnbWZZv7S5w8i2oVIPJg,808
-python_dmon-0.3.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-python_dmon-0.3.0.dist-info/entry_points.txt,sha256=1XmEpyjShANXEHMIMa4p3WXpcllIZfGt5DQyTFuSI74,78
-python_dmon-0.3.0.dist-info/METADATA,sha256=KmrhqMP-5A4CVpv1iJS1UDbmMGEpfELMtFLMAs-k8u0,6661
-python_dmon-0.3.0.dist-info/RECORD,,