pympacds 0.1.0__py3-none-any.whl

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/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]