pymidi-controller 0.3.1__tar.gz → 0.4.1__tar.gz

{pymidi_controller-0.3.1/pymidi_controller.egg-info → pymidi_controller-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymidi-controller
-Version: 0.3.1
+Version: 0.4.1
 Summary: Daemon that maps MIDI events to system actions (Elgato, Hue, or custom functions).
 Author-email: Alex Sandilands <sandilands.alex@gmail.com>
 License-Expression: MIT
@@ -20,6 +20,8 @@ Requires-Dist: python-rtmidi>=1.4.10
 Requires-Dist: requests>=2.0
 Requires-Dist: zeroconf>=0.40
 Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
 Dynamic: license-file
 
 # 🎹 PyMIDI Controller
@@ -157,15 +159,17 @@ Use `pymidi <group> --help` for details on each context.
 
 ### Service
 
-| Command                             | Description                         |
-| ----------------------------------- | ----------------------------------- |
-| `pymidi service install --user`     | Install & start as a user service   |
-| `pymidi service install --system`   | Install & start system-wide service |
-| `pymidi service uninstall --user`   | Stop & remove user service          |
-| `pymidi service uninstall --system` | Stop & remove system service        |
-| `pymidi service stop`               | Stop the running service            |
-| `pymidi service enable`             | Enable service (user scope)         |
-| `pymidi service log`                | Tail service logs                   |
+| Command                                      | Description                         |
+| -------------------------------------------- | ----------------------------------- |
+| `pymidi service --user install`               | Install & start as a user service   |
+| `pymidi service --system install`             | Install & start system-wide service |
+| `pymidi service --user uninstall`             | Stop & remove user service          |
+| `pymidi service --system uninstall`           | Stop & remove system service        |
+| `pymidi service --user\|--system stop`        | Stop the running service            |
+| `pymidi service --user\|--system enable`      | Enable service                      |
+| `pymidi service --user\|--system log`         | Tail service logs                   |
+
+Every service subcommand requires a scope flag before the subcommand. Choose either `--user` or `--system` where the table shows `--user|--system`, for example `pymidi service --user stop`. `--system install` and `--system uninstall` must be run through `sudo`; see [System-wide install](#system-wide-install-headless).
 
 ### Hue Commands
 
@@ -303,21 +307,42 @@ bindings:
 To run automatically at login:
 
 ```bash
-pymidi service install --user
+pymidi service --user install
 ```
 
 The user service starts with your graphical session (`graphical-session.target`), after the desktop compositor is up. It does not pull that target in itself, so it can't make other autostart apps start early.
 
 If your window manager doesn't start `graphical-session.target` (Plasma and GNOME do; some minimal setups such as i3, sway or Hyprland don't unless configured to), the service won't start at login. Start the target from your session startup, e.g. `systemctl --user start graphical-session.target`.
 
-> **Upgrading from 0.3.0 or earlier?** Rerun `pymidi service install --user` (or `--system` for a system-wide install) once. It replaces the old unit and removes its stale `default.target` link. `pymidi service enable` alone doesn't refresh the unit file.
+> **Upgrading from 0.3.0 or earlier?** Rerun `pymidi service --user install` (or the `--system` command below for a system-wide install) once. It replaces the old unit and removes its stale `default.target` link. `pymidi service --user enable` alone doesn't refresh the unit file.
 
 Logs:
 
 ```bash
-pymidi service log
+pymidi service --user log
 ```
 
+### System-wide install (headless)
+
+The user service only starts with a graphical session. On a headless machine (a Raspberry Pi or server driving Hue or Elgato lights, say), install it system-wide so it starts at boot:
+
+```bash
+sudo "$(command -v pymidi)" service --system install
+```
+
+Start it through `sudo` from your own account: the service runs as the user named in `SUDO_USER`, which `sudo` sets (it also survives `sudo -i` and `sudo -s`). A root login, `su` or `doas` doesn't set it, so the command refuses to install rather than guess. `sudo` resets `PATH`, so pass the full path to `pymidi` as shown. The service reads that user's config from `~/.config/pymidi-controller`, and joins the `audio` group (when the system has one) so it can reach the ALSA sequencer without a login session. The unit records the Python interpreter that ran the install, so reinstall after moving or recreating a venv.
+
+A system service has no desktop session (no `DISPLAY`, `WAYLAND_DISPLAY` or session D-Bus), so bindings that launch desktop programs or use `notify-send` won't work. Use the `--user` service for those; Hue and Elgato actions over the network are fine.
+
+Logs and removal:
+
+```bash
+pymidi service --system log
+sudo "$(command -v pymidi)" service --system uninstall
+```
+
+> **Already have a `--system` install from 0.3.x?** Rerun the install command above once. The old unit ran as root and looked for `pymidi-controller` on a `PATH` that never included `~/.local/bin`, so it was unlikely to have worked; rerunning the install replaces the unit and restarts the service.
+
 ---
 
 ## 📜 License

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1}/README.md

@@ -133,15 +133,17 @@ Use `pymidi <group> --help` for details on each context.
 
 ### Service
 
