ox-proc 0.1.0__py3-none-any.whl

ox_proc/__init__.py

@@ -0,0 +1,45 @@
+"""Launch, monitor, and clean up detached external processes.
+
+See `ox_proc.core` for full documentation.  The public API is
+re-exported here so callers can simply ``import ox_proc``.
+"""
+
+from ox_proc.core import (
+    DEFAULT_MAX_AGE_SECONDS,
+    DEFAULT_MAX_RUNTIME_SECONDS,
+    DEFAULT_TTL_SECONDS,
+    RUN_DIR_ENV_VAR,
+    OxProcError,
+    TooManyLiveError,
+    cleanup,
+    count_live,
+    default_base_dir,
+    generate_run_id,
+    get_info,
+    kill_run,
+    launch,
+    post_message,
+    run_dir_for,
+    write_result,
+)
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'DEFAULT_MAX_AGE_SECONDS',
+    'DEFAULT_MAX_RUNTIME_SECONDS',
+    'DEFAULT_TTL_SECONDS',
+    'RUN_DIR_ENV_VAR',
+    'OxProcError',
+    'TooManyLiveError',
+    'cleanup',
+    'count_live',
+    'default_base_dir',
+    'generate_run_id',
+    'get_info',
+    'kill_run',
+    'launch',
+    'post_message',
+    'run_dir_for',
+    'write_result',
+]

ox_proc/core.py

