Tables Generation

Relevant source files

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

• src/flext_cli/services/tables.py
• src/flext_cli/_utilities/tables.py
• tests/unit/test_services_tables_cov.py
• tests/unit/test_tables.py
• tests/unit/test_tables_cov.py
• examples/ex_11_complete_integration.py

The Tables Generation system in flext-cli provides a high-performance, lightweight ASCII table formatting integration using the tabulate backend. It is designed to handle large datasets and plain text output, offering an alternative to more complex Rich-based tables when performance and simplicity are prioritized. The system exposes both string-returning formatting methods and direct console-rendering methods through a unified public API.

This module ensures that raw data—whether mappings or sequences—is validated and normalized into a standard format before rendering. It utilizes Pydantic-driven configuration models to manage table styles, alignments, and headers, ensuring type-safe interactions throughout the CLI application.

Sources: src/flext_cli/services/tables.py:1-12, src/flext_cli/_utilities/tables.py:1-15

Architecture and Data Flow

The table generation logic is split between a service layer (FlextCliTables) and a utility layer (FlextCliUtilitiesTables). The service layer provides the public interface, while the utility layer handles data normalization, configuration resolution, and the actual invocation of the tabulate library.

Processing Pipeline

The system follows a three-step railway-oriented processing pipeline:

1. Resolve Configuration: Merges optional settings models with keyword arguments to create a final TableConfig.
2. Normalize Data: Validates the input data source and converts various formats (dictionaries, lists of lists, lists of dicts) into a sequence of standardized rows.
3. Render Table: Passes the normalized rows and resolved configuration to the tabulate backend to produce a formatted ASCII string.

Core Service Methods

The FlextCliTables class acts as the primary integration point for table operations.

format_table

This method returns a Result[str]. It is intended for scenarios where the table content needs to be captured for logging, file writing, or further manipulation. It chains the configuration resolution, data normalization, and rendering steps using flat-mapping to preserve error context.
Sources: src/flext_cli/services/tables.py:17-27

show_table

This method renders the table and prints it directly to the console. It includes additional functionality to print a table title using bold styling and handles formatting errors by printing safe error messages to the standard output.
Sources: src/flext_cli/services/tables.py:30-54

Data Normalization and Handling

The utility layer is responsible for converting various Python data structures into a format compatible with tabulate.

Supported Data Sources

Input Type	Normalization Logic
Mapping (Dict)	Converted to a two-column table with "Key" and "Value" headers.
List of Mappings	Each mapping represents a row; keys are used to align columns if headers are provided.
List of Sequences	Each inner sequence represents a row of data.

Sources: src/flext_cli/_utilities/tables.py:73-105, tests/unit/test_tables_cov.py:65-85

Key Utility Functions

• tables_normalize_data(data): Uses a ValueAdapter for TableDataSource to validate input types before conversion. Sources: src/flext_cli/_utilities/tables.py:73-77
• tables_tabulate_payload(rows, headers): Specifically prepares the data and headers. If the rows are mappings and specific headers are requested, it extracts values in the correct order to ensure alignment. Sources: src/flext_cli/_utilities/tables.py:107-127
• tables_normalize_mapping_row(row): Ensures all values in a mapping are JSON-compatible (e.g., converting complex objects to strings). Sources: src/flext_cli/_utilities/tables.py:31-35

Configuration and Styling

Tables are styled using the m.Cli.TableConfig model. This model encapsulates all parameters passed to the tabulate backend.

TableConfig Parameters

Parameter	Description
table_backend_format	The ASCII style (e.g., plain, grid, pipe).
headers	A string identifier or a sequence of strings for column labels.
show_header	Boolean flag to toggle header visibility.
colalign	Sequence of strings (e.g., "left", "right") to align specific columns.
floatfmt	Format string for floating-point numbers.
title	Optional bold title printed above the table.

Sources: src/flext_cli/_utilities/tables.py:133-157, tests/unit/test_tables.py:20-25

Integration Example

In production CLI workflows, tables are often used to display the final state of a data processing task.

# From examples/ex_11_complete_integration.py
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:106-110

Summary

The Table Generation system provides a robust mechanism for ASCII data presentation. By separating the public API from the normalization logic, flext-cli ensures that developers can pass raw data structures directly to show_table or format_table without manual formatting. The integration with tabulate provides a wide variety of visual styles while maintaining high performance for large datasets.

Sources: src/flext_cli/services/tables.py:7-12, src/flext_cli/_utilities/tables.py:14-25