Overview

Date: 2026-05-11

Time: 15:48

Overview

This is an example script demonstrating FTL2's output and progress control system. It shows how to configure verbosity levels (verbose, quiet, default), use event callbacks for structured event handling, and build custom progress displays. These controls let automation users choose between human-readable output during development and machine-processable events in production scripts.

Usage Patterns

Three output modes controlled via automation() context manager kwargs:

# Default — errors only, no output for successful operations
async with automation() as ftl:
    await ftl.file(path="/tmp/test.txt", state="touch")

# Verbose — shows every operation with timing
async with automation(verbose=True) as ftl:
    await ftl.command(cmd="echo hello")

# Quiet — suppresses all output; check results programmatically
async with automation(quiet=True) as ftl:
    await ftl.file(path="/tmp/test.txt", state="touch")
    success_count = sum(1 for r in ftl.results if r.success)

# Event callback — receive structured dicts per operation
async with automation(on_event=my_callback) as ftl:
    await ftl.command(cmd="echo hello")

# Quiet + events — silent execution with structured capture
async with automation(quiet=True, on_event=events.append) as ftl:
    ...

AutomationContext can also be instantiated directly to inspect output_mode:

ctx = AutomationContext(verbose=True)
print(ctx.output_mode)  # OutputMode enum value

API and Configuration

| Parameter | Type | Effect |

|-----------|------|--------|

| verbose=True | bool | Shows all operations with execution timing |

| quiet=True | bool | Suppresses all console output |

| on_event=callback | callable | Receives event dicts for each module start/complete |

Event dict fields: event ("modulestart" or "modulecomplete"), module, host, success, changed, duration (float, seconds), timestamp.

Result access: ftl.results — list of result objects with .success and .changed attributes, available after operations complete.

Output mode property: ftl.outputmode / context.outputmode — returns the current OutputMode enum value.

Key Behaviors

• Default mode shows nothing for successful operations — only errors surface. This means scripts that "work" produce no output unless you opt in.
• quiet=True and on_event can be combined — silent execution with full structured event capture. This is the recommended pattern for production scripts that need post-processing.
• Event callbacks fire synchronously during execution (not async) — the callback is a plain function, not a coroutine.
• ftl.results accumulates across all operations within a context block. It's available both inside and after the async with block.
• Events include both modulestart and modulecomplete — a custom progress display needs to filter on module_complete to avoid double-counting.

Relationships

• Imports: ftl2.automation (the automation context manager), ftl2.AutomationContext (direct instantiation), ftl2.automation.OutputMode (enum).
• Modules used: file (touch, absent, directory states) and command — the two most common FTL2 modules.
• Part of: Phase 5 in a progressive example series (phases 1–5 build up automation context features).
• Pattern reuse: The event callback + quiet mode pattern shown here is the basis for building custom TUIs, JSON log pipelines, or CI integrations on top of FTL2.