@@ -0,0 +1,448 @@
+"""Launch, monitor, and clean up detached external processes.
+
+The `ox_proc` package lets a short-lived caller (e.g., a web request
+handler) launch a long-running command as a *detached* subprocess and
+later inspect its progress from any other process, with no broker or
+persistent worker required.  All state lives on disk in a per-run
+directory:
+
+    <base_dir>/<slug>/<run_id>/
+        status.json     written by launcher; finalized by observers
+        messages.jsonl  appended by the child via `post_message()`
+        result.json     written by the child via `write_result()`
+        stdout.log      child's stdout
+        stderr.log      child's stderr
+
+Conventions and caveats:
+
+* The launched command should call `write_result()` on success.  A
+  dead process with no ``result.json`` is reported as state "died".
+* Because the child is detached, its true exit code and end time are
+  lost; observers record an *observed* end time when they first notice
+  the process is gone.  TTL-based cleanup counts from that time.
+* The default base directory lives under `tempfile.gettempdir()`, so
+  the operating system may purge it (e.g., on reboot or via tmpfiles
+  cleaning); run history is therefore not durable.
+* Liveness checks verify both PID existence and the process creation
+  time recorded at launch, guarding against PID reuse.
+
+This module is organized with the public API first and private
+helpers (named with a leading underscore) gathered at the end.
+
+Requires the `psutil` package.
+"""
+
+from __future__ import annotations
+
+import datetime
+import getpass
+import json
+import os
+import secrets
+import subprocess
+import tempfile
+from typing import Any, Iterator, Optional, Sequence
+
+import psutil
+
+DEFAULT_TTL_SECONDS = 24 * 3600          # keep finished runs this long
+DEFAULT_MAX_RUNTIME_SECONDS = 8 * 3600   # kill live runs after this
+DEFAULT_MAX_AGE_SECONDS = 24 * 3600      # deletion backstop from launch
+RUN_DIR_ENV_VAR = 'OX_PROC_RUN_DIR'
+
+_SLUG_CHARS = set('abcdefghijklmnopqrstuvwxyz0123456789_-')
+
+
+class OxProcError(Exception):
+    """Base class for errors raised by this package."""
+
+
+class TooManyLiveError(OxProcError):
+    """Raised when a launch would exceed the live-run limit for a slug."""
+
+
+# ----------------------------------------------------------------------
+# Public API
+# ----------------------------------------------------------------------
+
+def default_base_dir() -> str:
+    """Return the default base directory for run tracking.
+
+    Includes the username to avoid collisions between users sharing
+    the system temporary directory.
+    """
+    user = getpass.getuser()
+    return os.path.join(tempfile.gettempdir(), f'ox_proc-{user}')
+
+
+def generate_run_id(slug: str) -> str:
+    """Return a new run ID of the form ``<slug>-<timestamp>-<rand>``."""
+    stamp = datetime.datetime.now().strftime('%Y%m%dT%H%M%S')
+    return f'{_sanitize_slug(slug)}-{stamp}-{secrets.token_hex(2)}'
+
+
+def run_dir_for(run_id: str, base_dir: Optional[str] = None) -> str:
+    """Return the directory path holding files for `run_id`."""
+    base_dir = base_dir or default_base_dir()
+    return os.path.join(base_dir, _slug_from_run_id(run_id), run_id)
+
+
+def launch(cmd: Sequence[str], slug: str,
+           description: Optional[str] = None,
+           env_updates: Optional[dict[str, str]] = None,
+           base_dir: Optional[str] = None,
+           ttl_seconds: float = DEFAULT_TTL_SECONDS,
+           max_runtime_seconds: Optional[float] =
+           DEFAULT_MAX_RUNTIME_SECONDS,
+           max_live: Optional[int] = None) -> str:
+    """Launch `cmd` (a list of strings) as a detached subprocess.
+
+    The child is placed in its own session so it survives the caller's
+    exit; its stdout/stderr go to log files in the run directory, and
+    the environment variable named by `RUN_DIR_ENV_VAR` points the
+    child at that directory so it can use `post_message()` and
+    `write_result()`.
+
+    `env_updates`, if given, is merged into a copy of the caller's
+    environment.  If `max_live` is given and at least that many runs
+    with this slug are still alive, `TooManyLiveError` is raised (a
+    small launch race is accepted; the limit is best-effort).
+
+    Returns the new run ID.
+    """
+    slug = _sanitize_slug(slug)
+    if max_live is not None and \
+            count_live(base_dir).get(slug, 0) >= max_live:
+        raise TooManyLiveError(
+            f'Slug {slug!r} already has {max_live} or more live runs.')
+    run_id = generate_run_id(slug)
+    run_dir = run_dir_for(run_id, base_dir)
+    os.makedirs(run_dir)
+    env = os.environ.copy()
+    env.update(env_updates or {})
+    env[RUN_DIR_ENV_VAR] = run_dir
+    with open(os.path.join(run_dir, 'stdout.log'), 'wb') as out, \
+            open(os.path.join(run_dir, 'stderr.log'), 'wb') as err:
+        proc = subprocess.Popen(
+            cmd, stdin=subprocess.DEVNULL, stdout=out, stderr=err,
+            env=env, start_new_session=True)
+    status = {
+        'run_id': run_id,
+        'slug': slug,
+        'state': 'running',
+        'pid': proc.pid,
+        'pid_create_time': psutil.Process(proc.pid).create_time(),
+        'cmd': list(cmd),
+        'description': description,
+        'launch_time': _now_iso(),
+        'observed_end_time': None,
+        'ttl_seconds': ttl_seconds,
+        'max_runtime_seconds': max_runtime_seconds,
+        'env_update_keys': sorted(env_updates or {}),
+    }
+    _atomic_write_json(os.path.join(run_dir, 'status.json'), status)
+    return run_id
+
+
+def post_message(text: str, **extra_fields: Any) -> None:
+    """Append a status message; called from inside a launched process.
+
+    Each message is one JSON line in ``messages.jsonl`` containing a
+    timestamp, `text`, and any `extra_fields` (which must be
+    JSON-serializable).  Single-line appends are atomic on POSIX, so
+    concurrent writers need no locking.
+    """
+    record: dict[str, Any] = {'time': _now_iso(), 'text': text}
+    record.update(extra_fields)
+    path = os.path.join(_current_run_dir(), 'messages.jsonl')
+    with open(path, 'a', encoding='utf-8') as handle:
+        handle.write(json.dumps(record) + '\n')
+
+
+def write_result(result: Any) -> None:
+    """Write the final result; called from inside a launched process.
+
+    `result` may be any JSON-serializable value (string, number,
+    dict, list, ...).  By convention a launched process should always
+    call this on success (even with a trivial value); a dead process
+    with no result file is reported as state "died".
+    """
+    path = os.path.join(_current_run_dir(), 'result.json')
+    _atomic_write_json(path, {'time': _now_iso(), 'result': result})
+
+
+def get_info(run_id: str, base_dir: Optional[str] = None,
+             tail: int = 10) -> Optional[dict[str, Any]]:
+    """Return a summary dict for `run_id`, or None if unknown.
+
+    The summary includes the status fields, elapsed runtime, the last
+    `tail` status messages, the last `tail` lines of stdout and
+    stderr, and the result (if written).  If the process has died
+    without a recorded end, the status file is updated accordingly.
+    """
+    run_dir = run_dir_for(run_id, base_dir)
+    status = _refresh_status(run_dir)
+    if status is None:
+        return None
+    launch_time = _parse_iso(status['launch_time'])
+    end_time = (_parse_iso(status['observed_end_time'])
+                or datetime.datetime.now())
+    elapsed = (end_time - launch_time).total_seconds() if launch_time \
+        else None
+    messages = [_read_json_line(line) for line in
+                _tail_lines(os.path.join(run_dir, 'messages.jsonl'), tail)]
+    result = _read_json(os.path.join(run_dir, 'result.json'))
+    return {
+        **status,
+        'elapsed_seconds': elapsed,
+        'messages': [msg for msg in messages if msg is not None],
+        'stdout_tail': _tail_lines(os.path.join(run_dir, 'stdout.log'),
+                                   tail),
+        'stderr_tail': _tail_lines(os.path.join(run_dir, 'stderr.log'),
+                                   tail),
+        'result': result,
+    }
+
+
+def count_live(base_dir: Optional[str] = None) -> dict[str, int]:
+    """Return a mapping of slug to number of still-running runs.
+
+    Slugs with no live runs are omitted, so use
+    ``count_live().get(slug, 0)`` to query a single slug.
+    """
+    counts: dict[str, int] = {}
+    for run_dir in _iter_run_dirs(base_dir):
+        status = _refresh_status(run_dir)
+        if status is not None and status['state'] == 'running':
+            slug = status['slug']
+            counts[slug] = counts.get(slug, 0) + 1
+    return counts
+
+
+def kill_run(run_id: str, base_dir: Optional[str] = None) -> bool:
+    """Kill the process group of `run_id` if it is still alive.
+
+    Returns True if a kill signal was sent, False if the run was
+    already dead or unknown.  The whole process group is signaled
+    (the child was launched in its own session), so grandchildren
+    are included.
+    """
+    run_dir = run_dir_for(run_id, base_dir)
+    status = _refresh_status(run_dir)
+    if status is None or status['state'] != 'running':
+        return False
+    try:
+        os.killpg(status['pid'], 15)  # SIGTERM to the whole group
+    except (ProcessLookupError, PermissionError):
+        return False
+    _finalize_status(run_dir, status, 'killed')
+    return True
+
+
+def cleanup(base_dir: Optional[str] = None,
+            ttl_override: Optional[float] = None) -> dict[str, list[str]]:
+    """Perform periodic maintenance over all runs under `base_dir`.
+
+    Live runs that have exceeded their per-run `max_runtime_seconds`
+    are killed.  Ended runs are deleted once their TTL (counted from
+    observed end time, or `ttl_override` if given) has passed.  Runs
+    whose end was never observed are deleted via a backstop counted
+    from launch time.  Returns a dict with lists of killed and
+    deleted run IDs.
+    """
+    now = datetime.datetime.now()
+    killed: list[str] = []
+    deleted: list[str] = []
+    for run_dir in list(_iter_run_dirs(base_dir)):
+        status = _refresh_status(run_dir)
+        run_id = os.path.basename(run_dir)
+        if status is not None and status['state'] == 'running':
+            launch_time = _parse_iso(status['launch_time'])
+            limit = status.get('max_runtime_seconds',
+                               DEFAULT_MAX_RUNTIME_SECONDS)
+            if launch_time is not None and limit is not None and \
+                    (now - launch_time).total_seconds() > limit:
+                if kill_run(run_id, base_dir):
+                    killed.append(run_id)
+            continue
+        if _should_delete(status, run_dir, now, ttl_override):
+            _remove_run_dir(run_dir)
+            deleted.append(run_id)
+    return {'killed': killed, 'deleted': deleted}
+
+
+# ----------------------------------------------------------------------
+# Private helpers
+# ----------------------------------------------------------------------
+
+def _sanitize_slug(slug: str) -> str:
+    """Validate `slug`, returning it unchanged or raising ValueError."""
+    if not slug or not set(slug) <= _SLUG_CHARS:
+        raise ValueError(
+            f'Invalid slug {slug!r}: use only lowercase letters, digits, '
+            'underscore, and hyphen.')
+    return slug
+
+
+def _slug_from_run_id(run_id: str) -> str:
+    """Extract the slug portion from a run ID."""
+    parts = run_id.rsplit('-', 2)
+    if len(parts) != 3:
+        raise ValueError(f'Malformed run ID: {run_id!r}')
+    return parts[0]
+
+
+def _atomic_write_json(path: str, data: Any) -> None:
+    """Write `data` as JSON to `path` atomically (temp file + rename)."""
+    tmp_path = f'{path}.tmp.{os.getpid()}'
+    with open(tmp_path, 'w', encoding='utf-8') as handle:
+        json.dump(data, handle, indent=2)
+    os.replace(tmp_path, path)
+
+
+def _read_json(path: str) -> Any:
+    """Return parsed JSON from `path`, or None if absent/unreadable."""
+    try:
+        with open(path, encoding='utf-8') as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return None
+
+
+def _read_json_line(line: str) -> Any:
+    """Parse one JSON line, returning None on failure."""
+    try:
+        return json.loads(line)
+    except ValueError:
+        return None
+
+
+def _now_iso() -> str:
+    """Return the current local time as an ISO-8601 string."""
+    return datetime.datetime.now().isoformat(timespec='seconds')
+
+
+def _parse_iso(text: Optional[str]) -> Optional[datetime.datetime]:
+    """Parse an ISO-8601 string into a datetime, or return None."""
+    try:
+        return datetime.datetime.fromisoformat(text)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def _current_run_dir() -> str:
+    """Return this process's run directory from the environment."""
+    run_dir = os.environ.get(RUN_DIR_ENV_VAR)
+    if not run_dir:
+        raise OxProcError(
+            f'{RUN_DIR_ENV_VAR} is not set; was this process launched '
+            'via ox_proc.launch()?')
+    return run_dir
+
+
+def _is_alive(status: dict[str, Any]) -> bool:
+    """Return True if the process described by `status` is still alive.
+
+    Checks both PID existence and the creation time recorded at
+    launch, so a reused PID is not mistaken for our process.
+    """
+    try:
+        proc = psutil.Process(status['pid'])
+        if proc.create_time() != status['pid_create_time']:
+            return False
+        # An exited-but-unreaped child (the launcher never waited on
+        # it) lingers as a zombie; treat that as dead.
+        return proc.status() != psutil.STATUS_ZOMBIE
+    except psutil.NoSuchProcess:
+        return False
+
+
+def _finalize_status(run_dir: str, status: dict[str, Any],
+                     state: str) -> None:
+    """Mark `status` as ended with `state` and rewrite status.json.
+
+    Multiple observers may race to do this; they write nearly
+    identical content atomically, so last-writer-wins is harmless.
+    """
+    status['state'] = state
+    status['observed_end_time'] = _now_iso()
+    _atomic_write_json(os.path.join(run_dir, 'status.json'), status)
+
+
+def _refresh_status(run_dir: str) -> Optional[dict[str, Any]]:
+    """Load status.json, reconciling state with actual liveness.
+
+    Returns the (possibly updated) status dict, or None if the run
+    directory has no readable status file.
+    """
+    status = _read_json(os.path.join(run_dir, 'status.json'))
+    if status is None:
+        return None
+    if status['state'] == 'running' and not _is_alive(status):
+        has_result = os.path.exists(os.path.join(run_dir, 'result.json'))
+        _finalize_status(run_dir, status, 'finished' if has_result
+                         else 'died')
+    return status
+
+
+def _tail_lines(path: str, num_lines: int,
+                max_bytes: int = 65536) -> list[str]:
+    """Return up to the last `num_lines` lines of the file at `path`."""
+    try:
+        with open(path, 'rb') as handle:
+            handle.seek(0, os.SEEK_END)
+            size = handle.tell()
+            handle.seek(max(0, size - max_bytes))
+            data = handle.read()
+    except OSError:
+        return []
+    text = data.decode('utf-8', errors='replace')
+    return text.splitlines()[-num_lines:]
+
+
+def _iter_run_dirs(base_dir: Optional[str] = None) -> Iterator[str]:
+    """Yield all run directory paths under `base_dir`."""
+    base_dir = base_dir or default_base_dir()
+    try:
+        slug_names = sorted(os.listdir(base_dir))
+    except OSError:
+        return
+    for slug_name in slug_names:
+        slug_dir = os.path.join(base_dir, slug_name)
+        try:
+            names = sorted(os.listdir(slug_dir))
+        except OSError:
+            continue
+        for name in names:
+            yield os.path.join(slug_dir, name)
+
+
+def _remove_run_dir(run_dir: str) -> None:
+    """Best-effort removal of a run directory and its contents."""
+    try:
+        for name in os.listdir(run_dir):
+            os.unlink(os.path.join(run_dir, name))
+        os.rmdir(run_dir)
+    except OSError:
+        pass
+
+
+def _should_delete(status: Optional[dict[str, Any]], run_dir: str,
+                   now: datetime.datetime,
+                   ttl_override: Optional[float]) -> bool:
+    """Return True if a finished/orphaned run is past its retention."""
+    if status is None:  # unreadable/orphan dir: use backstop via mtime
+        try:
+            age = now.timestamp() - os.path.getmtime(run_dir)
+        except OSError:
+            return False
+        return age > DEFAULT_MAX_AGE_SECONDS
+    ttl = ttl_override if ttl_override is not None \
+        else status.get('ttl_seconds', DEFAULT_TTL_SECONDS)
+    end_time = _parse_iso(status.get('observed_end_time'))
+    if end_time is not None:
+        return (now - end_time).total_seconds() > ttl
+    launch_time = _parse_iso(status.get('launch_time'))
+    if launch_time is not None:  # end never observed: backstop from start
+        return (now - launch_time).total_seconds() > DEFAULT_MAX_AGE_SECONDS
+    return False

