Strict Type Definitions
Relevant source files
The following files were used as context for generating this wiki page:
Strict Type Definitions in the flext-dbt-ldap project represent a core architectural pillar ensuring data integrity and developer productivity across the LDAP-to-dbt transformation pipeline. By leveraging Python's typing module, Pydantic models, and runtime-checkable Protocols, the system enforces contract-based programming where data structures for LDAP entries, dbt configurations, and pipeline results are explicitly defined and validated.
This approach minimizes runtime errors by catching type mismatches during static analysis and provides a self-documenting interface for the various components of the integration. The type system bridges the gap between raw LDAP directory data and structured dbt models in the data warehouse.
Sources: pyproject.toml:19-24, AGENTS.md:65-67, src/flext_dbt_ldap/protocols.py:1-15
Core Type Architecture
The project's typing architecture is stratified into Protocols (defining behavior), Models (defining data structures), and Type Aliases. This multi-layered approach ensures that service components remain decoupled while sharing a common language for data exchange.
Behavioral Protocols
The system uses typing.Protocol with the @runtime_checkable decorator to define service contracts. This allows for structural subtyping where any class implementing the required methods is considered a valid implementation of the protocol.
The diagram above illustrates the hierarchical structure of the dbt LDAP protocols used to define service interfaces.
Sources: src/flext_dbt_ldap/protocols.py:22-110
Configuration Models
Strict typing is applied to dbt project and execution configurations using Pydantic-based models. These models include metadata through Annotated and Field for documentation and validation purposes.
| Component | Class Name | Key Fields | Purpose |
|---|---|---|---|
| Project Config | DbtProjectConfig | name, version, model_paths, target_path | Defines the dbt project structure and locations. |
| Source Definition | DbtSourceDefinition | name, tables, description | Declares raw LDAP sources for dbt ingestion. |
| Execution Config | DbtConfig | target, profiles_dir, project_dir | Controls runtime parameters for dbt commands. |
Sources: src/flext_dbt_ldap/_models/configuration.py:16-95
Result and Metric Typing
Execution results and data quality metrics are strictly typed to ensure predictable reporting and automated decision-making (e.g., stopping a pipeline if quality thresholds are not met).
Data Quality Validation Metrics
The ValidationMetrics model captures the health of LDAP data before it enters the dbt transformation layer.
class ValidationMetrics(m.Value):
"""Validation metrics for LDAP data quality."""
total_entries: Annotated[t.NonNegativeInt, u.Field(description="Total LDAP entries")] = 0
valid_dns: Annotated[t.NonNegativeInt, u.Field(description="Entries with valid DNs")] = 0
valid_entries: Annotated[t.NonNegativeInt, u.Field(description="Entries satisfying required attributes")] = 0
quality_score: Annotated[t.NonNegativeFloat, u.Field(description="Validation quality score")] = 0.0
validation_passed: Annotated[bool, u.Field(description="Threshold compliance")] = False
Sources: src/flext_dbt_ldap/_models/results.py:16-35, src/flext_dbt_ldap/services/client.py:126-155
Transformation Helpers and Typed Dimensions
The transformation logic uses typed dimension models to convert raw LDAP Ldif.Entry objects into structured dbt-ready formats. This is managed by integration utilities that enforce type safety during the mapping process.
The flow shows how raw LDAP entries are processed through typed transformation helpers to produce validated dbt dimensions.
Sources: src/flext_dbt_ldap/_utilities/integration.py:22-65
Key Transformation Methods
transform_users: Converts LDAP entries toUserDimension.transform_groups: Converts LDAP entries toGroupDimension.transform_memberships: Converts entries toMembershipFact.
Sources: src/flext_dbt_ldap/_utilities/integration.py:25-50
Type Enforcement Policy
The project follows a "Zero-Tolerance / Strict-Total" typing policy as defined in the engineering guidelines. This includes:
- Restrictive Typing: Using the most restrictive type that compiles.
- No Escape Hatches: Prohibiting the use of
Any, bareobject, or unchecked casts. - Source-Level Fixes: Requiring type errors to be fixed at the source rather than suppressed.
- Mypy and Pyright Integration: The project uses
mypyandpyrightfor static type checking with strict configurations.
Sources: AGENTS.md:21-25, AGENTS.md:65-67, pyproject.toml:135-155, pyproject.toml:234-265
Summary
Strict Type Definitions in flext-dbt-ldap provide a robust framework for managing complex LDAP data within dbt workflows. By combining Pydantic models for configuration and results with runtime-checkable protocols for service interfaces, the system ensures that every stage of the data pipeline is governed by clear, enforceable contracts. This leads to higher code quality, easier refactoring, and more reliable data transformations.