File Reading & Contexts

Relevant source files

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

• src/flext_tests/_utilities/_files/_reading.py
• src/flext_tests/_utilities/_files/_info.py
• src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py
• src/flext_tests/_models/_filesystem_parts/filesystem_part_02.py
• tests/unit/_files_parts/read.py
• tests/unit/_files_parts/info_cleanup.py
• tests/unit/_files_parts/contexts.py

The File Reading & Contexts module in the flext-tests ecosystem provides a robust infrastructure for managing temporary files and extracting comprehensive metadata during test execution. It abstracts low-level filesystem operations into a high-level API that supports automatic format detection, Pydantic model validation, and automated lifecycle management through context managers.

The system is designed to handle common data formats including JSON, YAML, and CSV, while providing detailed FileInfo and ContentMeta models. This ensures that test developers can easily create, read, and validate file-based artifacts without manually managing path cleanup or encoding complexities.

Sources: src/flext_tests/_utilities/_files/_reading.py, src/flext_tests/_utilities/_files/_info.py, tests/unit/_files_parts/contexts.py

File Reading Architecture

The reading logic is centered around the FlextTestsFilesReadingMixin, which provides a unified read() interface. This interface uses overload signatures to support both raw content retrieval and direct deserialization into Pydantic models.

Data Flow for File Reading

The following diagram illustrates the internal logic of the read() method, from parameter validation to format-specific parsing and optional model validation.

The system supports automatic detection of formats based on file extensions using the u.Cli.files_detect_format_from_path utility.

Sources: src/flext_tests/_utilities/_files/_reading.py:53-125

Read Parameters and Configuration

Reading operations are governed by ReadParams, which define how the filesystem should be accessed.

Parameter	Type	Default	Description
path	Path	Required	Absolute path to the file.
model_cls	type[m.BaseModel]	None	Optional Pydantic model for validation.
fmt	FileFormat	"auto"	Format override (json, yaml, csv, bin, text).
enc	str	"utf-8"	Text encoding used for reading.
delim	str	","	Delimiter for CSV parsing.
has_headers	bool	True	Whether CSV files contain a header row.

Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_02.py:21-45, src/flext_tests/_utilities/_files/_reading.py:80-90

File Metadata and Information

The module provides a comprehensive FileInfo model through the info() method. This method extracts filesystem-level attributes (stat data) and can optionally perform deep content inspection.

Metadata Extraction Logic

When info() is called, the system builds a FileInfo object containing:

• Stat Metadata: Size, permissions, creation/modification timestamps.
• Content Metadata: Detected encoding, line count, and the first line of the file.
• Integrity: Optional SHA256 hashing.
• Content Analysis: Optional parsing of JSON/YAML keys or CSV rows.

FileInfo Model Structure

The FileInfo model encapsulates the state of a file at a specific point in time.

Field	Type	Description
exists	bool	True if the file exists on disk.
size	int	File size in bytes.
lines	int	Number of lines (for text files).
fmt	str	Detected format label (e.g., "json", "csv").
is_readonly	bool	Derived from Unix permission bits.
content_meta	ContentMeta	Deep inspection data (keys, items, rows).

Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:21-65

Context Management and Lifecycle

A primary feature of the module is the tf.files() context manager, which handles the lifecycle of temporary test artifacts.

Temporary File Lifecycle

The context manager facilitates the following flow:

1. Creation: Files are created based on a mapping of filenames to content (strings, dicts, or models).
2. Execution: The paths to these temporary files are yielded to the test block.
3. Cleanup: Upon exiting the with block, all created files and their parent temporary directories are automatically unlinked/deleted.

# Usage Example
with tf.files({"config.json": {"key": "value"}}) as paths:
    path = paths["config.json"]
    assert path.exists()
# path is automatically deleted here

Sources: tests/unit/_files_parts/info_cleanup.py:91-105, tests/unit/_files_parts/contexts.py:18-29

Directory Tracking

The file manager (aliased as tf) tracks two internal collections to ensure clean teardown:

• created_files: A list of Path objects for every file generated.
• created_dirs: A list of temporary directories created to house these files.

Calling manager.cleanup() manually or exiting a context manager iterates through these collections, safely removing items even if they were already manually unlinked.

Sources: tests/unit/_files_parts/info_cleanup.py:59-83

Content-Specific Metadata (ContentMeta)

For structured files, the ContentMeta model provides insights without requiring the user to manually parse the file again.

Format	Metadata Extracted
JSON / YAML	key_count (for dicts), item_count (for lists).
CSV	row_count, column_count.
Model Validation	model_valid (boolean), model_name (class name).

Sources: src/flext_tests/_utilities/_files/_info.py:129-178, src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:67-85

Conclusion

The File Reading & Contexts module provides a high-level, type-safe abstraction for filesystem interactions within tests. By combining automatic format detection, Pydantic integration, and strictly managed lifecycles, it minimizes boilerplate and prevents "leaked" temporary files in the test environment. The inclusion of deep metadata extraction through FileInfo allows for precise assertions on file structure and integrity.