Python Multi Process Async-based Cooperative Discoverable Services 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.
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.
┌─────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────┘
pympacds provides:
- Process lifecycle —
ProcessBasewith setup/init/main/close, structured logging, signal handling, and named task management. - D-Bus transport —
DBusManageroverdbus-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, andMetricscontracts. - Middleware — optional lifecycle extensions (HTTP config provisioning, signal-action rules).
See Features and Philosophy for the full details.
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() pip install pympacdsFor minimal embedded deployments without the optional Cython extension:
SKIP_CYTHON=1 pip install --no-binary dbus-fast pympacdsNote: using pip doesn't install the system configurations files (it requires admin privileges to save D-Bus configurations). In order to work run sudo pympacds-admin setup before running services.
Debian packages are provided through launchpad ppa (dargor0/mpacds):
sudo add-apt-repository ppa:dargor0/mpacds
sudo apt update
sudo apt install python3-pympacdsPackages are installed system wide with all configurations and resource files (no need to do a setup step).
Repository has been tested on Ubuntu (plucky, resolute, stonking) and Debian (stable, testing, unstable).
Detailed documentation lives in the doc/ directory:
| 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 |
- dbus-fast — underlying D-Bus library
Release notes are published on the releases page.
MIT