@fake Connector¶

The @fake connector simulates execution locally without running anything, which is handy for demos, screenshots, documentation examples and tests.

Every command "succeeds" (exit code 0) with empty output by default. Specific responses can be scripted via the host fake_responses data, a mapping of a command matcher to a canned response.

The matcher (mapping key) is either:

• a str — matched as a substring of the command, or
• a compiled re.Pattern (re.compile(...)) — matched with pattern.search(command), so regular expressions are supported.

The response (mapping value) is either:

• a str / list[str] of stdout lines, or
• a dict with optional stdout (str/list), stderr (str/list) and success (bool) keys.

Matchers are tried in insertion order; the first match wins.

Each simulated command/transfer also takes a short, slightly randomised amount of time (so progress bars behave like a real deploy rather than finishing instantly). Tune this with the fake_delay / fake_delay_jitter host data, or the PYINFRA_FAKE_DELAY / PYINFRA_FAKE_DELAY_JITTER environment variables. Set the delay to 0 for instant execution (e.g. in tests).

Examples¶

Run any command or operation against one or more fake hosts, with no real target:

# A single fake host
pyinfra @fake exec -- echo "hello world"

# Multiple named fake hosts (comma separated)
pyinfra @fake/web-1,@fake/web-2 server.shell "echo hi"

Script what specific commands return with the fake_responses host data in an inventory file (inventory.py). Each key is a matcher, each value the canned response:

import re

hosts = [
    (
        "@fake/web-1",
        {
            "fake_responses": {
                # substring match
                "command -v git": {"success": False},
                "git --version": "git version 2.40.0",
                # regexp match (re.Pattern keys use pattern.search())
                re.compile(r"^apt-get .*install"): {
                    "success": False,
                    "stderr": "E: locked",
                },
            },
            # instant execution for this host
            "fake_delay": 0,
        },
    ),
]

A response value is either a str / list[str] of stdout lines, or a dict with optional stdout, stderr and success keys. Matchers are tried in insertion order; the first match wins, and unmatched commands succeed with no output.

Available Data¶

The following keys can be set as host or group data to control how this connector interacts with the target.