Overview

Date: 2026-05-11

Time: 15:43

Overview

This is a comprehensive example/demo script showing how to use FTL2's local module execution system (ftl2.ftlmodules). It demonstrates both the synchronous direct-call API (calling module functions like ftlfile, ftlcopy, ftlcommand, ftlshell directly) and the async executor API (execute, executebatch, executeonhosts, run). The script emphasizes FTL2's 250x+ speedup over Ansible's subprocess-based module execution by running modules in-process.

Usage Patterns

Direct synchronous module calls — simplest way to use FTL modules:

from ftl2.ftl_modules import ftl_file, ftl_copy, ftl_command, ftl_shell

# File operations (create, touch, delete)
result = ftl_file(path="/tmp/mydir", state="directory")
result = ftl_file(path="/tmp/myfile", state="touch")
result = ftl_file(path="/tmp/myfile", state="absent")

# Copy with optional backup
result = ftl_copy(src="/tmp/a.txt", dest="/tmp/b.txt", backup=True)

# Command execution (no shell interpretation)
result = ftl_command(cmd="echo hello", chdir="/tmp", creates="/tmp/marker")

# Shell execution (supports pipes, env vars)
result = ftl_shell(cmd="echo $HOME | wc -c")

Async executor API — for concurrent and multi-host execution:

from ftl2.ftl_modules import execute, execute_batch, execute_on_hosts, run, LocalHost

# Single module execution
result = await execute("file", {"path": "/tmp/test", "state": "touch"})
# result.success, result.changed, result.module, result.used_ftl

# Convenience wrapper
result = await run("command", cmd="date")

# Batch concurrent execution
tasks = [
    ("file", {"path": "/tmp/f1", "state": "touch"}, None),
    ("command", {"cmd": "echo hi"}, None),
]
results = await execute_batch(tasks)

# Parallel execution across hosts
hosts = [LocalHost(name=f"worker-{i}") for i in range(5)]
results = await execute_on_hosts(hosts, "command", {"cmd": "echo hello"})

API and Configuration

Direct module functions return plain dicts with keys: changed, path/src/dest/stdout/rc, state, mode, backup_file.

Executor API returns result objects with attributes: success, changed, module, used_ftl, output (dict), error, host.

Key parameters by module:

• ftl_file: path, state (directory|touch|file|absent)
• ftl_copy: src, dest, backup (bool)
• ftl_command: cmd, chdir, creates (skip if file exists — idempotency)
• ftl_shell: cmd (supports pipes and env var expansion)
• executebatch: list of (modulename, paramsdict, hostor_none) tuples

Key Behaviors

• Idempotency: Modules track changed status. Touching an existing file or copying identical content returns changed=False. The creates parameter on ftl_command skips execution if the target file already exists.
• Error handling: Failed commands return success=False with error message and rc in output. Non-existent modules return success=False with used_ftl=False. Errors don't raise exceptions — they're captured in result objects.
• Shell vs Command: ftlcommand runs commands directly (no shell interpretation). ftlshell runs through a shell, supporting pipes (|) and environment variable expansion ($HOME).
• Backup on copy: ftl_copy with backup=True preserves the previous version before overwriting.

Relationships

• Imports from: ftl2.ftl_modules — the core local module execution engine
• Module functions: ftlfile, ftlcopy, ftlcommand, ftlshell are the synchronous direct-call API
• Executor layer: execute, executebatch, executeon_hosts, run, LocalHost provide async orchestration on top of the same modules
• LocalHost: Represents a local execution target for executeonhosts, enabling the same API pattern used for remote hosts to work locally
• Located in: examples/ directory of the FTL2 repo — a reference for users, not production code