Data Parsers (JSON, TOML, YAML)

Relevant source files

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

• src/flext_cli/_utilities/yaml.py
• src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_06.py
• src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_01.py
• src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_04.py
• src/flext_cli/_utilities/_files_parts/flextcliutilitiesfiles_part_04.py
• src/flext_cli/_utilities/json.py
• examples/ex_04_file_operations.py

The Data Parsers in flext-cli provide a unified, typed interface for handling common configuration and data formats. These utilities are designed to support robust CLI applications by offering safe loading, validation via Pydantic adapters, and round-trip serialization that preserves document structure where possible.

The system is built on a "railway" pattern using p.Result, ensuring that file I/O and parsing errors are handled explicitly rather than through unmanaged exceptions. This module acts as the core infrastructure for project settings, deployment configurations, and general data persistence within the FLEXT ecosystem.

Sources: src/flext_cli/_utilities/yaml.py:1-15, examples/ex_04_file_operations.py:1-20

Architecture and Data Flow

The parsing infrastructure follows a layered approach where raw file contents are transformed into typed JsonMapping or TOMLDocument objects.

The diagram shows how files are processed from disk through format-specific parsers and validated before being returned as a Result type.
Sources: src/flext_cli/_utilities/_files_parts/flextcliutilitiesfiles_part_04.py:30-70, src/flext_cli/_utilities/yaml.py:38-65

YAML Parser Implementation

The FlextCliUtilitiesYaml class handles YAML operations using PyYAML's safe loading mechanisms. It emphasizes returning r[t.JsonMapping] to ensure the caller handles potential parse or validation failures.

Key YAML Methods

Method	Return Type	Description
yaml_safe_load(path)	p.Result[t.JsonMapping]	Reads a file and parses it as a mapping.
yaml_parse(text)	p.Result[t.JsonMapping]	Parses a YAML string and validates it against YAML_DICT_ADAPTER.
yaml_load_list(path)	t.SequenceOf[t.JsonValue]	Specifically parses top-level YAML lists, returning empty list on error.
yaml_dump(path, data)	p.Result[bool]	Serializes data to disk, creating parent directories automatically.

Sources: src/flext_cli/_utilities/yaml.py:31-135

TOML Parser Implementation

TOML support is split across multiple parts to handle both plain data mappings and sophisticated tomlkit document manipulations. This allows the CLI to modify files like pyproject.toml while preserving comments and formatting.

TOML Synchronization Flow

The TOML utilities provide unique "sync" capabilities, where a document is updated in-place only if the new data differs from the existing content.

This flow ensures minimal diffs when programmatically updating configuration files.
Sources: src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_05.py:31-60

Formatting and External Tools

The TOML parser integrates with taplo for formatting pyproject.toml files. When toml_write_document is called on a pyproject.toml, the utility attempts to resolve a .taplo.toml configuration and run the taplo format command.
Sources: src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_06.py:75-105

JSON Parser and Normalization

JSON utilities serve as the foundational contract for data exchange. The FlextCliUtilitiesJson class provides normalize_json_value, which ensures that complex Python objects are converted into types compatible with standard JSON/YAML/TOML serialization.

JSON Integration Pattern

def save_user_preferences(preferences: t.MappingKV[str, t.JsonPayloadCollectionValue], config_dir: Path) -> bool:
    config_file = config_dir / "preferences.json"
    
    # Normalize mapping into the CLI JSON contract before writing.
    write_result = cli.write_json_file(
        config_file,
        u.normalize_to_json_value(preferences),
    )
    return write_result.success

Sources: examples/ex_04_file_operations.py:27-46, src/flext_cli/_utilities/json.py

Automatic Format Detection

The utility files_load_auto_mapping provides a format-agnostic way to load data. It inspects file extensions and delegates to the appropriate parser.

Extension	Detected Format	Parser Delegated
.json	JSON	FlextCliUtilitiesJson.json_read
.yaml, .yml	YAML	FlextCliUtilitiesYaml.yaml_safe_load
.toml	TOML	FlextCliUtilitiesToml.toml_read_json

Sources: src/flext_cli/_utilities/_files_parts/flextcliutilitiesfiles_part_04.py:75-100

Conclusion

The Data Parsers in flext-cli provide a high-level abstraction over raw serialization libraries. By enforcing Pydantic validation and Result-based error handling, the system ensures that CLI applications remain resilient to malformed configuration files while maintaining the ability to perform complex, format-aware updates to project metadata.