Welcome to flext-ldap
Relevant source files
The following files were used as context for generating this wiki page:
flext-ldap is an enterprise-grade LDAP operations library built for the FLEXT framework. It provides a clean, maintainable, and type-safe interface for interacting with various LDAP servers, including OpenLDAP, Oracle Unified Directory (OUD), and Active Directory. The library is designed with Clean Architecture and Domain-Driven Design (DDD) principles, utilizing the r result pattern for explicit error handling and ensuring 100% module coverage for high reliability in production environments.
Sources: README.md:1-12, examples/README.md:21-27, pyproject.toml:29-38
Core Architecture and Principles
The system architecture follows a layered approach where the primary interface for developers is the ldap API (facade). It leverages structural typing via protocols to decouple service logic from specific third-party library implementations (like ldap3).
Key Design Principles
- API Facade: Developers should primarily interact with
api.py(exposed asldap). - Result Pattern: All operations return an
r(Result) object, forcing explicit success/failure checks. - Structural Typing: Extensive use of Python Protocols ensures independence from concrete model implementations.
- Type Safety: Optimized for Python 3.13+ with rigorous Pydantic validation.
Sources: examples/README.md:29-36, src/flext_ldap/protocols.py:20-40, README.md:27-30
System Component Overview
The following diagram illustrates the relationship between the public API, the protocol definitions, and the underlying adapters.
The architecture separates domain logic from infrastructure, allowing the library to support multiple LDAP server types through a unified interface.
Sources: src/flext_ldap/protocols.py:46-75, examples/README.md:535-555
Primary Components
1. Connection Management
Connections are managed through ConnectionConfig models and LdapClient protocols. The library supports standard LDAP, LDAPS (SSL), and StartTLS configurations.
| Parameter | Type | Default | Description |
|---|---|---|---|
host | str | "localhost" | LDAP server hostname |
port | int | 389 | LDAP server port |
use_ssl | bool | False | Enable SSL (LDAPS) |
use_tls | bool | False | Enable StartTLS |
timeout | int | 10 | Connection timeout in seconds |
auto_bind | bool | True | Automatically bind on connection |
Sources: src/flext_ldap/_models/ldap.py:20-43, src/flext_ldap/protocols.py:84-95
2. Search Operations
Search operations utilize SearchOptions to define the scope, filters, and requested attributes. Results are returned as SearchResult models containing a sequence of Entry objects.
3. Synchronization and Batch Operations
The FlextLdapSync module provides tools for large-scale data synchronization, supporting batch upserts with configurable retry logic and progress callbacks.
- Upsert Logic: Automatically determines if an entry should be added or modified.
- Batch Statistics: Tracks
synced,failed, andskippedcounts across phases. - Phase Configuration: Uses
SyncPhaseConfigto manage multi-phase migrations (e.g., "users" phase followed by "groups").
Sources: src/flext_ldap/_models/ldap.py:136-150, src/flext_ldap/protocols.py:101-106, src/flext_ldap/_models/ldap.py:171-182
Data Models
Entry Structure
Entries are derived from flext-ldif protocols to maintain consistency across the ecosystem. An entry consists of a Distinguished Name (DN) and an attribute mapping.
| Field | Type | Description |
|---|---|---|
dn | str | The Distinguished Name of the entry |
attributes | Mapping[str, StrSequence] | Attribute keys with lists of string values |
Sources: src/flext_ldap/protocols.py:79-82, src/flext_ldap/_models/ldap.py:238-245
Operational Results
Every modification or search operation returns a structured result.
class OperationResult(m.BaseModel):
success: bool
operation_type: str # ADD, MODIFY, DELETE
message: str
entries_affected: int
Sources: src/flext_ldap/_models/ldap.py:192-205, src/flext_ldap/protocols.py:133-142
Integration and Usage Patterns
The library is designed to be used with context managers to ensure graceful connection teardown and resource cleanup.
Standard Connection Flow
Conclusion
flext-ldap provides a robust, developer-friendly abstraction over LDAP protocols. By strictly adhering to the Result pattern and providing comprehensive models for search, sync, and ACL operations, it minimizes the risks associated with manual LDAP interaction and ensures compatibility across diverse enterprise directory services.
Sources: examples/README.md:656-670, README.md:7-10