LDAP3 Adapter
Relevant source files
The following files were used as context for generating this wiki page:
The LDAP3 Adapter is a service adapter within the flext-ldap library that wraps the ldap3 library to provide a simplified, enterprise-grade interface for LDAP operations. It adheres to the project's library abstraction boundaries (AGENTS.md §2.7), serving as the sole owner of ldap3 imports and exposing functionality through the p.Ldap.LdapAdapter protocol.
The adapter handles the lifecycle of LDAP connections, conversion of directory entries to Pydantic models, and execution of CRUD operations (Add, Read, Modify, Delete). It utilizes a railway-oriented programming pattern (flat_map) to ensure robust error handling across operation chains.
Sources: src/flext_ldap/adapters/ldap3.py:1-25, src/flext_ldap/protocols.py:270-315
Architecture and Components
The adapter is structured as a host class FlextLdapLdap3Adapter that delegates specific responsibilities to specialized internal executors and managers.
Core Components Table
| Component | Responsibility |
|---|---|
ConnectionManager | Handles creation of ldap3.Server and ldap3.Connection objects and TLS negotiation. |
OperationExecutor | Executes LDAP write operations (Add, Modify, Delete). |
SearchExecutor | Manages LDAP search queries and result extraction. |
ResultConverter | Transforms raw ldap3 entry objects into m.Ldif.Entry models. |
FlextLdapLdap3Wrappers | Provides type-safe static wrappers for untyped or dynamically typed ldap3 methods. |
Sources: src/flext_ldap/adapters/ldap3.py:38-41, src/flext_ldap/adapters/_ldap3/wrappers.py:11-15
Relationship Diagram
The following diagram illustrates the relationship between the main adapter, its internal helpers, and the external ldap3 library.
Connection Lifecycle
The adapter manages connections through a structured flow: initialization, TLS negotiation, and binding.
- Server Creation: Uses
ConnectionManagerto instantiate a server with host and port settings. - Connection Creation: Instantiates an
ldap3.Connectionobject using the server and bind credentials. - TLS Handling: If configured,
handle_tlsinvokes thestart_tlsmethod viaFlextLdapLdap3Wrappers. - Binding: Verifies the connection is bound before allowing operations.
Data Transformation and Result Extraction
The adapter ensures that raw LDAP data is converted into strongly-typed Pydantic models. This is primarily handled by the ResultConverterExtractMixin.
Attribute Normalization
LDAP attributes can be returned in various formats (strings, bytes, lists, or integers). The extract_attrs_dict and _normalize_attr_values methods convert these into a consistent t.StrSequence format.
- Strings/Ints/Floats: Converted directly to string and wrapped in a list.
- Bytes: Decoded to string using the canonical utility.
- Lists/Tuples: Processed via
FlextLdapLdap3Wrappers.value_to_str_list.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:89-115, src/flext_ldap/adapters/_ldap3/wrappers.py:17-21
DN and Metadata Extraction
The adapter provides specific logic for extracting the Distinguished Name (DN) and Server Metadata:
- DN Extraction: Safely retrieves the
entry_dnproperty fromldap3.Entryobjects or uses them.Ldif.DNmodel if already parsed. - Metadata Extraction: Maps raw attribute mappings to the
m.Ldif.ServerMetadatamodel, filtering for primitive scalar values.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:22-42, src/flext_ldap/adapters/_ldap3/result_extract.py:70-87
LDAP Operations Flow
Operations are executed using a railway pattern that chains connection retrieval, data conversion, and execution.
Search Operation
The search operation maps high-level m.Ldap.SearchOptions to low-level ldap3 search parameters.
Modify Operation
The modify method accepts a DN and a dictionary of changes. Changes follow the ldap3 format: { 'attribute': [(operation, [values])] }.
Sources: src/flext_ldap/adapters/ldap3.py:136-142, src/flext_ldap/adapters/_ldap3/wrappers.py:65-70
Configuration and Models
The adapter relies on several core models for operation parameters:
| Model | Purpose | Key Fields |
|---|---|---|
ConnectionConfig | LDAP server connection settings | host, port, use_ssl, use_tls, bind_dn |
SearchOptions | Parameters for searching entries | base_dn, scope, filter_str, attributes |
OperationResult | Status of a write operation | success, operation_type, message, entries_affected |
SearchResult | Container for search outcomes | entries (List[Entry]), total_count |
Sources: src/flext_ldap/_models/ldap.py:18-47, src/flext_ldap/_models/ldap.py:68-83, src/flext_ldap/_models/ldap.py:214-228
Conclusion
The LDAP3 Adapter provides a decoupled, type-safe interface for LDAP interactions within the flext-ldap framework. By centralizing ldap3 specific logic in internal wrappers and executors, it protects the rest of the application from library-specific implementation details while ensuring consistent data models and robust error handling for enterprise directory operations.