Global Configuration & Settings
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT-LDIF library utilizes a robust configuration management system based on Pydantic and environment variables to control enterprise LDIF processing. This system manages everything from low-level parsing behavior and RFC compliance to high-level migration strategies and batch processing orchestration.
The configuration architecture is divided into three primary layers:
- Infrastructure Layer: Managed by
settings.py, which handles environment variable loading and validation. - Domain/Model Layer: Defined in various
_settings_*.pymix-ins, providing typed schemas for complex operations like migration and transformation. - Cross-cutting Layer: Controlled by constants in
constants.pyand project-wide metadata inpyproject.toml.
Sources: src/README.md:27-40, src/flext_ldif/settings.py, pyproject.toml:23-35
Core Configuration Architecture
The settings system follows Clean Architecture principles, separating technical configuration concerns from domain logic. The central FlextLdifSettings class inherits from pydantic-settings to provide type-safe, environment-aware configuration.
The diagram shows how the main settings class orchestrates specialized configuration models for migration and processing.
Sources: src/flext_ldif/settings.py, src/flext_ldif/_models/_settings_migrate.py:16-20, src/flext_ldif/_models/_settings_processing.py:20-22
Environment Variables & Dependencies
The project leverages several Pydantic-related libraries to manage settings and data models, as defined in the project dependencies.
| Dependency | Purpose | Version |
|---|---|---|
pydantic | Core data validation and settings management | >=2.13.3 |
pydantic-settings | Environment variable loading for settings | >=2.14.0 |
ldap3 | Low-level LDAP protocol support | >=2.9.1 |
Sources: pyproject.toml:23-31
Migration & Formatting Options
The MigrateOptions and WriteFormatOptions classes provide granular control over how LDIF data is transformed and serialized. These settings support "Structured", "Categorized", and "Simple" migration modes.
Write Format Configuration
As of version 0.9.0, specific formatting options are transitioning into the global FlextLdifSettings.
| Option | Type | Description | Default |
|---|---|---|---|
line_width | int | Max width before line folding (RFC 2849 recommends 76) | 76 |
fold_long_lines | bool | Whether to fold lines according to RFC 2849 | True |
restore_original_format | bool | Enables perfect round-trip by using original metadata | False |
sort_attributes | bool | Alphabetically sorts attributes in output | False |
include_version_header | bool | Includes the version: 1 header in output | True |
Sources: src/flext_ldif/_models/_settings_migrate.py:84-142
Migration Mode Logic
The migration system determines the output structure based on which settings are provided in MigrateOptions.
The flow indicates the priority of migration modes based on configuration presence.
Sources: src/flext_ldif/_models/_settings_migrate.py:23-40
Processing & Transformation Settings
Processing operations are governed by ProcessConfig and TransformConfig, which manage batch execution and server-specific transformations.
Processing Controls (ProcessConfig)
- Batching:
batch_size(default: 100) defines entries per batch. - Resilience:
max_retries(default: 3) controls retry attempts on failure. - Timing:
timeout_seconds(default: 300) sets the maximum execution time. - Server Targeting:
source_serverandtarget_serveridentify the LDAP platforms involved in the operation.
Sources: src/flext_ldif/_models/_settings_processing.py:38-55
Transformation Behavior (TransformConfig)
This configuration determines how entries are modified during transit between servers.
fail_fast: IfTrue, stops the entire process on the first error.track_changes: Enables attribute-level auditing for changes.normalize_dns: Ensures Distinguished Names follow a canonical format during transformation.
Sources: src/flext_ldif/_models/_settings_processing.py:85-105
Domain Constants & Defaults
Global defaults and immutable rules are stored in FlextLdifConstants. These constants serve as the source of truth for RFC compliance and server-specific behaviors.
RFC & Binary Attribute Defaults
The system maintains a list of attributes that must be treated as binary data to ensure compliance with LDAP standards.
BINARY_ATTRIBUTE_NAMES: Final[frozenset[str]] = frozenset({
"usercertificate",
"cacertificate",
"photo",
"jpegphoto",
"objectguid",
"objectsid",
})
Sources: src/flext_ldif/constants.py:34-49
Server Validation Capabilities
Different LDAP servers have varying strictness requirements, which are configured globally.
| Server Type | Required Capabilities |
|---|---|
OID / OUD | requires_objectclass, requires_naming_attr, requires_binary_option |
OPENLDAP | requires_binary_option |
AD | requires_objectclass, requires_naming_attr |
Sources: src/flext_ldif/constants.py:53-78
Metadata Management Utilities
The FlextLdifUtilitiesMetadata class provides the logic for serializing configuration and metadata into JSON payloads. This is critical for maintaining state across processing stages and ensuring that settings are correctly propagated during migration.
Key Metadata Operations
- Dynamic Serialization:
dump_dynamic_metadataconverts typed mapping settings into a JSON string via theDynamicMetadatamodel. - Schema Analysis:
analyze_schema_formattingextracts spacing, quoting, and field ordering from raw schema definitions to preserve formatting in output. - Boolean Tracking:
track_boolean_conversionrecords conversions between server-specific formats (e.g., OID1/0) and RFC formats (TRUE/FALSE).
Sources: src/flext_ldif/_utilities/metadata.py:35-43, src/flext_ldif/_utilities/metadata.py:465-475, src/flext_ldif/_utilities/metadata.py:530-550
Conclusion
The Global Configuration & Settings system in FLEXT-LDIF provides a multi-layered approach to managing enterprise-grade LDIF operations. By combining environment-aware infrastructure settings with granular domain-level processing configurations and a centralized registry of RFC constants, the library ensures that data processing is both flexible and strictly compliant with LDAP standards.