systemd-pydantic

Pydantic models for systemd service and timer units.

Overview

systemd-pydantic provides typed, YAML-friendly models, lifecycle clients, and convenience commands for systemd. Its layers mirror supervisor-pydantic:

• ServiceConfiguration: [Service] settings, analogous to ProgramConfiguration
• ServiceUnitConfiguration and TimerUnitConfiguration: individual unit files
• SystemdConfiguration: named service and timer collections, file persistence, Hydra loading, and basic lifecycle methods
• SystemdConvenienceConfiguration: defaults and persisted JSON used by external tools such as Airflow
• SystemdClient: typed systemctl operations and UnitInfo state
• _systemd_convenience: lifecycle CLI for local or SSH-driven orchestration

Timer support lives in this package because timers share systemd's common [Unit] and [Install] sections and normally activate a matching service unit.

Configuration

from systemd_pydantic import ServiceConfiguration, ServiceUnitConfiguration, SystemdConfiguration

config = SystemdConfiguration(
    service={
        "long-running-job": ServiceUnitConfiguration(
            unit={"description": "Long-running Airflow job"},
            service=ServiceConfiguration(
                type="exec",
                exec_start="/opt/jobs/run",
                restart="on-failure",
                restart_sec="5s",
                environment={"MODE": "production"},
            ),
        )
    },
    scope="user",
)

config.write()

Dictionary input works identically, making the configuration suitable for YAML and Hydra:

# @package _global_

service:
  long-running-job:
    unit:
      description: Long-running Airflow job
    service:
      type: exec
      exec_start: /opt/jobs/run
      restart: on-failure
      restart_sec: 5s
      environment:
        MODE: production
scope: user

Timer values accept systemd time strings or Python timedelta values. Repeated calendar and monotonic triggers render as repeated directives, preserving systemd semantics.

scope="system" writes to /etc/systemd/system and calls systemctl. scope="user" writes to ~/.config/systemd/user and calls systemctl --user. The executing user must have permission to write the selected unit directory and control its systemd manager.

Lifecycle client

from systemd_pydantic import SystemdClient

client = SystemdClient(config)
client.daemon_reload()
client.start_services()

for unit in client.get_all_service_info().values():
    print(unit.name, unit.active_state, unit.result)

SystemdClient also supports stopping, restarting, killing, enabling, and disabling units. A custom CommandRunner can be injected for tests or remote execution.

Convenience CLI

SystemdConvenienceConfiguration persists its JSON representation alongside generated units. The _systemd_convenience CLI consumes that file and provides commands aligned with supervisor-pydantic:

configure-systemd
start-services
check-services
restart-services
stop-services
unconfigure-systemd

Systemd itself is already running, so there are intentionally no start-systemd or stop-systemd daemon commands.

[!NOTE] This library was generated using copier from the Base Python Project Template repository.