pympacds 0.1.0__tar.gz

pympacds-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: pympacds
+Version: 0.1.0
+Summary: Python Multi Process Asyncio-based Cooperative Discoverable Services Framework
+Author-email: Oscar Diaz <odiaz@ieee.org>
+License-Expression: MIT
+Keywords: dbus,asyncio,daemon,framework,embedded,ipc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dbus-fast
+Requires-Dist: dbus-fast>=4.0; extra == "dbus-fast"
+Provides-Extra: dbus-next
+Requires-Dist: dbus-next>=0.2; extra == "dbus-next"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: furo>=2023.9.10; extra == "docs"
+
+# pympacds
+
+**Py**thon **M**ulti **P**rocess **A**sync-based **C**ooperative **D**iscoverable **S**ervices Framework
+
+A lightweight, D-Bus-native application framework for building modular, multi-process, asyncio-based daemons on Linux — particularly suited for embedded and IoT systems.
+
+## Overview
+
+pympacds provides a common foundation for building systems composed of multiple cooperating daemons that communicate via D-Bus. Each daemon runs as an independent process (managed by systemd as a service), uses Python's `asyncio` for internal concurrency, and automatically discovers peer services on the D-Bus system bus.
+
+The framework is designed for any domain — IoT gateways, industrial control, home automation, automotive, robotics, or any Linux-based distributed system.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    D-Bus System Bus                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
+│  │ Service A │  │ Service B │  │ Service C │  │ Service D │   │
+│  │ (sensor)  │  │ (storage) │  │ (comm)    │  │ (ui)      │   │
+│  │ ProcessBase│ │ ProcessBase│ │ ProcessBase│ │ ProcessBase│  │
+│  │ DBusManager│ │ DBusManager│ │ DBusManager│ │ DBusManager│  │
+│  │ task1      │ │ task1      │ │ task1      │ │ task1      │  │
+│  │ task2      │ │ task2      │ │            │ │            │  │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
+│       │              │              │              │         │
+│  discover ←────────→ discover ←────→ discover ←──→ discover │
+│  (auto peer detection via NameOwnerChanged)                 │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                    ┌─────────┴──────────┐
+                    │    systemd (PID 1)  │
+                    │  service-a.service  │
+                    │  service-b.service  │
+                    │  service-c.service  │
+                    └────────────────────┘
+```
+
+## Features
+
+pympacds provides:
+
+- **Process lifecycle** — `ProcessBase` with setup/init/main/close, structured logging, signal handling, and named task management.
+- **D-Bus transport** — `DBusManager` over `dbus-fast`, configurable namespace prefix, and graceful disconnect.
+- **Service discovery** — automatic peer detection and dynamic subscribe/unsubscribe between services.
+- **Interface contracts** — validated D-Bus interface definitions, with built-in `Health`, `Lifecycle`, `Config`, and `Metrics` contracts.
+- **Middleware** — optional lifecycle extensions (e.g. HTTP config provisioning).
+
+See [Features and Philosophy](doc/features.md) for the full details.
+
+## Example: Minimal Service
+
+```python
+import asyncio
+import time
+from pympacds.process import ProcessBase
+from pympacds.dbus import DBusManager
+from pympacds.contracts import ServiceContract, dbus_method, dbus_signal
+
+
+class MyContract(ServiceContract):
+    def __init__(self, ifname, base):
+        super().__init__(ifname, base)
+        self._require("dbus_my_method")
+
+    @dbus_method()
+    def my_method(self, arg: "s") -> "s":
+        return self.base.dbus_my_method(arg)
+
+    @dbus_signal()
+    def heartbeat(self, uptime: "i") -> "i":
+        return [uptime]
+
+
+class MyService(ProcessBase):
+    def __init__(self):
+        super().__init__(
+            name="myservice",
+            version="1.0.0",
+            description="A minimal pympacds service",
+            bus_prefix="com.example.mysystem",
+        )
+
+    async def start_dbus(self):
+        self.bus = DBusManager(
+            logger=self.logger,
+            busname="myservice",
+            bus_prefix=self.bus_prefix,
+        )
+        self.iface = MyContract("com.example.MyInterface", self)
+        self.bus.add_interface("MyService", self.iface)
+        await self.bus.start()
+        return True
+
+    def update_tasks(self):
+        if "periodic" not in self.tasklist:
+            self.tasklist["periodic"] = asyncio.create_task(
+                self._periodic(), name="periodic"
+            )
+
+    def dbus_my_method(self, arg: str) -> str:
+        return f"Got: {arg}"
+
+    async def _periodic(self):
+        try:
+            while not self.exitevent.is_set():
+                await self.do_waitexit(timeout=5)
+                self.iface.heartbeat(int(time.time()))
+        except asyncio.CancelledError:
+            pass
+
+
+MyService().start()
+```
+
+## Installation
+
+```bash
+pip install pympacds
+```
+
+For minimal embedded deployments without the optional Cython extension:
+
+```bash
+SKIP_CYTHON=1 pip install --no-binary dbus-fast pympacds
+```
+
+## Documentation
+
+Detailed documentation lives in the [`doc/`](doc/) directory:
+
+- [Features and Philosophy](doc/features.md)
+- [Configuration](doc/config.md)
+- [Built-in Contracts](doc/contracts.md)
+- [Middleware](doc/middleware.md)
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Service** | A single-purpose daemon that subclasses `ProcessBase` and exports a D-Bus interface |
+| **Bus** | D-Bus system bus used as the IPC backbone between services |
+| **Discovery** | Automatic peer detection via bus name conventions and `NameOwnerChanged` signals |
+| **Interface Contract** | A standardized D-Bus interface template that enforces required callbacks at construction time |
+| **Task** | An asyncio coroutine managed inside a service's event loop |
+| **Lifecycle** | `setup → init_loop → main_loop → close_loop` pattern inherited from `ProcessBase` |
+
+## Related Work
+
+- [dbus-fast](https://github.com/Bluetooth-Devices/dbus-fast) — underlying D-Bus library
+
+## License
+
+MIT

pympacds-0.1.0/README.md

@@ -0,0 +1,154 @@
+# pympacds
+
+**Py**thon **M**ulti **P**rocess **A**sync-based **C**ooperative **D**iscoverable **S**ervices Framework
+
+A lightweight, D-Bus-native application framework for building modular, multi-process, asyncio-based daemons on Linux — particularly suited for embedded and IoT systems.
+
+## Overview
+
+pympacds provides a common foundation for building systems composed of multiple cooperating daemons that communicate via D-Bus. Each daemon runs as an independent process (managed by systemd as a service), uses Python's `asyncio` for internal concurrency, and automatically discovers peer services on the D-Bus system bus.
+
+The framework is designed for any domain — IoT gateways, industrial control, home automation, automotive, robotics, or any Linux-based distributed system.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    D-Bus System Bus                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
+│  │ Service A │  │ Service B │  │ Service C │  │ Service D │   │
+│  │ (sensor)  │  │ (storage) │  │ (comm)    │  │ (ui)      │   │
+│  │ ProcessBase│ │ ProcessBase│ │ ProcessBase│ │ ProcessBase│  │
+│  │ DBusManager│ │ DBusManager│ │ DBusManager│ │ DBusManager│  │
+│  │ task1      │ │ task1      │ │ task1      │ │ task1      │  │
+│  │ task2      │ │ task2      │ │            │ │            │  │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
+│       │              │              │              │         │
+│  discover ←────────→ discover ←────→ discover ←──→ discover │
+│  (auto peer detection via NameOwnerChanged)                 │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                    ┌─────────┴──────────┐
+                    │    systemd (PID 1)  │
+                    │  service-a.service  │
+                    │  service-b.service  │
+                    │  service-c.service  │
+                    └────────────────────┘
+```
+
+## Features
+
+pympacds provides:
+
+- **Process lifecycle** — `ProcessBase` with setup/init/main/close, structured logging, signal handling, and named task management.
+- **D-Bus transport** — `DBusManager` over `dbus-fast`, configurable namespace prefix, and graceful disconnect.
+- **Service discovery** — automatic peer detection and dynamic subscribe/unsubscribe between services.
+- **Interface contracts** — validated D-Bus interface definitions, with built-in `Health`, `Lifecycle`, `Config`, and `Metrics` contracts.
+- **Middleware** — optional lifecycle extensions (e.g. HTTP config provisioning).
+
+See [Features and Philosophy](doc/features.md) for the full details.
+
+## Example: Minimal Service
+
+```python
+import asyncio
+import time
+from pympacds.process import ProcessBase
+from pympacds.dbus import DBusManager
+from pympacds.contracts import ServiceContract, dbus_method, dbus_signal
+
+
+class MyContract(ServiceContract):
+    def __init__(self, ifname, base):
+        super().__init__(ifname, base)
+        self._require("dbus_my_method")
+
+    @dbus_method()
+    def my_method(self, arg: "s") -> "s":
+        return self.base.dbus_my_method(arg)
+
+    @dbus_signal()
+    def heartbeat(self, uptime: "i") -> "i":
+        return [uptime]
+
+
+class MyService(ProcessBase):
+    def __init__(self):
+        super().__init__(
+            name="myservice",
+            version="1.0.0",
+            description="A minimal pympacds service",
+            bus_prefix="com.example.mysystem",
+        )
+
+    async def start_dbus(self):
+        self.bus = DBusManager(
+            logger=self.logger,
+            busname="myservice",
+            bus_prefix=self.bus_prefix,
+        )
+        self.iface = MyContract("com.example.MyInterface", self)
+        self.bus.add_interface("MyService", self.iface)
+        await self.bus.start()
+        return True
+
+    def update_tasks(self):
+        if "periodic" not in self.tasklist:
+            self.tasklist["periodic"] = asyncio.create_task(
+                self._periodic(), name="periodic"
+            )
+
+    def dbus_my_method(self, arg: str) -> str:
+        return f"Got: {arg}"
+
+    async def _periodic(self):
+        try:
+            while not self.exitevent.is_set():
+                await self.do_waitexit(timeout=5)
+                self.iface.heartbeat(int(time.time()))
+        except asyncio.CancelledError:
+            pass
+
+
+MyService().start()
+```
+
+## Installation
+
+```bash
+pip install pympacds
+```
+
+For minimal embedded deployments without the optional Cython extension:
+
+```bash
+SKIP_CYTHON=1 pip install --no-binary dbus-fast pympacds
+```
+
+## Documentation
+
+Detailed documentation lives in the [`doc/`](doc/) directory:
+
+- [Features and Philosophy](doc/features.md)
+- [Configuration](doc/config.md)
+- [Built-in Contracts](doc/contracts.md)
+- [Middleware](doc/middleware.md)
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Service** | A single-purpose daemon that subclasses `ProcessBase` and exports a D-Bus interface |
+| **Bus** | D-Bus system bus used as the IPC backbone between services |
+| **Discovery** | Automatic peer detection via bus name conventions and `NameOwnerChanged` signals |
+| **Interface Contract** | A standardized D-Bus interface template that enforces required callbacks at construction time |
+| **Task** | An asyncio coroutine managed inside a service's event loop |
+| **Lifecycle** | `setup → init_loop → main_loop → close_loop` pattern inherited from `ProcessBase` |
+
+## Related Work
+
+- [dbus-fast](https://github.com/Bluetooth-Devices/dbus-fast) — underlying D-Bus library
+
+## License
+
+MIT

pympacds-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pympacds"
+version = "0.1.0"
+description = "Python Multi Process Asyncio-based Cooperative Discoverable Services Framework"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name="Oscar Diaz", email="odiaz@ieee.org"}
+]
+keywords = ["dbus", "asyncio", "daemon", "framework", "embedded", "ipc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+[project.scripts]
+pympacds-admin = "pympacds.cli:main"
+
+[project.optional-dependencies]
+dbus-fast = ["dbus-fast>=4.0"]
+dbus-next = ["dbus-next>=0.2"]
+dev = ["pytest", "pytest-asyncio", "mypy", "ruff"]
+docs = ["sphinx>=7.0", "myst-parser>=2.0", "furo>=2023.9.10"]
+
+[project.entry-points."pympacds.middleware"]
+httpconfprov = "pympacds.middleware:HttpConfigMiddleware"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+    "-v",
+    "--tb=short",
+]
+filterwarnings = [
+    # Third-party deprecation from PyGObject (triggered by the D-Bus library's
+    # GLib backend import); pympacds uses asyncio and does not use GLib.
+    "ignore:GLib.unix_signal_add_full is deprecated.*:gi.PyGIDeprecationWarning",
+]