-| Command                             | Description                         |
-| ----------------------------------- | ----------------------------------- |
-| `pymidi service install --user`     | Install & start as a user service   |
-| `pymidi service install --system`   | Install & start system-wide service |
-| `pymidi service uninstall --user`   | Stop & remove user service          |
-| `pymidi service uninstall --system` | Stop & remove system service        |
-| `pymidi service stop`               | Stop the running service            |
-| `pymidi service enable`             | Enable service (user scope)         |
-| `pymidi service log`                | Tail service logs                   |
+| Command                                      | Description                         |
+| -------------------------------------------- | ----------------------------------- |
+| `pymidi service --user install`               | Install & start as a user service   |
+| `pymidi service --system install`             | Install & start system-wide service |
+| `pymidi service --user uninstall`             | Stop & remove user service          |
+| `pymidi service --system uninstall`           | Stop & remove system service        |
+| `pymidi service --user\|--system stop`        | Stop the running service            |
+| `pymidi service --user\|--system enable`      | Enable service                      |
+| `pymidi service --user\|--system log`         | Tail service logs                   |
+
+Every service subcommand requires a scope flag before the subcommand. Choose either `--user` or `--system` where the table shows `--user|--system`, for example `pymidi service --user stop`. `--system install` and `--system uninstall` must be run through `sudo`; see [System-wide install](#system-wide-install-headless).
 
 ### Hue Commands
 
@@ -279,21 +281,42 @@ bindings:
 To run automatically at login:
 
 ```bash
-pymidi service install --user
+pymidi service --user install
 ```
 
 The user service starts with your graphical session (`graphical-session.target`), after the desktop compositor is up. It does not pull that target in itself, so it can't make other autostart apps start early.
 
 If your window manager doesn't start `graphical-session.target` (Plasma and GNOME do; some minimal setups such as i3, sway or Hyprland don't unless configured to), the service won't start at login. Start the target from your session startup, e.g. `systemctl --user start graphical-session.target`.
 
-> **Upgrading from 0.3.0 or earlier?** Rerun `pymidi service install --user` (or `--system` for a system-wide install) once. It replaces the old unit and removes its stale `default.target` link. `pymidi service enable` alone doesn't refresh the unit file.
+> **Upgrading from 0.3.0 or earlier?** Rerun `pymidi service --user install` (or the `--system` command below for a system-wide install) once. It replaces the old unit and removes its stale `default.target` link. `pymidi service --user enable` alone doesn't refresh the unit file.
 
 Logs:
 
 ```bash
-pymidi service log
+pymidi service --user log
 ```
 
+### System-wide install (headless)
+
+The user service only starts with a graphical session. On a headless machine (a Raspberry Pi or server driving Hue or Elgato lights, say), install it system-wide so it starts at boot:
+
+```bash
+sudo "$(command -v pymidi)" service --system install
+```
+
+Start it through `sudo` from your own account: the service runs as the user named in `SUDO_USER`, which `sudo` sets (it also survives `sudo -i` and `sudo -s`). A root login, `su` or `doas` doesn't set it, so the command refuses to install rather than guess. `sudo` resets `PATH`, so pass the full path to `pymidi` as shown. The service reads that user's config from `~/.config/pymidi-controller`, and joins the `audio` group (when the system has one) so it can reach the ALSA sequencer without a login session. The unit records the Python interpreter that ran the install, so reinstall after moving or recreating a venv.
+
+A system service has no desktop session (no `DISPLAY`, `WAYLAND_DISPLAY` or session D-Bus), so bindings that launch desktop programs or use `notify-send` won't work. Use the `--user` service for those; Hue and Elgato actions over the network are fine.
+
+Logs and removal:
+
+```bash
+pymidi service --system log
+sudo "$(command -v pymidi)" service --system uninstall
+```
+
+> **Already have a `--system` install from 0.3.x?** Rerun the install command above once. The old unit ran as root and looked for `pymidi-controller` on a `PATH` that never included `~/.local/bin`, so it was unlikely to have worked; rerunning the install replaces the unit and restarts the service.
+
 ---
 
 ## 📜 License

pymidi_controller-0.4.1/pymidi_controller/__main__.py

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

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1}/pymidi_controller/config.py

@@ -1,3 +1,5 @@
+import sys
+
 from pymidi_controller.utils.config_manager import load_config
 
 _cfg = load_config()
@@ -13,5 +15,6 @@ MIDI_DEVICES    = _m.get("devices", [])
 MIDI_BINDINGS   = _m.get("bindings", {})
 COLOR_CYCLES    = _m.get("color_cycles", {})
 
-# CLI entrypoint
-CLI_COMMAND = "pymidi-controller"
+# CLI entrypoint: the running interpreter, so bindings work without the
+# console script on PATH (the system service has no ~/.local/bin)
+CLI_COMMAND = [sys.executable, "-m", "pymidi_controller"]

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1}/pymidi_controller/core.py

@@ -18,7 +18,7 @@ def handle_midi_message(msg, bindings):
 
     key = format_midi_key(msg)
     if key and key in bindings:
-        command = [CLI_COMMAND] + bindings[key]
+        command = CLI_COMMAND + bindings[key]
         print(f"🎯 Matched {key} → Running: {' '.join(command)}")
         try:
             subprocess.Popen(command)