ox_proc-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: ox_proc
+Version: 0.1.0
+Summary: Launch, monitor, and clean up detached external processes with on-disk status tracking (no broker or worker required).
+Project-URL: Homepage, https://github.com/aocks/ox_proc
+Author-email: Emin Martinian <emin.martinian@gmail.com>
+License-Expression: BSD-2-Clause
+Keywords: background,detached,job,status,subprocess
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: psutil>=5.9
+Provides-Extra: dev
+Requires-Dist: pycodestyle; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ox_proc
+
+Launch, monitor, and clean up **detached** external processes with
+simple on-disk status tracking — no message broker, no persistent
+worker process.
+
+`ox_proc` is aimed at the common case where a short-lived caller
+(e.g., a Flask/gunicorn request handler) needs to kick off a
+long-running command, return immediately, and let *any* later process
+check progress, read recent output, fetch the final result, or kill
+the run.
+
+## How it works
+
+Each launch gets a run ID like `myslug-20260611T143022-a1b2` and a
+run directory:
+
+```
+<base_dir>/<slug>/<run_id>/
+    status.json     written by the launcher; finalized by observers
+    messages.jsonl  appended by the child via post_message()
+    result.json     written by the child via write_result()
+    stdout.log      child's stdout
+    stderr.log      child's stderr
+```
+
+The child is launched in its own session (`setsid`), so it survives
+the launcher's exit. Liveness checks verify both the PID and the
+process creation time recorded at launch, so a reused PID is never
+mistaken for the original process. No file locking is needed:
+`status.json` and `result.json` use atomic write-and-rename, and
+`messages.jsonl` is append-only.
+
+## Quick start
+
+Launcher side (e.g., in a web request handler):
+
+```python
+import ox_proc
+
+run_id = ox_proc.launch(
+    ["python", "-m", "myproject.analysis", "--full"],
+    slug="analysis",
+    description="Nightly full analysis",
+    env_updates={"ANALYSIS_MODE": "full"},
+    max_live=1,            # raise TooManyLiveError if one is running
+)
+```
+
+Child side (inside the launched command):
+
+```python
+import ox_proc
+
+ox_proc.post_message("loading data", progress=0.1)
+...
+ox_proc.write_result({"rows": 12345, "ok": True})   # always on success
+```
+
+Status side (any process, any time):
+
+```python
+info = ox_proc.get_info(run_id)
+info["state"]          # "running", "finished", "died", or "killed"
+info["messages"]       # recent post_message() records
+info["stdout_tail"]    # last lines of stdout
+info["result"]         # contents of result.json, or None
+
+ox_proc.count_live()   # {"analysis": 1, ...}
+ox_proc.kill_run(run_id)
+ox_proc.cleanup()      # call periodically: kills over-runtime runs,
+                       # deletes expired finished runs
+```
+
+## Conventions and caveats
+
+* **Always call `write_result()` on success.** Because the child is
+  detached, its true exit code is lost; a dead process with no
+  `result.json` is reported as state `"died"`.
+* End times are *observed*: recorded when an observer first notices
+  the process is gone. TTL-based deletion counts from that time, with
+  a backstop (default 24 h from launch) for runs whose end was never
+  observed.
+* Live runs are killed by `cleanup()` once they exceed their per-run
+  `max_runtime_seconds` (default 8 h; pass `None` for unlimited).
+* `kill_run()` sends SIGTERM to the whole process group; there is no
+  SIGKILL escalation.
+* The default base directory is
+  `tempfile.gettempdir()/ox_proc-<username>`, which the OS may purge
+  (reboots, tmpfiles cleaning) — run history is not durable. Pass
+  `base_dir=` everywhere for a durable location.
+* POSIX only (relies on sessions/process groups and atomic appends).
+* The `max_live` limit is best-effort: two simultaneous launches can
+  race past it.
+
+## Installation
+
+```
+pip install ox_proc
+```
+
+Requires Python 3.9+ and `psutil`.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```

ox_proc-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+ox_proc/__init__.py,sha256=AyEB73wmYMQgffYGaV3D8wvmPlMihXYfP8-b8g3hIyw,912
+ox_proc/core.py,sha256=u6iu7A9gCbSxQhCSZw6sf2zUuN5BWYYLbeV0DS-noSE,16932
+ox_proc-0.1.0.dist-info/METADATA,sha256=gJHfJMPc9cDnJ50sFydVC4uU5ZaCIQ1IEMbV8GogwLI,4200
+ox_proc-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ox_proc-0.1.0.dist-info/RECORD,,

ox_proc-0.1.0.dist-info/WHEEL

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