Result Processing
Relevant source files
The following files were used as context for generating this wiki page:
Result Processing in flext-ldap is a multi-layered system responsible for converting raw LDAP responses from the underlying ldap3 library into normalized, type-safe Pydantic models. This system ensures that directory data—regardless of the specific LDAP server implementation (OpenLDAP, OUD, etc.)—is presented in a consistent format for the rest of the application.
The process involves extracting Distinguished Names (DNs), normalizing attribute values into string sequences, and capturing server metadata. This transformation is primarily handled by adapter mixins and specialized executors that validate operation success and structure results into models like SearchResult and OperationResult.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:12-25, src/flext_ldap/_models/ldap.py:207-220, tests/unit/test_ldap3_adapter_helpers.py:380-395
Core Components
Result Extraction Mixin
The ResultConverterExtractMixin serves as the primary utility for parsing raw objects. it handles various input types, including m.Ldif.Entry, p.Ldap.Ldap3Entry, and generic JSON-like mappings.
- DN Extraction: Normalizes Distinguished Names to
m.Ldif.DNmodels. If extraction fails or the input is null, it returns a canonical empty DN. - Attribute Extraction: Transforms raw LDAP attributes into
m.Ldif.Attributes. It utilizes internal normalization logic to ensure all values are stored as string sequences (t.StrSequence). - Metadata Extraction: Captures
ServerMetadata, such as the detected server type, from entry properties or mappings.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:16-95
Data Flow for Result Conversion
The following diagram illustrates how raw LDAP data is processed through the extraction mixin into structured models.
The diagram shows the transformation from a raw response to a fully validated SearchResult model.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:16-100, src/flext_ldap/_models/ldap.py:207-215
Result Models and Structures
The system uses several Pydantic models to represent the outcome of directory operations.
Search Results
The SearchResult model aggregates entries and provides computed properties for grouping and counting.
| Property | Type | Description |
|---|---|---|
entries | Sequence[m.Ldif.Entry] | List of processed directory entries. |
total_count | int | Computed field returning the number of entries. |
by_objectclass | m.Ldif.FlexibleCategories | Entries grouped by their primary objectClass. |
search_options | SearchOptions | The original parameters used for the search. |
Sources: src/flext_ldap/_models/ldap.py:207-230
Operation Results
For write operations (Add, Modify, Delete), the system returns an OperationResult or UpsertResult.
| Field | Type | Description |
|---|---|---|
success | bool | Indicates if the operation was successful. |
operation_type | str | The type of operation (e.g., ADD, DELETE). |
message | str | Descriptive message or error details. |
entries_affected | int | Number of directory entries impacted. |
Sources: src/flext_ldap/_models/ldap.py:188-205
Attribute Normalization Logic
A critical part of result processing is ensuring type consistency. LDAP values can arrive as bytes, integers, datetimes, or lists. The _normalize_attr_values method converts these into a uniform t.Ldap.OperationAttributes format.
- Scalars: Strings, integers, floats, and booleans are converted to strings and wrapped in a list.
- Bytes: Decoded to UTF-8 strings.
- Sequences: Iterated and converted using
FlextLdapLdap3Wrappers.value_to_str_list. - Nulls: Result in an empty list.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:110-132, tests/unit/test_ldap3_adapter_helpers.py:301-315
Normalization Mapping
The diagram describes the logic used by _normalize_attr_values to ensure all LDAP attributes conform to a list of strings.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:115-130
Batch and Sync Result Processing
When performing bulk operations or directory synchronization, the system aggregates individual results into summary models.
Sync Results Hierarchy
UpsertResult: Individual entry result (ADD/MODIFY/SKIP).BatchUpsertResult: Summary of a batch, including a computedsuccess_rate.PhaseSyncResult: Statistics for a specific synchronization phase (e.g., "Users").MultiPhaseSyncResult: Final aggregation of all phases, including total duration and overall success status.
Sources: src/flext_ldap/_models/ldap.py:136-180, tests/unit/test_models_sync.py:36-60
Implementation Details
Result Converter
The ResultConverter class provides high-level methods to process ldap3 connection results.
# From src/flext_ldap/adapters/_ldap3/result_converter.py (via test usage)
# Converted entries from a search response
converted_entries = ResultConverter.convert_parsed_entries(parsed_response)
Sources: tests/unit/test_ldap3_adapter_helpers.py:410-415
Execution Logic
The SearchExecutor and OperationExecutor classes encapsulate the call to the wrapper and the immediate processing of the response. They check for LDAP result codes (e.g., SUCCESS, NO_SUCH_OBJECT) and raise or return failure results based on the response payload.
Sources: tests/unit/test_ldap3_adapter_helpers.py:425-470
Summary
Result Processing in flext-ldap acts as a bridge between raw network responses and the domain-driven models of the library. By centralizing extraction and normalization logic in ResultConverterExtractMixin, the library provides a robust, testable, and server-agnostic way to handle LDAP data.
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:12-15, src/flext_ldap/_models/ldap.py:207-210