pyinfra.api.facts module

The pyinfra facts API. Facts enable pyinfra to collect remote server state which is used to “diff” with the desired state, producing the final commands required for a deploy.

Note that the facts API does not use the global currently in context host so it’s possible to call facts on hosts out of context (ie give me the IP of this other host B while I operate on this host A).

class pyinfra.api.facts.FactBase

Bases: Generic[T]

abstract: bool = True

check_preconditions(state: State, host: Host) → str | None

Check that this fact’s prerequisites are satisfied before running.

Override this method to call host.get_fact(...) and return:

• None (or no return) — all prerequisites satisfied, proceed normally

• "reason message" — prerequisite not satisfied with explanation

The framework handles raising FactPreconditionError and phase-awareness automatically; fact authors never need to import exception classes.

command: Callable[[...], str | StringCommand]

static default() → T

Set the default attribute to be a type (eg list/dict).

name: str

process(output: list[str]) → T

process_pipeline(args, output)

requires_command(*args, **kwargs) → str | None

Return the binary name that must exist on the remote host for this fact to run. If the binary is absent the fact returns its default() value silently.

shell_executable: str | None = None

class pyinfra.api.facts.ShortFactBase

Bases: Generic[T]

fact: Type[FactBase]

name: str

process_data(data)

pyinfra.api.facts.get_fact(state: State, host: Host, cls: type[FactBase], args: Any | None = None, kwargs: Any | None = None, ensure_hosts: Any | None = None, apply_failed_hosts: bool = True) → Any

pyinfra.api.facts.get_facts(state, *args, **kwargs)

pyinfra.api.facts.get_short_facts(state: State, host: Host, short_fact, **kwargs)