Core Protocols & Typings

Relevant source files

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

• src/flext_tests/typings.py
• src/flext_tests/_typings/base.py
• src/flext_tests/_typings/matchers.py
• src/flext_tests/protocols.py
• src/flext_tests/_protocols/valuefactory.py
• src/flext_tests/_models/_matchers_parts/matchers_part_03.py
• src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py

The Core Protocols & Typings module provides the foundational type definitions, structural protocols, and validation adapters required for the FLEXT testing infrastructure. It establishes a unified type system for serializable test objects, result payloads, and matching rules, ensuring consistency across various testing utilities like builders, factories, and validators.

This module serves as the backbone for the project's strict typing strategy, utilizing Pydantic TypeAdapter instances and advanced Python type aliases to enforce data integrity during test execution. It defines how test data is represented, compared, and validated within the FLEXT ecosystem.

Sources: README.md:1-10, src/flext_tests/_typings/base.py:1-15

Type System Fundamentals

The system is built upon FlextTestsBaseTypesMixin, which defines the core atoms and collections allowed in the testing suite. These types distinguish between "serializable" objects and broader "result" values that may include complex system components.

Core Type Hierarchy

The hierarchy transitions from basic scalar "Atoms" to complex "Serializable" structures, and finally to "TestResultValues" which include active system interfaces like Loggers and Containers.

This diagram illustrates the promotion of types from basic serializable data to complex testable entities.
Sources: src/flext_tests/_typings/base.py:27-77

Primary Type Definitions

Type Alias	Description	Included Types
TestobjectAtom	Primitive values and basic objects.	str, int, float, bool, bytes, datetime, Path, m.BaseModel
TestobjectSerializable	Values safe for JSON/YAML serialization.	TestobjectAtom, Sequence, Mapping, None
TestResultValue	Broadest type for test outputs.	TestobjectSerializable, Enum, Logger, Container, Exception, ModuleType
Testobject	The standard interface for test data.	TestResultValue, p.ResultLike[TestResultValue]

Sources: src/flext_tests/_typings/base.py:27-86

Matcher & Validation Typings

The module defines specialized types for the "Universal Matcher" system, allowing for declarative rule definitions that include predicates, regex patterns, and nested structure matching.

Matching Rule Structures

The MatchRuleSpec allows developers to define expectations using direct values, types for instance checking, or complex mappings for deep attribute validation.

Key Matcher Types

• ItemSelector: Supports indexing into sequences via int or specialized strings like "first", "last", or "*" (wildcard).
• DeepMatchResult: A structured model representing the outcome of a deep comparison, containing the path, expected value, actual value, and a matched boolean.
• ComparableScalar: A union of float, int, and str used for range-based assertions (gt, lt, etc.).

Sources: src/flext_tests/_typings/matchers.py:44-80, src/flext_tests/_models/_matchers_parts/matchers_part_03.py:65-79

Infrastructure Protocols

Protocols define the expected behavior for core service components without requiring strict inheritance, facilitating easier mocking and replacement during tests.

Value Factories

The FlextTestsValueFactoryProtocolsMixin defines the interface for factories that generate test data.

Data Validation Adapters

To bridge the gap between static type hints and runtime validation, the module provides pre-configured Pydantic TypeAdapter instances. These are optimized for performance and consistency.

# From src/flext_tests/_typings/base.py
TESTOBJECT_SERIALIZABLE_MAPPING_ADAPTER: m.TypeAdapter[
    t.MappingKV[str, FlextTestsBaseTypesMixin.TestobjectSerializable]
] = m.TypeAdapter(
    t.MappingKV[str, TestobjectSerializable],
    config=m.ConfigDict(arbitrary_types_allowed=True),
)

Sources: src/flext_tests/_typings/base.py:102-108

Available Adapters

Adapter Name	Target Type	Configuration
TESTOBJECT_SEQUENCE_ADAPTER	Sequence[TestobjectSerializable]	arbitrary_types_allowed=True
STR_MAPPING_SEQUENCE_ADAPTER	Sequence[Mapping[str, str]]	Default
SCALAR_MAPPING_ADAPTER	Mapping[str, Scalar]	Default
INTEGER_SEQUENCE_ADAPTER	Sequence[int]	Default

Sources: src/flext_tests/_typings/base.py:88-125

Filesystem Model Integration

The typing system extends into the filesystem utilities, providing models for file metadata and creation parameters. These use Annotated types with descriptions for documentation and validation.

• FileInfo: Captures comprehensive file state including sha256, permissions, encoding, and size_human.
• ContentMeta: A specialized structure for parsed files that tracks row_count (CSV), key_count (JSON), and model_valid status.

Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:18-85

Conclusion

The "Core Protocols & Typings" module provides a rigorous foundation for the FLEXT ecosystem. By combining flexible type aliases for test data with strict Pydantic adapters and structural protocols, it ensures that test utilities remain robust and developer-friendly. This infrastructure enables complex declarative assertions and consistent data handling across the entire project.

Sources: src/flext_tests/_typings/base.py, src/flext_tests/_typings/matchers.py