udevmon 0.8.1__py3-none-any.whl

udevmon/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Juan Domingo Martín
+"""udevmon: user-level device and mount event automation."""
+
+from pathlib import Path
+
+
+def __getattr__(name):
+    """``__version__``: written at build time, else asked from git (a source checkout)."""
+    if name == "__version__":
+        try:
+            from ._version import version
+        except ImportError:
+            from ._scm import get_version
+            version = get_version(Path(__file__).resolve().parents[2])
+        globals()["__version__"] = version
+        return version
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

udevmon/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Juan Domingo Martín
+import sys
+
+from .cli import main
+
+sys.exit(main())

udevmon/_scm.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Juan Domingo Martín
+"""Derive the package version from git, formatted exactly like setuptools-scm.
+
+Uses setuptools-scm's default schemes, without depending on it:
+
+* ``guess-next-dev``: on a tag the version is the tag (``0.2.0``); after it, the last
+  number is bumped and ``.devN`` (N = commits since the tag) is added (``0.2.1.dev5``);
+  with no tag at all it is ``0.1.devN`` (N = number of commits).
+* ``node-and-date``: anything that is not exactly a clean tag gets a local part
+  ``+g<commit>`` (``g`` plus 9 hex digits, as in setuptools-scm 10), plus ``.d<YYYYMMDD>`` (the build date) when tracked files have
+  uncommitted changes. Untracked files do not count.
+
+Standard library only: setup.py imports this module before anything is installed.
+Without git (or outside a git checkout) the version comes from ``PKG-INFO`` (an sdist),
+else ``0.0.0+unknown``; this never raises.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+FALLBACK = "0.0.0+unknown"
+_DESCRIBE = re.compile(r"^(?P<tag>.+)-(?P<distance>\d+)-g(?P<node>[0-9a-f]+)(?P<dirty>-dirty)?$")
+NODE_LENGTH = 10                 # "g" + 9 hex digits: what setuptools-scm keeps of the hash
+_TAG = re.compile(r"^(?:[\w-]+-)?[vV]?(?P<version>\d+(?:\.\d+)*[^+]*)")
+
+
+def _git(root: Path, *args: str) -> str | None:
+    """Run git in ``root``; stdout, or None if git is missing or the command fails."""
+    try:
+        done = subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True,
+                              env={**os.environ, "LC_ALL": "C"}, timeout=30)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return done.stdout.strip() if done.returncode == 0 else None
+
+
+def _bump(version: str) -> str:
+    """Increment the trailing number: 0.1.0 -> 0.1.1, 0.2 -> 0.3, 1.0rc1 -> 1.0rc2."""
+    m = re.match(r"^(.*?)(\d+)$", version)
+    return f"{m.group(1)}{int(m.group(2)) + 1}" if m else version + ".1"
+
+
+def _normalize_tag(tag: str) -> str | None:
+    m = _TAG.match(tag)
+    return m.group("version").lower() if m else None
+
+
+def git_version(root: Path, now: datetime | None = None) -> str | None:
+    """The setuptools-scm style version of the git checkout at ``root``, or None."""
+    root = Path(root)
+    top = _git(root, "rev-parse", "--show-toplevel")
+    if top is None or os.path.realpath(top) != os.path.realpath(root):
+        return None                                  # not (the top of) a git checkout
+    if _git(root, "rev-parse", "--verify", "--quiet", "HEAD") is None:
+        return None                                  # no commits yet
+    described = _git(root, "describe", "--dirty", "--tags", "--long", "--abbrev=40",
+                     "--match", "*[0-9]*")
+    m = _DESCRIBE.match(described) if described else None
+    tag = _normalize_tag(m.group("tag")) if m else None
+    if m and tag:
+        distance, dirty = int(m.group("distance")), bool(m.group("dirty"))
+        node = ("g" + m.group("node"))[:NODE_LENGTH]
+    else:                                            # no usable tag
+        count = _git(root, "rev-list", "HEAD", "--count")
+        head = _git(root, "rev-parse", "HEAD")
+        if count is None or head is None:
+            return None
+        tag, distance, node = "0.0", int(count), ("g" + head)[:NODE_LENGTH]
+        dirty = bool(_git(root, "status", "--porcelain", "--untracked-files=no"))
+    if distance == 0 and not dirty:
+        return tag                                   # exactly a clean tag
+    date = (now or datetime.now(timezone.utc)).strftime("%Y%m%d")
+    return f"{_bump(tag)}.dev{distance}+{node}" + (f".d{date}" if dirty else "")
+
+
+def _pkg_info_version(root: Path) -> str | None:
+    try:
+        text = (Path(root) / "PKG-INFO").read_text()
+    except OSError:
+        return None
+    m = re.search(r"^Version:\s*(\S+)", text, re.M)
+    return m.group(1) if m else None
+
+
+def get_version(root: Path) -> str:
+    """The version: from git, else from ``PKG-INFO``, else ``0.0.0+unknown``. Never raises."""
+    return git_version(root) or _pkg_info_version(root) or FALLBACK
+
+
+def version_tuple(version: str) -> tuple:
+    """(0, 1, 'dev4', 'gabc1234.d20260920'): numbers first, then the other parts."""
+    main, _, local = version.partition("+")
+    parts = [int(p) if p.isdigit() else p for p in main.split(".")]
+    return tuple(parts + ([local] if local else []))
+
+
+def write_version_file(path: Path, version: str) -> None:
+    """Write the ``_version.py`` that a built package reads its version from."""
+    Path(path).write_text(
+        "# file generated by setup.py from git; do not edit\n"
+        f"__version__ = version = {version!r}\n"
+        f"__version_tuple__ = version_tuple = {version_tuple(version)!r}\n")

udevmon/_version.py

@@ -0,0 +1,3 @@
+# file generated by setup.py from git; do not edit
+__version__ = version = '0.8.1'
+__version_tuple__ = version_tuple = (0, 8, 1)

udevmon/actions.py

@@ -0,0 +1,306 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Juan Domingo Martín
+"""Run actions as subprocesses (never via a shell)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import subprocess
+import threading
+from concurrent.futures import ThreadPoolExecutor
+
+from . import notify
+from . import pause as pause_flag
+from . import session, state
+from .config import Action, expand
+from .events import Event
+
+log = logging.getLogger("udevmon.actions")
+
+
+def build_env(event: Event, device: str | None, tag: str | None = None,
+              variables=None, state_dir: str | None = None) -> dict[str, str]:
+    """The environment for an action: the daemon's own plus ``UDEVMON_EVENT``,
+    ``UDEVMON_DEVICE``, ``UDEVMON_TAG``, ``UDEVMON_<PROPERTY>``, ``UDEVMON_VAR_<NAME>`` and
+    ``UDEVMON_STATE_DIR``, each when it applies.
+    """
+    env = dict(os.environ)
+    env["UDEVMON_EVENT"] = event.kind
+    if device:
+        env["UDEVMON_DEVICE"] = device
+    if tag:
+        env["UDEVMON_TAG"] = tag
+    for k, v in event.endpoint.props.items():
+        env[f"UDEVMON_{k.upper()}"] = v
+    for k, v in (variables or {}).items():
+        env[f"UDEVMON_VAR_{k.upper()}"] = v
+    if state_dir:
+        env["UDEVMON_STATE_DIR"] = state_dir
+    return env
+
+
+def run_action(action: Action, event: Event, device: str | None, tag: str | None = None, *,
+               dry_run: bool = False, variables=None, state_dir: str | None = None,
+               outcome: dict | None = None) -> int | None:
+    """Run one action; returns exit status (None if skipped/timeout-killed).
+
+    ``outcome``, if given, gets ``failure``: how a None result failed (a timeout, a
+    command that could not start), for the notification; it is left alone otherwise.
+    """
+    outcome = {} if outcome is None else outcome
+    props = dict(event.props)
+    if state_dir:
+        props["state_dir"] = state_dir
+    props.update({f"var_{k}": v for k, v in (variables or {}).items()})
+    if device:
+        props["device"] = device
+    if tag:
+        props["tag"] = tag
+    try:
+        argv = expand(action.run, props)
+    except KeyError as e:
+        log.error("action %r skipped: placeholder(s) %s unavailable for event %r",
+                  action.name, e.args[0], event.kind)
+        return None
+    if dry_run:
+        log.info("[dry-run] action %r would run: %s", action.name, argv)
+        return None
+    log.info("action %r: %s %s", action.name, "starting (detached)" if action.detach
+             else "running", argv)
+    env = build_env(event, device, tag, variables, state_dir)
+    session.update(env)                  # DISPLAY etc., which a service may not have had at start
+    try:
+        proc = subprocess.Popen(
+            argv, cwd=os.path.expanduser("~"), env=env,
+            stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            text=True, errors="replace", start_new_session=True)
+    except OSError as e:
+        log.error("action %r failed to start: %s", action.name, e)
+        outcome["failure"] = f"could not start: {e}"
+        return None
+    # The output is logged as it arrives, by a reader that outlives the command if it has to:
+    # a program the command leaves running in the background keeps the pipe open, and
+    # waiting for the pipe (instead of the command) made the action look stuck.
+    reader = threading.Thread(target=_pump, args=(action, proc), daemon=True,
+                              name=f"output-{action.name}")
+    reader.start()
+    if action.detach:
+        threading.Thread(target=_reap, args=(action, proc), daemon=True,
+                         name=f"reaper-{action.name}").start()
+        return None
+    try:
+        proc.wait(timeout=action.timeout)
+    except subprocess.TimeoutExpired:
+        log.error("action %r timed out after %gs; terminating", action.name, action.timeout)
+        outcome["failure"] = f"timed out after {action.timeout:g} s"
+        _kill_group(proc)
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            _kill_group(proc, signal.SIGKILL)
+            proc.wait()
+        reader.join(timeout=1)
+        return None
+    reader.join(timeout=_DRAIN_WAIT)      # normally the pipe is already closed; not for long
+    _log_exit(action, proc.returncode)
+    return proc.returncode
+
+
+_DRAIN_WAIT = 0.2      # seconds to let the reader catch up after the command has exited
+
+
+def _pump(action, proc) -> None:
+    """Log the command's output line by line until its last writer closes the pipe."""
+    try:
+        for line in proc.stdout:
+            log.info("[%s] %s", action.name, line.rstrip("\r\n"))
+    except (OSError, ValueError):                 # the pipe went away under us
+        pass
+    finally:
+        try:
+            proc.stdout.close()
+        except OSError:
+            pass
+
+
+def _reap(action, proc) -> None:
+    """Log how a detached command ended."""
+    _log_exit(action, proc.wait(), "detached ")
+
+
+def _log_exit(action, status: int, kind: str = "") -> None:
+    log.log(logging.INFO if status == 0 else logging.WARNING,
+            "%saction %r exited with status %d", kind, action.name, status)
+
+
+def _kill_group(proc, sig=signal.SIGTERM):
+    try:
+        os.killpg(proc.pid, sig)
+    except ProcessLookupError:
+        pass
+
+
+class FifoLock:
+    """A mutex that hands the turn out in the order the tickets were taken.
+
+    A ticket is taken when the event is submitted (on the daemon's single main thread, so in
+    the order the events arrived) and used later, by whichever worker runs the job. That
+    keeps the actions of a plug ahead of those of the following unplug even when the unplug
+    reaches a free worker first, which a plain lock would not.
+    """
+
+    def __init__(self, name: str):
+        self.name = name
+        self._cond = threading.Condition()
+        self._next = 0            # the next ticket to hand out
+        self._serving = 0         # the ticket whose turn it is
+
+    def take(self) -> int:
+        """Take the next ticket: a place in the queue, for :meth:`wait`."""
+        with self._cond:
+            ticket = self._next
+            self._next += 1
+            return ticket
+
+    def wait(self, ticket: int) -> bool:
+        """Block until it is ``ticket``'s turn; True if it had to wait."""
+        with self._cond:
+            waited = self._serving != ticket
+            while self._serving != ticket:
+                self._cond.wait()
+            return waited
+
+    def release(self) -> None:
+        """End the current turn and let the next ticket go."""
+        with self._cond:
+            self._serving += 1
+            self._cond.notify_all()
+
+
+class ActionRunner:
+    """Runs the jobs of each event on a pool of ``max_workers`` threads.
+
+    The jobs of one event run one after another in one worker; those of different events
+    can overlap, unless their actions share a ``lock``. With ``dry_run`` the commands are
+    logged, not run.
+    """
+    def __init__(self, max_workers: int = 4, dry_run: bool = False):
+        self.dry_run = dry_run
+        self._pool = ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="action")
+        self._locks: dict[str, FifoLock] = {}
+        self._stopping = threading.Event()      # set by shutdown(): no more retries
+
+    def _lock(self, name: str) -> FifoLock:
+        return self._locks.setdefault(name, FifoLock(name))
+
+    def submit(self, event: Event, jobs, ended: str | None = None):
+        """Run the jobs (engine.Job) sequentially in one worker.
+
+        Called in the order the events arrived: a job whose action has a ``lock`` takes its
+        ticket now, so locked jobs run in that order and never at the same time. ``ended``
+        is the instance whose presence this event ends: its state folder is removed once
+        the jobs are done.
+        """
+        ticketed = [(job, self._lock(job.action.lock).take() if job.action.lock else None)
+                    for job in jobs]
+        return self._pool.submit(self._run_all, event, ticketed, ended)
+
+    def _run_all(self, event, ticketed, ended=None):
+        """Run the jobs in order; returns [(action name, exit status or None)]."""
+        done = 0
+        results = []
+        try:
+            for job, ticket in ticketed:
+                done += 1
+                results.append((job.action.name, self._run_one(event, job, ticket)))
+        except BaseException:
+            for job, ticket in ticketed[done:]:            # never leave a ticket unserved
+                if ticket is not None:
+                    lock = self._lock(job.action.lock)
+                    lock.wait(ticket)
+                    lock.release()
+            raise
+        finally:
+            if ended:
+                state.remove(ended)
+        return results
+
+    def _run_one(self, event, job, ticket):
+        lock = self._lock(job.action.lock) if ticket is not None else None
+        if lock is not None:
+            if lock.wait(ticket):
+                log.info("action %r waited for lock %r", job.action.name, lock.name)
+        try:
+            return self._run_with_retries(event, job)
+        except Exception:
+            log.exception("action %r crashed", job.action.name)
+            return None
+        finally:
+            if lock is not None:
+                lock.release()
+
+    def _state_dir(self, event) -> str | None:
+        """The state folder of the event's instance, created on first use (not for a dry run)."""
+        instance = event.props.get("instance")
+        if not instance or self.dry_run:
+            return None
+        try:
+            return str(state.ensure(instance))
+        except OSError as e:
+            log.warning("cannot create the state folder for %s: %s", instance, e)
+            return None
+
+    def _run_with_retries(self, event, job):
+        """Run the action (with its retries); with ``notify_on_failure``, tell the user
+        when the last attempt failed (a non-zero exit, a timeout, a failure to start)."""
+        outcome: dict = {}
+        status = self._attempts(event, job, outcome)
+        if job.action.notify_on_failure and not self.dry_run:
+            what = outcome.get("failure") or (f"exit status {status}" if status else None)
+            if what:
+                if outcome.get("attempts", 1) > 1:
+                    what += f" (after {outcome['attempts']} attempts)"
+                notify.action_failed(job.action.name, job.device, what)
+        return status
+
+    def _attempts(self, event, job, outcome):
+        """Run the action; after a non-zero exit run it again, up to ``retries`` more times.
+
+        Not retried: a timeout, a command that cannot start, a skipped or dry run (they
+        return None), and nothing once automation is paused or the daemon is stopping.
+        The lock, if any, is held across the attempts.
+        """
+        action = job.action
+        attempts = action.retries + 1
+        for attempt in range(1, attempts + 1):
+            outcome.clear()
+            outcome["attempts"] = attempt
+            status = run_action(action, event, job.device, job.tag, dry_run=self.dry_run,
+                                variables=job.vars, state_dir=self._state_dir(event),
+                                outcome=outcome)
+            if status is None or status == 0:
+                return status
+            if attempt == attempts:
+                if action.retries:
+                    log.warning("action %r gave up after %d attempts (last status %d)",
+                                action.name, attempts, status)
+                return status
+            if pause_flag.is_paused():
+                log.warning("action %r failed with status %d; automation is paused, so not "
+                            "retrying", action.name, status)
+                return status
+            log.warning("action %r attempt %d of %d failed with status %d; retrying in %g s",
+                        action.name, attempt, attempts, status, action.retry_delay)
+            if self._stopping.wait(action.retry_delay):
+                log.warning("action %r: the daemon is stopping, so not retrying", action.name)
+                return status
+        return None
+
+    def shutdown(self, wait=False):
+        """Stop retrying and shut the pool down: with ``wait``, after the running and queued jobs;
+        else queued jobs are cancelled.
+        """
+        self._stopping.set()
+        self._pool.shutdown(wait=wait, cancel_futures=not wait)