pympacds-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pympacds-0.1.0/src/pympacds/__init__.py

@@ -0,0 +1,133 @@
+"""
+pympacds — Python Multi Process Asyncio-based Cooperative Discoverable Services Framework.
+
+A lightweight, D-Bus-native application framework for building modular,
+multi-process, asyncio-based daemons on Linux.
+"""
+
+import logging
+import os
+
+_logger = logging.getLogger(__name__)
+
+_DBUS_BACKEND: str | None = None
+_dbus_lib: object | None = None
+_dbus_aio: object | None = None
+_dbus_service: object | None = None
+
+_import_error_msg: str = "pympacds requires a D-Bus library. "\
+                "Install either 'dbus-fast' (recommended) or 'dbus-next':\n"\
+                "    pip install dbus-fast\n"\
+                "    pip install dbus-next"
+
+def _import_dbus() -> tuple[str, object, object, object]:
+    """Import the D-Bus library in priority order.
+
+    Tries ``dbus-fast`` first, then ``dbus-next``.  Set the environment
+    variable ``PYMPACDS_DBUS_BACKEND`` to ``dbus-fast`` or ``dbus-next``
+    to force a specific backend.
+
+    Returns:
+        Tuple of (backend_name, dbus_lib_module, dbus_aio_module, dbus_service_module).
+
+    Raises:
+        ImportError: If neither library is installed.
+    """
+    global _DBUS_BACKEND, _dbus_lib, _dbus_aio, _dbus_service
+
+    if _DBUS_BACKEND is not None:
+        return _DBUS_BACKEND, _dbus_lib, _dbus_aio, _dbus_service
+        
+    if os.environ.get("PYMPACDS_DBUS_BACKEND", "") == "dbus-fast":
+        # force dbus-fast
+        _try_dbus_fast_import(True)
+    elif os.environ.get("PYMPACDS_DBUS_BACKEND", "") == "dbus-next":
+        # force dbus-next
+        _try_dbus_next_import(True)
+    else:
+        # try first dbus-fast
+        if not _try_dbus_fast_import(False):
+            # then dbus-next
+            if not _try_dbus_next_import(False):
+                # neither, raise error
+                raise ImportError(_import_error_msg)
+
+    _logger.info("D-Bus backend: %s", _DBUS_BACKEND)
+    return _DBUS_BACKEND, _dbus_lib, _dbus_aio, _dbus_service
+    
+def _try_dbus_fast_import(doraise: bool) -> bool:
+    """Attempt to import ``dbus-fast``.
+
+    Args:
+        doraise: If True, raise ImportError instead of returning False.
+
+    Returns:
+        True if the import succeeded.
+    """
+    global _DBUS_BACKEND, _dbus_lib, _dbus_aio, _dbus_service
+    
+    try:
+        import dbus_fast as _dbus_lib
+        import dbus_fast.aio.message_bus as _dbus_aio
+        import dbus_fast.service as _dbus_service
+
+        _DBUS_BACKEND = "dbus-fast"
+    except ImportError:
+        if doraise:
+            raise ImportError(_import_error_msg)
+        return False
+    else:
+        return True
+        
+        
+def _try_dbus_next_import(doraise: bool) -> bool:
+    """Attempt to import ``dbus-next``.
+
+    Args:
+        doraise: If True, raise ImportError instead of returning False.
+
+    Returns:
+        True if the import succeeded.
+    """
+    global _DBUS_BACKEND, _dbus_lib, _dbus_aio, _dbus_service
+    
+    try:
+        import dbus_next as _dbus_lib
+        import dbus_next.aio.message_bus as _dbus_aio
+        import dbus_next.service as _dbus_service
+
+        _DBUS_BACKEND = "dbus-next"
+    except ImportError:
+        if doraise:
+            raise ImportError(_import_error_msg)
+        return False
+    else:
+        return True
+
+
+def get_dbus_backend() -> str:
+    """Return the active D-Bus library name (``"dbus-fast"`` or ``"dbus-next"``)."""
+    if _DBUS_BACKEND is None:
+        _import_dbus()
+    return _DBUS_BACKEND
+
+
+def get_dbus_lib() -> object:
+    """Return the active D-Bus library root module."""
+    if _dbus_lib is None:
+        _import_dbus()
+    return _dbus_lib
+
+
+def get_dbus_aio() -> object:
+    """Return the active D-Bus asyncio module."""
+    if _dbus_aio is None:
+        _import_dbus()
+    return _dbus_aio
+
+
+def get_dbus_service() -> object:
+    """Return the active D-Bus service module."""
+    if _dbus_service is None:
+        _import_dbus()
+    return _dbus_service

