API Overview

​

Core Components

​

Operations & Deploys

• @operation - Decorator for creating custom operations
• @deploy - Decorator for creating reusable deploy functions
• add_op - Programmatically add operations to state
• add_deploy - Programmatically add deploys to state

​

State Management

• State - Manages the state of a pyinfra deployment
• Inventory - Represents a collection of target hosts
• Host - Represents a single target host
• Config - Configuration options for deployments

​

Commands

• StringCommand - Execute shell commands
• FileUploadCommand - Upload files to hosts
• FileDownloadCommand - Download files from hosts
• FunctionCommand - Execute Python functions
• RsyncCommand - Sync files using rsync

​

Connectors

• SSH - Connect via SSH (default)
• Local - Execute on local machine
• Docker - Execute in Docker containers
• Terraform - Generate inventory from Terraform
• Vagrant - Generate inventory from Vagrant

​

Facts

• Server Facts - System information
• File Facts - Filesystem information
• Package Facts - Package manager information

​

Quick Start

from pyinfra import Config, Inventory, State
from pyinfra.operations import server

# Create inventory with target hosts
inventory = Inventory(
    ([
        "server1.example.com",
        "server2.example.com",
    ], {})
)

# Create config
config = Config(
    SUDO=True,
)

# Initialize state
state = State(inventory, config)
state.init(inventory, config)

# Connect to hosts
for host in inventory:
    host.connect()

# Add operations
server.shell(
    name="Hello from pyinfra API!",
    commands=["echo 'Hello World'"],
    state=state,
    host=inventory,
)

# Execute operations
from pyinfra.api.operations import run_ops
run_ops(state)

​

CLI vs API Mode

• CLI Mode - When running pyinfra command-line tool
• API Mode - When using pyinfra as a Python library

• add_op() and add_deploy() should only be called in API mode
• Operations automatically execute immediately in API mode when called during the execute phase

​

Context Management

from pyinfra.context import ctx_state, ctx_host, ctx_config

# Access current context
state = ctx_state.get()
host = ctx_host.get()
config = ctx_config.get()

​

Type Safety

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pyinfra.api import State, Host

def my_deploy(state: "State", host: "Host") -> None:
    # Type-safe operations
    pass

​

Next Steps

• Operations - Create custom operations
• Deploy - Create reusable deploys
• State - Understand state management
• Host - Work with individual hosts
• Inventory - Manage host collections