Base Classes

Relevant source files

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

• src/flext_ldap/protocols.py
• src/flext_ldap/_models/ldap.py
• examples/README.md
• README.md
• AGENTS.md
• pyproject.toml

Base classes and foundational structures in flext-ldap establish the enterprise-grade framework for LDAP operations. These components follow the FLEXT "domain" project class pattern, emphasizing clean architecture, structural typing via Python protocols, and Pydantic-based data validation. The architecture is designed to be server-agnostic, supporting standard RFC implementations alongside specific providers like OpenLDAP and Oracle Unified Directory (OUD).

The primary entry point for consumers is the api.py (ldap) facade, which leverages these base protocols and models to provide a unified interface for connection management, CRUD operations, and search functionality. The project adheres to strict quality gates, including 100% public API coverage and zero-debt baselines.

Sources: README.md:5-25, examples/README.md:15-30, AGENTS.md:1-50

Protocol-Driven Architecture

The core of flext-ldap relies on structural typing through protocols. This design decouples implementation details (such as specific LDAP client libraries like ldap3) from the domain logic. Protocols are organized into a tiered hierarchy to manage internal dependencies effectively.

Hierarchy Tiers

• Layer 0: Domain Protocols: Foundational definitions for DNs, Attributes, and Entries, largely inherited from flext-ldif.
• Layer 1: Service Protocols: High-level interfaces for LDAP clients and adapters that support CRUD operations.
• Layer 2: Handler Protocols: Specific execution logic built upon lower layers.

Sources: src/flext_ldap/protocols.py:27-44

Client and Adapter Protocols

The LdapClient and LdapAdapter protocols define the standard interface for interacting with LDAP servers. The LdapAdapter acts as a DIP (Dependency Inversion Principle) boundary, ensuring that the service layer depends on abstractions rather than concrete library implementations.

Data Models and Validation

flext-ldap utilizes Pydantic BaseModel to define rigid data structures for configurations and operation results. These models ensure that input parameters, such as search filters and connection strings, are validated before transmission to the LDAP server.

Connection Configuration

The ConnectionConfig model encapsulates the necessary parameters for establishing an LDAP session. It includes a validator to ensure that SSL and StartTLS are not used simultaneously, as they are mutually exclusive protocols.

Field	Type	Default	Description
host	str	localhost	LDAP server hostname
port	int	389	LDAP server port
use_ssl	bool	False	Enable LDAPS (SSL)
use_tls	bool	False	Enable StartTLS
timeout	int	30	Connection timeout in seconds
auto_bind	bool	True	Automatically bind on connection

Sources: src/flext_ldap/_models/ldap.py:20-56

Search and Operation Results

Operations return immutable result models that provide clear status information and metadata about the transaction.

class SearchOptions(m.BaseModel):
    """LDAP search parameters with validation."""
    base_dn: t.NonEmptyStr
    scope: str = c.Ldap.DEFAULT_SCOPE
    filter_str: str = c.Ldap.ALL_ENTRIES_FILTER
    attributes: t.StrSequence | None = None
    size_limit: t.NonNegativeInt = 0
    time_limit: t.NonNegativeInt = 0

Sources: src/flext_ldap/_models/ldap.py:72-85

Result Pattern and Statistics

The library implements a functional Result pattern (r-pattern) for error handling, avoiding traditional try/except blocks in the primary API surface. Batch operations additionally provide statistical models to track synchronization progress.

Batch Statistics Flow

When performing bulk updates or synchronizations, the system tracks successes, failures, and skips using namespaced models.

Structural Helper Protocols

To ensure compatibility with the underlying ldap3 library without tight coupling, the project defines structural "duck-typing" protocols. These allow the system to interact with objects that have specific methods or attributes, such as items() or attributes properties, regardless of their class inheritance.

• Ldap3Connection: Defines the required interface for the active connection object, including bind, search, and unbind callables.
• RootDseConnection: A specialized protocol for connections capable of querying the Root DSE (Directory Specific Entry).
• HasAttributesProperty: A protocol for objects exposing an attributes mapping, used for structural compatibility with varying entry formats.

Sources: src/flext_ldap/protocols.py:255-330, src/flext_ldap/protocols.py:350-380

Conclusion

The base classes and protocols of flext-ldap form a resilient foundation for enterprise LDAP integration. By utilizing structural typing and rigid data validation models, the project ensures that directory operations are predictable, server-agnostic, and maintainable. This architecture supports complex patterns like Domain-Driven Design (DDD) and the Repository pattern while maintaining strict adherence to the FLEXT framework standards.

Sources: README.md:1-10, examples/README.md:10-25