launchd

launchd.AgentSpec

A declarative launchd LaunchAgent: what to run, when, and where its logs go.

Usage

Source

launchd.AgentSpec(
    label,
    command,
    schedule,
    log_name=None,
    log_dir=None,
    working_dir=None,
    env=()
)

Parameter Attributes

label: str

command: tuple[str, …]

schedule: Schedule

log_name: str | None = None

log_dir: Path | None = None

working_dir: Path | None = None

env: tuple[tuple[str, str], …] = ()


Example

>>> spec = AgentSpec(
...     label="com.athome.batch-collect",
...     command=("athome", "batch", "collect"),
...     schedule=Calendar(hour=3, minute=0),
... )
>>> path = await install(spec)

launchd.Calendar

A wall-clock trigger: every day at hour:minute, or a single weekday (0=Sunday).

Usage

Source

launchd.Calendar(hour, minute, weekday=None)

Parameter Attributes

hour: int

minute: int

weekday: int | None = None

launchd.Interval

A relative trigger: fire every seconds since the last launch.

Usage

Source

launchd.Interval(seconds)

Parameter Attributes

seconds: int

launchd.KeepAlive

An always-on daemon: launchd respawns it whenever it exits, and runs it at load.

Usage

Source

launchd.KeepAlive()

launchd.AgentStatus

The live state of one agent: whether its plist is installed and its bootstrapped process running.

Usage

Source

launchd.AgentStatus(label, installed, running, pid, last_exit)

Parameter Attributes

label: str

installed: bool

running: bool

pid: int | None

last_exit: int | None

launchd.plist_dict()

Render spec to the launchd plist dictionary launchctl loads.

Usage

Source

launchd.plist_dict(spec)

launchd.install()

Write spec’s plist and (re)load it into the user’s GUI domain; return the plist path.

Usage

Source

launchd.install(spec)

Raises

LaunchdError

launchctl bootstrap exited non-zero (stderr attached).

launchd.uninstall()

Boot the agent out of the GUI domain and remove its plist.

Usage

Source

launchd.uninstall(label)

Raises

LaunchdError

the agent is still loaded after launchctl bootout, so its plist is kept rather than orphaning a live agent with no on-disk definition.

launchd.status()

Report label’s installed/running state by parsing launchctl print gui/<uid>/<label>.

Usage

Source

launchd.status(label)

launchd.installed()

List the labels of every athome-written LaunchAgent, optionally narrowed to those under prefix.

Usage

Source

launchd.installed(*, prefix="")

launchd.LaunchdError

Raised when a launchctl invocation fails — most often a non-zero bootstrap.

Usage

Source

launchd.LaunchdError()