Output & Formatting

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_cli/services/output.py
• src/flext_cli/_utilities/output.py
• src/flext_cli/_utilities/_output_parts/flextcliutilitiesoutput_part_01.py
• src/flext_cli/_utilities/_output_parts/flextcliutilitiesoutput_part_02.py
• examples/ex_01_getting_started.py
• examples/ex_11_complete_integration.py
• tests/_constants_parts/tests_yaml_output.py

The Output & Formatting module in flext-cli provides a unified, highly-structured API for presenting information to users via the command line. It acts as an abstraction layer over low-level rendering engines, such as the Rich library, to ensure visual consistency across the flext ecosystem. The system handles diverse output needs, ranging from simple styled text and debug messages to complex UI elements like progress bars, tables, panels, and quality gate results.

At its core, the architecture separates the high-level service API (FlextCliOutput) from the low-level formatting logic (FlextCliFormatters) and canonical utility functions (FlextCliUtilitiesOutput). This allows the project to maintain a "Single Source of Truth" (SSOT) for styles, emojis, and layouts, facilitating easier updates to the CLI's visual identity.

Sources: src/flext_cli/services/output.py:1-20, examples/README.md:12-25

Architecture Overview

The output system follows a tiered architecture where the public facade delegates to specialized services, which in turn use utility helpers to resolve styles and build canonical display payloads.

The diagram shows the delegation flow from the public API through the output service to specialized formatters and utilities.
Sources: src/flext_cli/services/output.py:13-25, src/flext_cli/_utilities/output.py:10-25

Core Components

FlextCliOutput Service

The FlextCliOutput class is the primary service providing a unified API. It contains static methods for displaying different types of content, ensuring that every message passes through a validation and styling resolution phase.

Method	Purpose
display_message	Displays styled messages (info, success, error, warning).
display_progress	Renders a progress indicator with labels and detail.
display_status	Shows a pass/fail status line with optional timing.
display_summary	Renders a summary panel showing total/success/failed counts.
display_gate	Displays results for quality gates (e.g., linting or tests).
display_debug	Prints messages only when verbose mode is enabled.

Sources: src/flext_cli/services/output.py:28-112

Utility Payloads and Styling

Styling is handled by u.Cli (implemented in FlextCliUtilitiesOutput). This component maps logical message types to specific visual styles and emojis.

The sequence diagram illustrates how styles and emojis are resolved before being sent to the final rendering engine.
Sources: src/flext_cli/_utilities/_output_parts/flextcliutilitiesoutput_part_01.py:34-51

Formatting Logic and Utilities

Progress and Status Indicators

The system uses standardized templates for progress and status reporting. This ensures that different CLI commands have a uniform appearance when performing long-running tasks.

• Progress Lines: Formatted as [current/total] label detail. The utility calculates the width needed for the total count to keep the display aligned.
• Status Lines: Use canonical symbols (e.g., SYMBOL_SUCCESS_MARK) and include elapsed time if provided.

Sources: src/flext_cli/_utilities/_output_parts/flextcliutilitiesoutput_part_01.py:53-63, src/flext_cli/_utilities/output.py:24-40

Reporting and Directories

For complex operations, flext-cli manages standardized report paths. The utilities resolve paths based on the workspace root, scope (e.g., workspace), and the specific action (verb) being performed.

Parameter	Type	Description
workspace_root	Path | str	The root directory of the project.
scope	str	The scope of the operation (e.g., workspace).
verb	str	The action being performed (e.g., test, lint).

Sources: src/flext_cli/_utilities/_output_parts/flextcliutilitiesoutput_part_02.py:73-89

Practical Examples

Integration in CLI Workflows

In a complete CLI application, the cli facade is used to print status updates and final tables. The following pattern demonstrates the integration of prompts, styled printing, and table display.

# From ex_11_complete_integration.py
cli.print(
    f"✅ Created entry: {key} = {value}",
    style=c.Cli.MessageStyles.GREEN,
)

cli.show_table(
    [{"Key": key, "Value": str(value)} for key, value in current_data.items()],
    headers=["Key", "Value"],
    title="📋 Current Data",
)

Sources: examples/ex_11_complete_integration.py:46-51, examples/ex_11_complete_integration.py:82-87

Summary Reporting

The display_summary method creates a visually distinct panel. This is typically used at the end of a command execution to provide a high-level result overview.

# Logic from FlextCliUtilitiesOutput
content = f"Total: {total}  Success: {success}  Failed: {failed}  Skipped: {skipped}"
# Rendered as a Rich Panel via FlextCliOutput.display_summary

Sources: src/flext_cli/_utilities/_output_parts/flextcliutilitiesoutput_part_01.py:65-74

Data Formatting Utilities

While visual output is the primary focus, the system also handles structured data formatting. FlextCliUtilitiesFiles contains logic to detect file formats and load them into normalized mappings.

• Format Detection: Detects formats (json, yaml, csv, bin) based on file extensions or content inspection.
• Auto-loading: The files_load_auto_mapping utility can automatically parse JSON or YAML files into a JsonMapping while normalizing values.

Sources: src/flext_cli/_utilities/_files_parts/flextcliutilitiesfiles_part_04.py:27-80

The Output & Formatting module ensures that developers can focus on logic while the system handles the complexities of terminal rendering, style consistency, and user feedback. By leveraging a centralized styling map and specialized services, flext-cli provides a professional and predictable user experience.