@@ -60,6 +60,9 @@ def run(mode: str = "blocking"):
     Entry point for the long-running MIDI listener.
     mode: 'interactive' or 'blocking'
     """
+    # Under systemd stdout is a pipe, so flush per line to reach the journal
+    sys.stdout.reconfigure(line_buffering=True)
+
     bindings = MIDI_BINDINGS
     if not bindings:
         print("❌ No MIDI bindings defined in config.yaml.")

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1}/pymidi_controller/data/systemd/pymidi-controller.system.service

@@ -5,8 +5,9 @@ Wants=sound.target
 
 [Service]
 Type=simple
-Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
-ExecStart=/usr/bin/env pymidi-controller run --mode blocking
+User=@USER@
+@SUPPLEMENTARY_GROUPS@
+ExecStart=@EXEC_START@
 Restart=always
 RestartSec=5
 StandardOutput=journal

pymidi_controller-0.4.1/pymidi_controller/utils/service_manager.py

@@ -0,0 +1,252 @@
+import grp
+import os
+import pwd
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from importlib import resources
+from enum import Enum, auto
+
+# -------------------------------------------------------------------
+# Service Installation & Management with Scoped Control
+# -------------------------------------------------------------------
+
+class ServiceScope(Enum):
+    USER = auto()
+    SYSTEM = auto()
+
+
+SYSTEM_UNIT_DIR = Path("/etc/systemd/system")
+
+# Conservative, but allows realm-style names (alice@corp.com); excludes % and whitespace
+_USERNAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_.@-]*\$?")
+
+
+def _exec_start_arg(path: str) -> str:
+    """
+    Escape a path for use as the executable in a unit's ExecStart=.
+
+    systemd rejects quotes and backslashes in the executable word whatever the
+    quoting, so those paths are refused. A literal $ is fine there ($$ is only
+    collapsed in arguments).
+    """
+    bad = [c for c in path if ord(c) < 32 or ord(c) == 127 or c in "'\"\\"]
+    if bad:
+        raise ValueError(
+            f"Can't write a systemd unit for the interpreter at {path!r}: its path contains "
+            "a control, quote or backslash character. Install pymidi from a path without those."
+        )
+    path = path.replace("%", "%%")  # % is a unit specifier
+    if any(c.isspace() for c in path):
+        path = '"' + path + '"'
+    return path
+
+
+def render_system_unit(user: str, python: str, audio_group: bool = True) -> str:
+    """
+    Render the system-wide unit for ``user``, running ``python -m pymidi_controller``.
+
+    The absolute interpreter path means the unit doesn't depend on PATH, which the
+    system manager doesn't set up for a user (pipx, venv and pip --user installs).
+    ``audio_group`` adds SupplementaryGroups=audio; leave it off where the group
+    doesn't exist, as systemd refuses to start a unit naming a missing group.
+    """
+    if not _USERNAME_RE.fullmatch(user):
+        raise ValueError(f"Unsupported user name for a systemd unit: {user!r}")
+    template = (resources.files("pymidi_controller") / "data/systemd/pymidi-controller.system.service").read_text(encoding="utf-8")
+    exec_start = f"{_exec_start_arg(python)} -m pymidi_controller run --mode blocking"
+    groups = "SupplementaryGroups=audio\n" if audio_group else ""
+    return (
+        template.replace("@USER@", user)
+        .replace("@SUPPLEMENTARY_GROUPS@\n", groups)
+        .replace("@EXEC_START@", exec_start)
+    )
+
+
+def _require_root(action: str):
+    """Exit with a clear message instead of a PermissionError traceback."""
+    if os.geteuid() != 0:
+        sys.exit(
+            f"⚠️  `service --system {action}` must run as root. "
+            'Use: sudo "$(command -v pymidi)" service --system ' + action
+        )
+
+
+def _invoking_user() -> str:
+    """The user to run the system service as: whoever invoked sudo."""
+    user = os.environ.get("SUDO_USER")
+    if not user or user == "root":
+        sys.exit(
+            "⚠️  Can't tell which user the service should run as. Run this from your own "
+            'account with sudo, e.g. sudo "$(command -v pymidi)" service --system install '
+            "(running directly as root isn't supported)."
+        )
+    try:
+        pwd.getpwnam(user)
+    except KeyError:
+        sys.exit(f"⚠️  SUDO_USER {user!r} isn't a known user.")
+    return user
+
+
+def _audio_group_exists() -> bool:
+    try:
+        grp.getgrnam("audio")
+    except KeyError:
+        return False
+    return True
+
+
+def _warn_audio_group(user: str):
+    try:
+        audio = grp.getgrnam("audio")
+    except KeyError:
+        print("⚠️  No 'audio' group on this system, so the unit omits SupplementaryGroups=audio. The service may not be able to open /dev/snd/seq.")
+        return
+    gids = os.getgrouplist(user, pwd.getpwnam(user).pw_gid)
+    if audio.gr_gid not in gids:
+        print(f"⚠️  {user} isn't in the 'audio' group. The service adds it itself, but `pymidi` run from a shell may not reach /dev/snd/seq (sudo usermod -aG audio {user}).")
+
+
+def install(scope: ServiceScope):
+    """
+    Install and enable the systemd service unit.
+
+    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
+    """
+    unit_text = None
+    if scope == ServiceScope.USER:
+        target_dir = Path.home() / ".config/systemd/user"
+        ctl = ["systemctl", "--user"]
+        src_name = "pymidi-controller.service"
+    elif scope == ServiceScope.SYSTEM:
+        _require_root("install")
+        user = _invoking_user()
+        target_dir = SYSTEM_UNIT_DIR
+        ctl = ["systemctl"]
+        try:
+            unit_text = render_system_unit(user, sys.executable, audio_group=_audio_group_exists())
+        except ValueError as e:
+            sys.exit(f"⚠️  {e}")
+    else:
+        print("⚠️  Invalid scope for install.")
+        return
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    dst = target_dir / "pymidi-controller.service"
+    if unit_text is None:
+        src = resources.files("pymidi_controller") / "data/systemd" / src_name
+        shutil.copy(src, dst)
+    else:
+        dst.write_text(unit_text, encoding="utf-8")
+    print(f"✔️  Installed service unit to {dst}")
+    if unit_text is not None:
+        print(f"   User={user}")
+        print(f"   ExecStart={sys.executable} -m pymidi_controller run --mode blocking")
+        _warn_audio_group(user)
+
+    subprocess.run(ctl + ["daemon-reload"], check=True)
+    # Drop links from older units (e.g. default.target.wants) before enabling
+    subprocess.run(ctl + ["disable", "pymidi-controller.service"], check=False)
+    subprocess.run(ctl + ["enable", "pymidi-controller.service"], check=True)
+    # restart (not enable --now) so a reinstall replaces an already-running old process
+    subprocess.run(ctl + ["restart", "pymidi-controller.service"], check=True)
+    print("✅ Service enabled and started.")
+
+
+def uninstall(scope: ServiceScope):
+    """
+    Disable and remove the systemd service unit.
+
+    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
+    """
+    if scope == ServiceScope.USER:
+        target_dir = Path.home() / ".config/systemd/user"
+        ctl = ["systemctl", "--user"]
+    elif scope == ServiceScope.SYSTEM:
+        _require_root("uninstall")
+        target_dir = SYSTEM_UNIT_DIR
+        ctl = ["systemctl"]
+    else:
+        print("⚠️  Invalid scope for uninstall.")
+        return
+
+    service_name = "pymidi-controller.service"
+    dst = target_dir / service_name
+
+    subprocess.run(ctl + ["stop", service_name], check=False)
+    subprocess.run(ctl + ["disable", service_name], check=False)
+
+    if dst.exists():
+        dst.unlink()
+        print(f"🗑️  Removed service unit at {dst}")
+    else:
+        print(f"⚠️  No service unit found at {dst}")
+
+    subprocess.run(ctl + ["daemon-reload"], check=True)
+    print("✅ Service uninstalled.")
+
+
+def stop(scope: ServiceScope = ServiceScope.USER):
+    """
+    Stop the systemd service.
+
+    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
+    """
+    cmd = ["systemctl"]
+    if scope == ServiceScope.USER:
+        cmd.insert(1, "--user")
+    cmd.append("stop")
+    cmd.append("pymidi-controller.service")
+    subprocess.run(cmd, check=True)
+    print("✅ Service stopped.")
+
+
+def enable(scope: ServiceScope = ServiceScope.USER):
+    """
+    Enable the systemd service.
+
+    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
+    """
+    cmd = ["systemctl"]
+    if scope == ServiceScope.USER:
+        cmd.insert(1, "--user")
+    cmd.extend(["enable", "pymidi-controller.service"])
+    subprocess.run(cmd, check=True)
+    print("✅ Service enabled.")
+
+
+def log(scope: ServiceScope = ServiceScope.USER):
+    """
+    Show the systemd service logs.
+
+    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
+    """
+    cmd = ["journalctl"]
+    if scope == ServiceScope.USER:
+        cmd.extend(["--user"])
+    cmd.extend(["-u", "pymidi-controller.service", "--no-pager"])
+    subprocess.run(cmd, check=True)
+    print("✅ Service logs displayed.")
+
+
+def dispatch(action: str, scope: ServiceScope = ServiceScope.USER):
+    """
+    Dispatcher for service subcommands.
+
+    :param action: one of 'install', 'uninstall', 'stop', 'enable', 'log'
+    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
+    """
+    if action == "install":
+        install(scope)
+    elif action == "uninstall":
+        uninstall(scope)
+    elif action == "stop":
+        stop(scope)
+    elif action == "enable":
+        enable(scope)
+    elif action == "log":
+        log(scope)
+    else:
+        print(f"⚠️  Unknown service action: {action}")

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1/pymidi_controller.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymidi-controller
-Version: 0.3.1
+Version: 0.4.1
 Summary: Daemon that maps MIDI events to system actions (Elgato, Hue, or custom functions).
 Author-email: Alex Sandilands <sandilands.alex@gmail.com>
 License-Expression: MIT
@@ -20,6 +20,8 @@ Requires-Dist: python-rtmidi>=1.4.10
 Requires-Dist: requests>=2.0
 Requires-Dist: zeroconf>=0.40
 Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
 Dynamic: license-file
 
 # 🎹 PyMIDI Controller
@@ -157,15 +159,17 @@ Use `pymidi <group> --help` for details on each context.
 
 ### Service
 
-| Command                             | Description                         |
-| ----------------------------------- | ----------------------------------- |
-| `pymidi service install --user`     | Install & start as a user service   |
-| `pymidi service install --system`   | Install & start system-wide service |
-| `pymidi service uninstall --user`   | Stop & remove user service          |
-| `pymidi service uninstall --system` | Stop & remove system service        |
-| `pymidi service stop`               | Stop the running service            |
-| `pymidi service enable`             | Enable service (user scope)         |
-| `pymidi service log`                | Tail service logs                   |
+| Command                                      | Description                         |
+| -------------------------------------------- | ----------------------------------- |
+| `pymidi service --user install`               | Install & start as a user service   |
+| `pymidi service --system install`             | Install & start system-wide service |
+| `pymidi service --user uninstall`             | Stop & remove user service          |
+| `pymidi service --system uninstall`           | Stop & remove system service        |
+| `pymidi service --user\|--system stop`        | Stop the running service            |
+| `pymidi service --user\|--system enable`      | Enable service                      |
+| `pymidi service --user\|--system log`         | Tail service logs                   |
+
+Every service subcommand requires a scope flag before the subcommand. Choose either `--user` or `--system` where the table shows `--user|--system`, for example `pymidi service --user stop`. `--system install` and `--system uninstall` must be run through `sudo`; see [System-wide install](#system-wide-install-headless).
 
 ### Hue Commands
 
@@ -303,21 +307,42 @@ bindings:
 To run automatically at login:
 
 ```bash
-pymidi service install --user
+pymidi service --user install
 ```
 
 The user service starts with your graphical session (`graphical-session.target`), after the desktop compositor is up. It does not pull that target in itself, so it can't make other autostart apps start early.
 
 If your window manager doesn't start `graphical-session.target` (Plasma and GNOME do; some minimal setups such as i3, sway or Hyprland don't unless configured to), the service won't start at login. Start the target from your session startup, e.g. `systemctl --user start graphical-session.target`.
 
-> **Upgrading from 0.3.0 or earlier?** Rerun `pymidi service install --user` (or `--system` for a system-wide install) once. It replaces the old unit and removes its stale `default.target` link. `pymidi service enable` alone doesn't refresh the unit file.
+> **Upgrading from 0.3.0 or earlier?** Rerun `pymidi service --user install` (or the `--system` command below for a system-wide install) once. It replaces the old unit and removes its stale `default.target` link. `pymidi service --user enable` alone doesn't refresh the unit file.
 
 Logs:
 
 ```bash
-pymidi service log
+pymidi service --user log
 ```
 
+### System-wide install (headless)
+
+The user service only starts with a graphical session. On a headless machine (a Raspberry Pi or server driving Hue or Elgato lights, say), install it system-wide so it starts at boot:
+
+```bash
+sudo "$(command -v pymidi)" service --system install
+```
+
+Start it through `sudo` from your own account: the service runs as the user named in `SUDO_USER`, which `sudo` sets (it also survives `sudo -i` and `sudo -s`). A root login, `su` or `doas` doesn't set it, so the command refuses to install rather than guess. `sudo` resets `PATH`, so pass the full path to `pymidi` as shown. The service reads that user's config from `~/.config/pymidi-controller`, and joins the `audio` group (when the system has one) so it can reach the ALSA sequencer without a login session. The unit records the Python interpreter that ran the install, so reinstall after moving or recreating a venv.
+
+A system service has no desktop session (no `DISPLAY`, `WAYLAND_DISPLAY` or session D-Bus), so bindings that launch desktop programs or use `notify-send` won't work. Use the `--user` service for those; Hue and Elgato actions over the network are fine.
+
+Logs and removal:
+
+```bash
+pymidi service --system log
+sudo "$(command -v pymidi)" service --system uninstall
+```
+
+> **Already have a `--system` install from 0.3.x?** Rerun the install command above once. The old unit ran as root and looked for `pymidi-controller` on a `PATH` that never included `~/.local/bin`, so it was unlikely to have worked; rerunning the install replaces the unit and restarts the service.
+
 ---
 
 ## 📜 License

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1}/pymidi_controller.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ MANIFEST.in
 README.md
 pyproject.toml
 pymidi_controller/__init__.py
+pymidi_controller/__main__.py
 pymidi_controller/cli.py
 pymidi_controller/config.py
 pymidi_controller/core.py
@@ -26,4 +27,6 @@ pymidi_controller/utils/config_manager.py
 pymidi_controller/utils/function_manager.py
 pymidi_controller/utils/midi_utils.py
 pymidi_controller/utils/service_manager.py
-pymidi_controller/utils/state_manager.py
+pymidi_controller/utils/state_manager.py
+tests/test_core.py
+tests/test_service_unit.py

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1}/pymidi_controller.egg-info/requires.txt

@@ -3,3 +3,6 @@ python-rtmidi>=1.4.10
 requests>=2.0
 zeroconf>=0.40
 PyYAML>=6.0
+
+[dev]
+pytest

{pymidi_controller-0.3.1 → pymidi_controller-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pymidi-controller"
-version = "0.3.1"
+version = "0.4.1"
 description = "Daemon that maps MIDI events to system actions (Elgato, Hue, or custom functions)."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "MIT"
@@ -26,6 +26,9 @@ classifiers = [
   "Topic :: Utilities"
 ]
 
+[project.optional-dependencies]
+dev = ["pytest"]
+
 [project.scripts]
 pymidi-controller = "pymidi_controller.cli:main"
 pymidi            = "pymidi_controller.cli:main"

pymidi_controller-0.4.1/tests/test_core.py

@@ -0,0 +1,38 @@
+import subprocess
+import sys
+
+import mido
+
+from pymidi_controller import core
+
+
+def _press(bindings, monkeypatch):
+    procs = []
+    real_popen = subprocess.Popen
+
+    def popen(cmd, **kwargs):
+        proc = real_popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+        procs.append((cmd, proc))
+        return proc
+
+    monkeypatch.setattr(core.subprocess, "Popen", popen)
+    msg = mido.Message("control_change", channel=0, control=99, value=1)
+    core.handle_midi_message(msg, bindings)
+    return procs
+
+
+def test_binding_runs_cli_through_current_interpreter(monkeypatch):
+    procs = _press({"control_change:0:99:1": ["hue", "--help"]}, monkeypatch)
+    [(cmd, _)] = procs
+    assert cmd == [sys.executable, "-m", "pymidi_controller", "hue", "--help"]
+
+
+def test_binding_runs_without_console_script_on_path(monkeypatch):
+    # The system service's PATH has no ~/.local/bin, so the action must not
+    # depend on finding the pymidi-controller script there
+    monkeypatch.setenv("PATH", "/nonexistent")
+    procs = _press({"control_change:0:99:1": ["--help"]}, monkeypatch)
+    [(_, proc)] = procs
+    out, _ = proc.communicate(timeout=30)
+    assert proc.returncode == 0, out
+    assert "usage:" in out

pymidi_controller-0.4.1/tests/test_service_unit.py

@@ -0,0 +1,181 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from pymidi_controller.utils import service_manager
+from pymidi_controller.utils.service_manager import ServiceScope, render_system_unit
+
+PY = "/opt/venv/bin/python"
+
+
+def _exec_start_line(unit):
+    return next(l for l in unit.splitlines() if l.startswith("ExecStart="))
+
+
+def test_unit_runs_as_given_user_with_audio_group():
+    unit = render_system_unit("alice", PY)
+    assert "\nUser=alice\n" in unit
+    assert "\nSupplementaryGroups=audio\n" in unit
+    assert "@" not in unit
+
+
+def test_unit_omits_audio_group_when_missing():
+    unit = render_system_unit("alice", PY, audio_group=False)
+    assert "SupplementaryGroups" not in unit
+    assert "@SUPPLEMENTARY_GROUPS@" not in unit
+    assert "\nUser=alice\nExecStart=" in unit
+
+
+def test_exec_start_uses_absolute_interpreter():
+    unit = render_system_unit("alice", PY)
+    assert _exec_start_line(unit) == f"ExecStart={PY} -m pymidi_controller run --mode blocking"
+
+
+def test_no_home_specifier_or_path_override():
+    # %h is /root in the system manager, so it must not appear
+    unit = render_system_unit("alice", PY)
+    assert "%h" not in unit
+    assert "Environment=PATH" not in unit
+
+
+@pytest.mark.parametrize(
+    "path, expected",
+    [
+        ("/home/a b/python", '"/home/a b/python"'),
+        ("/home/50%/python", "/home/50%%/python"),
+        ("/home/a b/50%/python", '"/home/a b/50%%/python"'),
+        ("/home/a$b/python", "/home/a$b/python"),
+    ],
+)
+def test_interpreter_path_is_escaped(path, expected):
+    unit = render_system_unit("alice", path)
+    assert _exec_start_line(unit) == f"ExecStart={expected} -m pymidi_controller run --mode blocking"
+
+
+@pytest.mark.skipif(shutil.which("systemd-analyze") is None, reason="systemd-analyze not available")
+@pytest.mark.parametrize("dirname", ["plain", "with space", "with%percent", "with space%and percent", "with$dollar", "with $dollar space"])
+def test_systemd_resolves_the_rendered_interpreter(tmp_path, dirname):
+    interpreter = tmp_path / dirname / "python"
+    interpreter.parent.mkdir()
+    interpreter.write_text("#!/bin/sh\n")
+    interpreter.chmod(0o755)
+    unit_file = tmp_path / "pymidi-controller.service"
+    unit_file.write_text(render_system_unit("alice", str(interpreter)))
+    out = subprocess.run(["systemd-analyze", "verify", str(unit_file)], capture_output=True, text=True)
+    assert "not executable" not in out.stdout + out.stderr
+    assert "quoting" not in (out.stdout + out.stderr).lower()
+
+
+@pytest.mark.parametrize("path", ["/tmp/o'x/python", '/tmp/q"x/python', "/tmp/b\\s/python"])
+def test_paths_systemd_cant_express_are_rejected(path):
+    with pytest.raises(ValueError):
+        render_system_unit("alice", path)
+
+
+@pytest.mark.parametrize("path", ["/tmp/a\nExecStartPre=/bin/evil", "/tmp/a\rb"])
+def test_control_characters_in_interpreter_path_are_rejected(path):
+    with pytest.raises(ValueError):
+        render_system_unit("alice", path)
+
+
+@pytest.mark.parametrize("user", ["", "a b", "alice\n", "a\nUser=root", "50%", "-lead", "a/b"])
+def test_unsupported_user_names_are_rejected(user):
+    with pytest.raises(ValueError):
+        render_system_unit(user, PY)
+
+
+@pytest.mark.parametrize("user", ["alice", "pi", "_svc", "first.last", "name-1", "machine$", "alice@corp.com"])
+def test_ordinary_user_names_are_accepted(user):
+    assert f"\nUser={user}\n" in render_system_unit(user, PY)
+
+
+# ---- install / uninstall -------------------------------------------------
+
+@pytest.fixture
+def calls(monkeypatch):
+    recorded = []
+    monkeypatch.setattr(subprocess, "run", lambda cmd, **kw: recorded.append(cmd))
+    return recorded
+
+
+def _as_root(monkeypatch, tmp_path, sudo_user="alice"):
+    monkeypatch.setattr(os, "geteuid", lambda: 0)
+    monkeypatch.setattr(service_manager, "SYSTEM_UNIT_DIR", tmp_path / "system")
+    monkeypatch.setattr(service_manager.sys, "executable", PY)
+    monkeypatch.setattr(service_manager.pwd, "getpwnam", lambda name: type("P", (), {"pw_gid": 1000})())
+    monkeypatch.setattr(service_manager, "_audio_group_exists", lambda: True)
+    monkeypatch.setattr(service_manager, "_warn_audio_group", lambda user: None)
+    if sudo_user is None:
+        monkeypatch.delenv("SUDO_USER", raising=False)
+    else:
+        monkeypatch.setenv("SUDO_USER", sudo_user)
+
+
+def test_system_install_writes_rendered_unit_and_restarts(monkeypatch, tmp_path, calls):
+    _as_root(monkeypatch, tmp_path)
+    service_manager.install(ServiceScope.SYSTEM)
+
+    unit = (tmp_path / "system" / "pymidi-controller.service").read_text()
+    assert unit == render_system_unit("alice", PY)
+    # restart, not just enable --now, so a running old instance is replaced
+    assert ["systemctl", "restart", "pymidi-controller.service"] in calls
+    assert calls.index(["systemctl", "daemon-reload"]) < calls.index(["systemctl", "restart", "pymidi-controller.service"])
+
+
+def test_system_install_omits_audio_group_line_when_group_missing(monkeypatch, tmp_path, calls):
+    _as_root(monkeypatch, tmp_path)
+    monkeypatch.setattr(service_manager, "_audio_group_exists", lambda: False)
+    service_manager.install(ServiceScope.SYSTEM)
+    assert "SupplementaryGroups" not in (tmp_path / "system" / "pymidi-controller.service").read_text()
+
+
+def test_system_uninstall_removes_unit(monkeypatch, tmp_path, calls):
+    _as_root(monkeypatch, tmp_path)
+    service_manager.install(ServiceScope.SYSTEM)
+    service_manager.uninstall(ServiceScope.SYSTEM)
+    assert not (tmp_path / "system" / "pymidi-controller.service").exists()
+    assert ["systemctl", "stop", "pymidi-controller.service"] in calls
+
+
+def test_user_install_still_copies_unmodified_unit(monkeypatch, tmp_path, calls):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    service_manager.install(ServiceScope.USER)
+    dst = tmp_path / ".config/systemd/user/pymidi-controller.service"
+    assert "graphical-session.target" in dst.read_text()
+    assert "@" not in dst.read_text()
+    assert ["systemctl", "--user", "restart", "pymidi-controller.service"] in calls
+
+
+def test_system_install_refuses_non_root(monkeypatch):
+    monkeypatch.setattr(os, "geteuid", lambda: 1000)
+    with pytest.raises(SystemExit) as exc:
+        service_manager.install(ServiceScope.SYSTEM)
+    assert "must run as root" in str(exc.value)
+
+
+def test_system_uninstall_refuses_non_root(monkeypatch):
+    monkeypatch.setattr(os, "geteuid", lambda: 1000)
+    with pytest.raises(SystemExit) as exc:
+        service_manager.uninstall(ServiceScope.SYSTEM)
+    assert "must run as root" in str(exc.value)
+
+
+@pytest.mark.parametrize("sudo_user", [None, "root"])
+def test_system_install_refuses_without_real_sudo_user(monkeypatch, tmp_path, sudo_user):
+    _as_root(monkeypatch, tmp_path, sudo_user)
+    with pytest.raises(SystemExit) as exc:
+        service_manager.install(ServiceScope.SYSTEM)
+    assert "which user" in str(exc.value)
+
+
+def test_system_install_refuses_unknown_sudo_user(monkeypatch, tmp_path):
+    _as_root(monkeypatch, tmp_path, "ghost")
+    def missing(name):
+        raise KeyError(name)
+    monkeypatch.setattr(service_manager.pwd, "getpwnam", missing)
+    with pytest.raises(SystemExit) as exc:
+        service_manager.install(ServiceScope.SYSTEM)
+    assert "isn't a known user" in str(exc.value)

pymidi_controller-0.3.1/pymidi_controller/utils/service_manager.py

@@ -1,140 +0,0 @@
-import shutil
-import subprocess
-from pathlib import Path
-from importlib import resources
-from enum import Enum, auto
-
-# -------------------------------------------------------------------
-# Service Installation & Management with Scoped Control
-# -------------------------------------------------------------------
-
-class ServiceScope(Enum):
-    USER = auto()
-    SYSTEM = auto()
-
-
-def install(scope: ServiceScope):
-    """
-    Install and enable the systemd service unit.
-
-    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
-    """
-    if scope == ServiceScope.USER:
-        target_dir = Path.home() / ".config/systemd/user"
-        ctl = ["systemctl", "--user"]
-        src_name = "pymidi-controller.service"
-    elif scope == ServiceScope.SYSTEM:
-        target_dir = Path("/etc/systemd/system")
-        ctl = ["systemctl"]
-        src_name = "pymidi-controller.system.service"
-    else:
-        print("⚠️  Invalid scope for install.")
-        return
-
-    target_dir.mkdir(parents=True, exist_ok=True)
-    src = resources.files("pymidi_controller") / "data/systemd" / src_name
-    dst = target_dir / "pymidi-controller.service"
-    shutil.copy(src, dst)
-    print(f"✔️  Installed service unit to {dst}")
-
-    subprocess.run(ctl + ["daemon-reload"], check=True)
-    # Drop links from older units (e.g. default.target.wants) before enabling
-    subprocess.run(ctl + ["disable", "pymidi-controller.service"], check=False)
-    subprocess.run(ctl + ["enable", "--now", "pymidi-controller.service"], check=True)
-    print("✅ Service enabled and started.")
-
-
-def uninstall(scope: ServiceScope):
-    """
-    Disable and remove the systemd service unit.
-
-    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
-    """
-    if scope == ServiceScope.USER:
-        target_dir = Path.home() / ".config/systemd/user"
-        ctl = ["systemctl", "--user"]
-    elif scope == ServiceScope.SYSTEM:
-        target_dir = Path("/etc/systemd/system")
-        ctl = ["systemctl"]
-    else:
-        print("⚠️  Invalid scope for uninstall.")
-        return
-
-    service_name = "pymidi-controller.service"
-    dst = target_dir / service_name
-
-    subprocess.run(ctl + ["stop", service_name], check=False)
-    subprocess.run(ctl + ["disable", service_name], check=False)
-
-    if dst.exists():
-        dst.unlink()
-        print(f"🗑️  Removed service unit at {dst}")
-    else:
-        print(f"⚠️  No service unit found at {dst}")
-
-    subprocess.run(ctl + ["daemon-reload"], check=True)
-    print("✅ Service uninstalled.")
-
-
-def stop(scope: ServiceScope = ServiceScope.USER):
-    """
-    Stop the systemd service.
-
-    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
-    """
-    cmd = ["systemctl"]
-    if scope == ServiceScope.USER:
-        cmd.insert(1, "--user")
-    cmd.append("stop")
-    cmd.append("pymidi-controller.service")
-    subprocess.run(cmd, check=True)
-    print("✅ Service stopped.")
-
-
-def enable(scope: ServiceScope = ServiceScope.USER):
-    """
-    Enable the systemd service.
-
-    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
-    """
-    cmd = ["systemctl"]
-    if scope == ServiceScope.USER:
-        cmd.insert(1, "--user")
-    cmd.extend(["enable", "pymidi-controller.service"])
-    subprocess.run(cmd, check=True)
-    print("✅ Service enabled.")
-
-
-def log(scope: ServiceScope = ServiceScope.USER):
-    """
-    Show the systemd service logs.
-
-    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
-    """
-    cmd = ["journalctl"]
-    if scope == ServiceScope.USER:
-        cmd.extend(["--user"])
-    cmd.extend(["-u", "pymidi-controller.service", "--no-pager"])
-    subprocess.run(cmd, check=True)
-    print("✅ Service logs displayed.")
-
-
-def dispatch(action: str, scope: ServiceScope = ServiceScope.USER):
-    """
-    Dispatcher for service subcommands.
-
-    :param action: one of 'install', 'uninstall', 'stop', 'enable', 'log'
-    :param scope: ServiceScope.USER or ServiceScope.SYSTEM
-    """
-    if action == "install":
-        install(scope)
-    elif action == "uninstall":
-        uninstall(scope)
-    elif action == "stop":
-        stop(scope)
-    elif action == "enable":
-        enable(scope)
-    elif action == "log":
-        log(scope)
-    else:
-        print(f"⚠️  Unknown service action: {action}")