Typing & Type Aliases

Relevant source files

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

• src/flext_target_ldap/models.py
• src/flext_target_ldap/settings.py
• src/flext_target_ldap/api.py
• tests/unit/test_sinks.py
• src/flext_target_ldap/_exports_lazy_part_01.py
• src/flext_target_ldap/init.py
• tests/typings.py

Typing in flext-target-ldap is a critical infrastructure component that ensures data integrity throughout the ETL pipeline, from incoming Singer messages to outgoing LDAP protocol operations. The project utilizes a centralized type registry, typically aliased as t, which consolidates project-specific types, inherited types from the FLEXT ecosystem (e.g., flext-core, flext-ldap), and standard Python types.

This system provides developers with strict contracts for configuration payloads, record structures, and domain models like LDAP entries and attribute mappings. By enforcing these types at the boundary of each module—such as Sinks, API Facades, and Settings—the target maintains high reliability and facilitates easier refactoring.

Centralized Type Alias Registry

The project follows the FLEXT convention of using a single-character alias t to represent the comprehensive type registry FlextTargetLdapTypes. This registry is exposed via lazy exports to improve initialization performance while maintaining full IDE support and type-checking capabilities.

Core Type Categories

The type system is divided into logical namespaces that mirror the responsibilities of the target.

Singer and Target Payloads

These types define the structure of data as it flows through the Singer protocol.

Type Alias	Base Type	Description
t.TargetLdap.SettingsPayload	Mapping[str, Any]	The raw configuration dictionary provided to the target.
t.TargetLdap.RecordPayload	Mapping[str, object]	A single data record from a Singer stream.
t.TargetLdap.SchemaPayload	dict[str, Any]	The JSON schema defining a stream's structure.
t.TargetLdap.CatalogPayload	dict[str, Any]	The Singer catalog metadata.

Sources: src/flext_target_ldap/api.py:34-40, tests/unit/test_sinks.py:27-30

LDAP Domain Specific Types

Used within models and client utilities to represent directory-specific structures.

• t.NonEmptyStr: A string type that must contain at least one character, used for Distinguished Names (DNs) and attribute names.
• t.MutableStrSequenceMapping: A mapping where keys are strings and values are lists of strings, specifically representing LDAP multi-valued attributes.
• t.Ldap.OperationAttributes: Specifically used in sink validation for LDAP operations.

Sources: src/flext_target_ldap/models.py:38-42, src/flext_target_ldap/models.py:126-130, tests/unit/test_sinks.py:124-128

Typing in Model Definitions

Domain models in src/flext_target_ldap/models.py utilize the type registry to define immutable value objects and entities. These models use Annotated types combined with Pydantic field validators for runtime enforcement.

Example: Attribute Mapping Typing

The AttributeMapping model defines how source fields are transformed into LDAP attributes:

• singer_field_name: Annotated[t.NonEmptyStr, ...]
• ldap_attribute_name: Annotated[t.NonEmptyStr, ...]
• is_required: bool
• transformation_rule: str | None

Sources: src/flext_target_ldap/models.py:38-65

Configuration Typing and Normalization

The FlextTargetLdapSettings class uses type aliases to define the expected configuration schema. It also includes a normalization layer that transforms flat Singer configuration into nested, typed structures.

• Connection Configuration: Uses m.Ldap.ConnectionConfig to type the connection field.
• Timeouts and Sizes: Uses t.PositiveInt for connect_timeout and t.BatchSize for batch_size.
• Normalization Logic: The normalize_flat_settings method converts raw t.MappingKV[str, t.JsonPayload | None] into the canonical nested shape required by the target.

Sources: src/flext_target_ldap/settings.py:35-40, src/flext_target_ldap/settings.py:118-140

Type Usage in Test Suites

The test infrastructure heavily relies on tests.typings.t to mock payloads and validate sink behavior. This ensures that test data remains synchronized with the implementation's type requirements.

# From tests/unit/test_sinks.py
@pytest.fixture
def ldap_base_sink(mock_target: MagicMock) -> LDAPBaseSink:
    schema: t.TargetLdap.SchemaPayload = {
        "properties": {"dn": {"type": "string"}, "cn": {"type": "string"}},
    }
    # ...

Sources: tests/unit/test_sinks.py:27-35, tests/unit/test_integration.py:32-35

Summary

The "Typing & Type Aliases" system in flext-target-ldap provides a robust, developer-friendly interface for handling complex data transformations. By centralizing types under the t alias and utilizing FLEXT ecosystem standards, the project achieves strict type safety across Singer stream processing, LDAP directory interactions, and Pydantic-based configuration management. This structure is foundational to the target's "zero-tolerance for code duplication" and "fail loud" engineering principles.