pympacds-0.1.0/src/pympacds/builtin_contracts.py

@@ -0,0 +1,129 @@
+"""Built-in D-Bus interface contracts.
+
+- HealthContract (enabled by default)
+- LifecycleContract, ConfigContract, MetricsContract (opt-in via [dbus] INI)
+"""
+
+from .contracts import ServiceContract, dbus_method, dbus_signal, dbus_property
+from . import get_dbus_lib
+
+_PropertyAccess = get_dbus_lib().PropertyAccess
+
+
+class HealthContract(ServiceContract):
+    """Service health and diagnostics.
+
+    Exported at the "health" relative object path automatically
+    when [dbus] contract_health = true (default).
+    """
+
+    iface_name = "Health"
+    iface_version = "1.0.0"
+    contract_type = "health"
+
+    def __init__(self, ifname: str, base):
+        super().__init__(ifname, base)
+        self._require(
+            "dbus_health_ping",
+            "dbus_health_status",
+            "dbus_health_get_uptime",
+        )
+
+    @dbus_method()
+    def ping(self) -> "b":
+        return self.base.dbus_health_ping()
+
+    @dbus_method()
+    def status(self) -> "s":
+        return self.base.dbus_health_status()
+
+    @dbus_signal()
+    def heartbeat(self, uptime: "i") -> "i":
+        return [uptime]
+
+    @dbus_property(access=_PropertyAccess.READ)
+    def uptime(self) -> "u":
+        return self.base.dbus_health_get_uptime()
+
+
+class LifecycleContract(ServiceContract):
+    """Remote restart and shutdown.
+
+    Exported when [dbus] contract_lifecycle = true.
+    """
+
+    iface_name = "Lifecycle"
+    iface_version = "1.0.0"
+    contract_type = "lifecycle"
+
+    def __init__(self, ifname: str, base):
+        super().__init__(ifname, base)
+        self._require(
+            "dbus_lifecycle_restart",
+            "dbus_lifecycle_shutdown",
+        )
+
+    @dbus_method()
+    def restart(self) -> "b":
+        return self.base.dbus_lifecycle_restart()
+
+    @dbus_method()
+    def shutdown(self) -> "b":
+        return self.base.dbus_lifecycle_shutdown()
+
+    @dbus_signal()
+    def state_changed(self, new_state: "s") -> "s":
+        return [new_state]
+
+
+class ConfigContract(ServiceContract):
+    """Runtime configuration management.
+
+    Exported when [dbus] contract_config = true.
+    """
+
+    iface_name = "Config"
+    iface_version = "1.0.0"
+    contract_type = "config"
+
+    def __init__(self, ifname: str, base):
+        super().__init__(ifname, base)
+        self._require(
+            "dbus_config_get",
+            "dbus_config_set",
+        )
+
+    @dbus_method()
+    def get_config(self, section: "s", key: "s") -> "s":
+        return self.base.dbus_config_get(section, key)
+
+    @dbus_method()
+    def set_config(self, section: "s", key: "s", value: "s") -> "b":
+        return self.base.dbus_config_set(section, key, value)
+
+    @dbus_signal()
+    def config_changed(self, section: "s", key: "s", value: "s") -> "sss":
+        return [section, key, value]
+
+
+class MetricsContract(ServiceContract):
+    """Operational metrics exposition.
+
+    Exported when [dbus] contract_metrics = true.
+    """
+
+    iface_name = "Metrics"
+    iface_version = "1.0.0"
+    contract_type = "metrics"
+
+    def __init__(self, ifname: str, base):
+        super().__init__(ifname, base)
+        self._require("dbus_metrics_get")
+
+    @dbus_method()
+    def get_metrics(self) -> "s":
+        return self.base.dbus_metrics_get()
+
+    @dbus_signal()
+    def metric_update(self, name: "s", value: "v") -> "sv":
+        return [name, value]