pymidi-controller 0.1.0__tar.gz → 0.3.0__tar.gz

{pymidi_controller-0.1.0/pymidi_controller.egg-info → pymidi_controller-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pymidi-controller
-Version: 0.1.0
-Summary: Daemon that maps MIDI events to system actions (Elgato, Hue, etc.)
+Version: 0.3.0
+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
 Project-URL: Homepage, https://github.com/AlexSandilands/pymidi-controller
@@ -43,6 +43,7 @@ A lightweight Python CLI and background MIDI listener for controlling Philips Hu
   - [Hue Commands](#hue-commands)
   - [Elgato Commands](#elgato-commands)
   - [MIDI Commands](#midi-commands)
+  - [Custom Function Commands](#custom-function-commands)
 - [🎹 MIDI Binding Guide](#-midi-binding-guide)
 - [⚙️ Service (Optional)](#️-service-optional)
 
@@ -149,10 +150,10 @@ Use `pymidi <group> --help` for details on each context.
 
 ### Global
 
-| Command       | Description                                 |
-| ------------- | ------------------------------------------- |
-| `pymidi init` | Create default config file                  |
-| `pymidi run`  | Start the MIDI listener (`--mode blocking`) |
+| Command                                        | Description                                 |
+| ---------------------------------------------- | ------------------------------------------- |
+| `pymidi init`                                  | Create default config file and function dir |
+| `pymidi run [--mode interactive \| blocking]`  | Start the MIDI listener (`--mode blocking`) |
 
 ### Service
 
@@ -194,6 +195,13 @@ Use `pymidi <group> --help` for details on each context.
 | -------------------- | ------------------------------------------ |
 | `pymidi midi listen` | Print incoming MIDI event keys for mapping |
 
+### Custom Function Commands
+
+| Command                                        | Description                                           |
+| ---------------------------------------------- | ----------------------------------------------------- |
+| `pymidi function list`                         | List all available custom functions                  |
+| `pymidi function run <name> [args...]`         | Run a custom function by name with optional arguments |
+
 ---
 
 ## 🎹 MIDI Binding Guide
@@ -219,6 +227,77 @@ Use `pymidi <group> --help` for details on each context.
 
 ---
 
+## 📜 Custom User Functions
+
+You can define your own Python functions to run on MIDI events. These live in:
+
+```
+~/.config/pymidi-controller/functions/
+```
+
+This directory is created by `pymidi init` and permissioned as `0700` (only accessible to your user).
+
+### Supported Formats
+
+#### Option 1: Single `.py` file
+
+**Structure:**
+
+```
+functions/
+└── my_function.py
+```
+
+**Content:**
+
+Note, the function must have a main() function, and this will be the entry point.
+
+```python
+def main(*args):
+    print("Hello from my_function", args)
+```
+
+#### Option 2: Package folder
+
+You can also use a subfolder with either an `__init__.py` or a `main.py`:
+These must have a main() function.
+
+**Structure A:**
+
+```
+functions/
+└── my_package/
+    └── __init__.py
+```
+
+**Structure B:**
+
+```
+functions/
+└── my_package/
+    └── main.py
+```
+
+**Content:**
+
+```python
+def main(*args):
+    print("Hello from package function", args)
+```
+
+Then bind it in your config:
+
+```yaml
+bindings:
+  control_change:0:10:127:
+    - custom
+    - my_function
+    - optional_arg1
+    - optional_arg2
+```
+
+---
+
 ## ⚙️ Service (Optional)
 
 To run automatically at login:

{pymidi_controller-0.1.0 → pymidi_controller-0.3.0}/README.md

@@ -19,6 +19,7 @@ A lightweight Python CLI and background MIDI listener for controlling Philips Hu
   - [Hue Commands](#hue-commands)
   - [Elgato Commands](#elgato-commands)
   - [MIDI Commands](#midi-commands)
+  - [Custom Function Commands](#custom-function-commands)
 - [🎹 MIDI Binding Guide](#-midi-binding-guide)
 - [⚙️ Service (Optional)](#️-service-optional)
 
@@ -125,10 +126,10 @@ Use `pymidi <group> --help` for details on each context.
 
 ### Global
 
-| Command       | Description                                 |
-| ------------- | ------------------------------------------- |
-| `pymidi init` | Create default config file                  |
-| `pymidi run`  | Start the MIDI listener (`--mode blocking`) |
+| Command                                        | Description                                 |
+| ---------------------------------------------- | ------------------------------------------- |
+| `pymidi init`                                  | Create default config file and function dir |
+| `pymidi run [--mode interactive \| blocking]`  | Start the MIDI listener (`--mode blocking`) |
 
 ### Service
 
@@ -170,6 +171,13 @@ Use `pymidi <group> --help` for details on each context.
 | -------------------- | ------------------------------------------ |
 | `pymidi midi listen` | Print incoming MIDI event keys for mapping |
 
+### Custom Function Commands
+
+| Command                                        | Description                                           |
+| ---------------------------------------------- | ----------------------------------------------------- |
+| `pymidi function list`                         | List all available custom functions                  |
+| `pymidi function run <name> [args...]`         | Run a custom function by name with optional arguments |
+
 ---
 
 ## 🎹 MIDI Binding Guide
@@ -195,6 +203,77 @@ Use `pymidi <group> --help` for details on each context.
 
 ---
 
+## 📜 Custom User Functions
+
+You can define your own Python functions to run on MIDI events. These live in:
+
+```
+~/.config/pymidi-controller/functions/
+```
+
+This directory is created by `pymidi init` and permissioned as `0700` (only accessible to your user).
+
+### Supported Formats
+
+#### Option 1: Single `.py` file
+
+**Structure:**
+
+```
+functions/
+└── my_function.py
+```
+
+**Content:**
+
+Note, the function must have a main() function, and this will be the entry point.
+
+```python
+def main(*args):
+    print("Hello from my_function", args)
+```
+
+#### Option 2: Package folder
+
+You can also use a subfolder with either an `__init__.py` or a `main.py`:
+These must have a main() function.
+
+**Structure A:**
+
+```
+functions/
+└── my_package/
+    └── __init__.py
+```
+
+**Structure B:**
+
+```
+functions/
+└── my_package/
+    └── main.py
+```
+
+**Content:**
+
+```python
+def main(*args):
+    print("Hello from package function", args)
+```
+
+Then bind it in your config:
+
+```yaml
+bindings:
+  control_change:0:10:127:
+    - custom
+    - my_function
+    - optional_arg1
+    - optional_arg2
+```
+
+---
+
 ## ⚙️ Service (Optional)
 
 To run automatically at login:

{pymidi_controller-0.1.0 → pymidi_controller-0.3.0}/pymidi_controller/cli.py

@@ -32,21 +32,32 @@ def main():
     # Service Commands
     # ----------------------------------------------------------------
     svc = subparsers.add_parser("service", help="Install or manage the systemd service")
+    scope_grp = svc.add_mutually_exclusive_group(required=True)
+    scope_grp.add_argument("--user",   action="store_true", help="Operate on the current user's service (~/.config/systemd/user)")
+    scope_grp.add_argument("--system", action="store_true", help="Operate on the system service (/etc/systemd/system)")
     svc_sub = svc.add_subparsers(dest="svc_cmd", required=True)
+
     # install
-    inst = svc_sub.add_parser("install", help="Install and enable the service unit")
-    inst_grp = inst.add_mutually_exclusive_group(required=True)
-    inst_grp.add_argument("--user", action="store_true", help="Install to user's systemd")
-    inst_grp.add_argument("--system", action="store_true", help="Install system-wide (requires sudo)")
+    svc_sub.add_parser("install",   help="Install and enable the service unit")
+
     # uninstall
-    uninst = svc_sub.add_parser("uninstall", help="Disable and remove the service unit")
-    uninst_grp = uninst.add_mutually_exclusive_group(required=True)
-    uninst_grp.add_argument("--user", action="store_true", help="Remove from user's systemd")
-    uninst_grp.add_argument("--system", action="store_true", help="Remove from system-wide systemd")
+    svc_sub.add_parser("uninstall", help="Disable and remove the service unit")
+
     # stop, enable, log
-    svc_sub.add_parser("stop", help="Stop the service")
+    svc_sub.add_parser("stop",   help="Stop the service")
     svc_sub.add_parser("enable", help="Enable the service")
-    svc_sub.add_parser("log", help="Show service logs")
+    svc_sub.add_parser("log",    help="Show service logs")
+
+    # ----------------------------------------------------------------
+    # Custom Function Commands
+    # ----------------------------------------------------------------
+    func = subparsers.add_parser("function", help="Custom function management")
+    func_sub = func.add_subparsers(dest="func_cmd", required=True)
+    func_sub.add_parser("list", help="List available custom functions")
+    # Run a custom function
+    run_func = func_sub.add_parser("run", help="Run a custom function")
+    run_func.add_argument("name", help="Name of the custom function to run")
+    run_func.add_argument("args", nargs=argparse.REMAINDER, help="Arguments to pass to the function")
 
     # ----------------------------------------------------------------
     # Hue Commands
@@ -102,6 +113,16 @@ def main():
         core_run(mode=args.mode)
         sys.exit(0)
 
+    if args.command == "function":
+        if args.func_cmd == "list":
+            from pymidi_controller.utils.function_manager import list_functions
+            list_functions()
+        elif args.func_cmd == "run":
+            from pymidi_controller.utils.function_manager import load_user_function
+            func = load_user_function(args.name)
+            func(*args.args)
+        sys.exit(0)
+
     if args.command == "service":
         scope = ServiceScope.USER if getattr(args, "user", False) else ServiceScope.SYSTEM
         service_dispatch(args.svc_cmd, scope)

{pymidi_controller-0.1.0 → pymidi_controller-0.3.0}/pymidi_controller/data/systemd/pymidi-controller.service

@@ -1,10 +1,12 @@
 [Unit]
 Description=🎹 MIDI Controller Background Service
-After=network.target
+After=graphical-session.target sound.target
+Wants=graphical-session.target sound.target
 
 [Service]
 Type=simple
 Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
+ExecStartPre=/bin/sleep 5
 ExecStart=/usr/bin/env pymidi-controller run --mode blocking
 Restart=always
 RestartSec=5

{pymidi_controller-0.1.0 → pymidi_controller-0.3.0}/pymidi_controller/utils/config_manager.py

@@ -7,6 +7,7 @@ from pathlib import Path
 XDG = Path.home() / ".config"  if "XDG_CONFIG_HOME" not in __import__("os").environ else Path(__import__("os").environ["XDG_CONFIG_HOME"])
 CFG_DIR  = XDG / "pymidi-controller"
 CFG_FILE = CFG_DIR / "config.yaml"
+FUNC_DIR = CFG_DIR / "functions"
 
 def ensure_config_dir():
     CFG_DIR.mkdir(parents=True, exist_ok=True)
@@ -30,10 +31,19 @@ def init_config():
     ensure_config_dir()
     data = resources.files("pymidi_controller").joinpath("data/default_config.yaml")
 
+    # Ensure the config file exists
     if not CFG_FILE.exists():
         CFG_FILE.write_text(data.read_text())
         os.chmod(CFG_FILE, 0o600)
         print(f"Created {CFG_FILE}, please discover your API keys & set midi mappings.")
     else:
         print(f"{CFG_FILE} already exists, skipping.")
-    return
+
+    # Ensure the functions directory exists
+    if not FUNC_DIR.exists():
+        FUNC_DIR.mkdir(parents=True)
+        os.chmod(FUNC_DIR, 0o700)
+        print(f"Created {FUNC_DIR}, please add your custom functions here.")
+    else:
+        print(f"{FUNC_DIR} already exists, skipping.")
+    

pymidi_controller-0.3.0/pymidi_controller/utils/function_manager.py

@@ -0,0 +1,74 @@
+import sys
+import importlib.util
+from types import ModuleType
+from pymidi_controller.utils.config_manager import FUNC_DIR
+
+CACHE: dict[str, tuple[ModuleType, float]] = {}  # name → (module, mtime)
+
+def _ensure_path():
+    """Ensure FUNC_DIR is on sys.path (for relative imports inside user modules)."""
+    if FUNC_DIR.exists() and str(FUNC_DIR) not in sys.path:
+        sys.path.insert(0, str(FUNC_DIR))
+
+def _load_module_from_path(name: str, path: str) -> ModuleType:
+    """Safely load a module from a specific file path."""
+    spec = importlib.util.spec_from_file_location(name, path)
+    if not spec or not spec.loader:
+        raise ImportError(f"Cannot load module '{name}' from {path}")
+    module = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(module)
+    except Exception as e:
+        raise RuntimeError(f"Error while executing module '{name}': {e}")
+    return module
+
+def load_user_function(name: str):
+    """Loads and returns the `main()` function from a user-defined module."""
+    _ensure_path()
+
+    # Locate the file on disk
+    file_py  = FUNC_DIR / f"{name}.py"
+    file_pkg = FUNC_DIR / name / "__init__.py"
+    file_alt = FUNC_DIR / name / "main.py"
+
+    filepath = None
+    for candidate in (file_py, file_pkg, file_alt):
+        if candidate.exists():
+            filepath = candidate
+            break
+
+    if filepath is None:
+        raise FileNotFoundError(f"No module '{name}' found in {FUNC_DIR}")
+
+    mtime = filepath.stat().st_mtime
+
+    # Load (or reload) the module from file
+    if name in CACHE:
+        _, cached_mtime = CACHE[name]
+        if mtime > cached_mtime:
+            module = _load_module_from_path(name, str(filepath))  # reload if changed
+            CACHE[name] = (module, mtime)
+        else:
+            module = CACHE[name][0]  # reuse cached module
+    else:
+        module = _load_module_from_path(name, str(filepath))
+        CACHE[name] = (module, mtime)
+
+    if not hasattr(module, "main") or not callable(module.main):
+        raise RuntimeError(f"User module '{name}' must define a callable main() function")
+
+    return module.main
+
+def list_functions():
+    """Prints available function modules in FUNC_DIR."""
+    _ensure_path()
+    if not FUNC_DIR.exists():
+        print(f"Function directory not found: {FUNC_DIR}")
+        return
+
+    print("Available functions:")
+    for path in FUNC_DIR.iterdir():
+        if path.is_dir() and ((path / "__init__.py").exists() or (path / "main.py").exists()):
+            print(f"  - {path.name}")
+        elif path.suffix == ".py":
+            print(f"  - {path.stem}")

{pymidi_controller-0.1.0 → pymidi_controller-0.3.0/pymidi_controller.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pymidi-controller
-Version: 0.1.0
-Summary: Daemon that maps MIDI events to system actions (Elgato, Hue, etc.)
+Version: 0.3.0
+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
 Project-URL: Homepage, https://github.com/AlexSandilands/pymidi-controller
@@ -43,6 +43,7 @@ A lightweight Python CLI and background MIDI listener for controlling Philips Hu
   - [Hue Commands](#hue-commands)
   - [Elgato Commands](#elgato-commands)
   - [MIDI Commands](#midi-commands)
+  - [Custom Function Commands](#custom-function-commands)
 - [🎹 MIDI Binding Guide](#-midi-binding-guide)
 - [⚙️ Service (Optional)](#️-service-optional)
 
@@ -149,10 +150,10 @@ Use `pymidi <group> --help` for details on each context.
 
 ### Global
 
-| Command       | Description                                 |
-| ------------- | ------------------------------------------- |
-| `pymidi init` | Create default config file                  |
-| `pymidi run`  | Start the MIDI listener (`--mode blocking`) |
+| Command                                        | Description                                 |
+| ---------------------------------------------- | ------------------------------------------- |
+| `pymidi init`                                  | Create default config file and function dir |
+| `pymidi run [--mode interactive \| blocking]`  | Start the MIDI listener (`--mode blocking`) |
 
 ### Service
 
@@ -194,6 +195,13 @@ Use `pymidi <group> --help` for details on each context.
 | -------------------- | ------------------------------------------ |
 | `pymidi midi listen` | Print incoming MIDI event keys for mapping |
 
+### Custom Function Commands
+
+| Command                                        | Description                                           |
+| ---------------------------------------------- | ----------------------------------------------------- |
+| `pymidi function list`                         | List all available custom functions                  |
+| `pymidi function run <name> [args...]`         | Run a custom function by name with optional arguments |
+
 ---
 
 ## 🎹 MIDI Binding Guide
@@ -219,6 +227,77 @@ Use `pymidi <group> --help` for details on each context.
 
 ---
 
+## 📜 Custom User Functions
+
+You can define your own Python functions to run on MIDI events. These live in:
+
+```
+~/.config/pymidi-controller/functions/
+```
+
+This directory is created by `pymidi init` and permissioned as `0700` (only accessible to your user).
+
+### Supported Formats
+
+#### Option 1: Single `.py` file
+
+**Structure:**
+
+```
+functions/
+└── my_function.py
+```
+
+**Content:**
+
+Note, the function must have a main() function, and this will be the entry point.
+
+```python
+def main(*args):
+    print("Hello from my_function", args)
+```
+
+#### Option 2: Package folder
+
+You can also use a subfolder with either an `__init__.py` or a `main.py`:
+These must have a main() function.
+
+**Structure A:**
+
+```
+functions/
+└── my_package/
+    └── __init__.py
+```
+
+**Structure B:**
+
+```
+functions/
+└── my_package/
+    └── main.py
+```
+
+**Content:**
+
+```python
+def main(*args):
+    print("Hello from package function", args)
+```
+
+Then bind it in your config:
+
+```yaml
+bindings:
+  control_change:0:10:127:
+    - custom
+    - my_function
+    - optional_arg1
+    - optional_arg2
+```
+
+---
+
 ## ⚙️ Service (Optional)
 
 To run automatically at login:

{pymidi_controller-0.1.0 → pymidi_controller-0.3.0}/pymidi_controller.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ pymidi_controller/data/systemd/pymidi-controller.service
 pymidi_controller/utils/__init__.py
 pymidi_controller/utils/color_cycle.py
 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-0.1.0 → pymidi_controller-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "pymidi-controller"
-version = "0.1.0"
-description = "Daemon that maps MIDI events to system actions (Elgato, Hue, etc.)"
+version = "0.3.0"
+description = "Daemon that maps MIDI events to system actions (Elgato, Hue, or custom functions)."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "MIT"
 license-files = ["LICENSE"]