## launchd


## launchd.AgentSpec


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


Usage

``` python
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

``` python
>>> 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

``` python
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

``` python
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

``` python
launchd.KeepAlive()
```


## launchd.AgentStatus


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


Usage

``` python
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

``` python
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

``` python
launchd.install(spec)
```


#### Raises


<a href="launchd.html#athome.launchd.LaunchdError" class="gdls-link gdls-code"><code>LaunchdError</code></a>  
`launchctl bootstrap` exited non-zero (stderr attached).


## launchd.uninstall()


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


Usage

``` python
launchd.uninstall(label)
```


#### Raises


<a href="launchd.html#athome.launchd.LaunchdError" class="gdls-link gdls-code"><code>LaunchdError</code></a>  
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](serve.md#athome.serve.ManagedServer.label)'s installed/running state by parsing `launchctl print gui/<uid>/<label>`.


Usage

``` python
launchd.status(label)
```


## launchd.installed()


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


Usage

``` python
launchd.installed(*, prefix="")
```


## launchd.LaunchdError


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


Usage

``` python
launchd.LaunchdError()
```