Usage Examples

Relevant source files

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

• examples/README.md
• src/flext_ldap/protocols.py
• tests/constants.py
• tests/unit/test_sync.py
• tests/unit/test_ldap3_adapter_helpers.py
• tests/utilities.py

The flext-ldap library provides a high-level API for enterprise LDAP operations, emphasizing clean architecture, type safety, and server-agnostic patterns. The primary interface for all operations is the ldap API (exposed via api.py), which abstracts complex LDAP interactions into manageable patterns like r results for error handling and standard configuration models.

Usage examples in this project cover fundamental CRUD operations, advanced search patterns, user authentication, and synchronization workflows. These examples are designed to follow FLEXT standards, ensuring 100% module coverage and demonstrating best practices such as connection management via context managers and input validation before execution.
Sources: examples/README.md:14-25, examples/README.md:520-525

Core Connection Patterns

Establishing and managing connections is the foundation of the library. Users can choose between manual lifecycle management or automated resource handling using context managers.

Basic Connection Management

Manual management involves creating a FlextLdapSettings object, initializing the API, and explicitly calling connect() and unbind(). Error handling is performed by checking the is_failure state of the returned result.

from flext_ldap import ldap
from flext_ldap import FlextLdapSettings

# Configuration
settings = FlextLdapSettings(
    ldap_server_uri="ldap://localhost:389",
    ldap_bind_dn="cn=admin,dc=example,dc=com",
    ldap_bind_password="password",
)
api = ldap()

# Lifecycle
result = api.connect()
if result.is_failure:
    print(f"Connection failed: {result.error}")
else:
    # Perform operations
    api.unbind()

Sources: examples/README.md:544-565

Context Manager Pattern

For more resilient applications, the context manager pattern ensures that connections are gracefully closed even if an exception occurs during execution.

The diagram shows the lifecycle of an LDAP connection when wrapped in a Python context manager to ensure resource cleanup.
Sources: examples/README.md:567-584

Data Operations

The library supports standard LDAP CRUD (Create, Read, Update, Delete) operations using type-safe models and structured requests.

Search and Filtering

Searches are performed using SearchRequest objects or direct parameters. The library supports standard scopes like BASE, ONE_LEVEL, and SUBTREE.

Scope	Description	ldap3 Value
BASE	Search only the base DN	BASE
ONE_LEVEL	Search immediate children of base DN	LEVEL(1)
SUBTREE	Search the base DN and all children	SUBTREE
SUBORDINATE	Search all children but not the base DN	SUBORDINATE

Sources: tests/constants.py:441-456, examples/README.md:89-98

Batch Operations and Synchronization

The library provides advanced utilities for bulk updates and LDIF-based synchronization. This is handled via the FlextLdapSync service, which supports multi-phase processing (e.g., syncing users followed by groups).

This flowchart illustrates the internal logic for processing a batch of LDAP entries from an LDIF source, including validation and progress tracking.
Sources: src/flext_ldap/protocols.py:126-140, tests/unit/test_sync.py:155-175

Configuration and Constants

Constants are organized into a flat namespace for use in data-driven testing and production configuration.

Constant Category	Example Keys	Source File
Field Names	HOST, PORT, BIND_DN, BASE_DN	tests/constants.py:38-47
Docker Defaults	DOCKER_PORT (3390), DOCKER_ADMIN_DN	tests/constants.py:125-131
Search Scenarios	PRESENT, EQUALITY, SUBSTRING	tests/constants.py:417-427
Result Codes	SUCCESS (0), NO_SUCH_OBJECT (32)	tests/unit/test_ldap3_adapter_helpers.py:205-212

Validation Best Practices

Before performing any LDAP operation, input data should be validated using FlextLdapValidations. This prevents common issues such as LDAP injection or malformed DNs.

1. Validate DNs: Ensure the Distinguished Name follows RFC standards before search or delete.
2. Validate Filters: Check syntax of LDAP filters before execution.
3. Handle Results: Always check result.is_failure before attempting to unwrap() the value.
4. Sanitize Inputs: Explicitly sanitize user-provided strings for use in filters.
   Sources: examples/README.md:596-613, examples/README.md:652-662

Conclusion

The Usage Examples section of flext-ldap demonstrates a robust approach to directory service management. By leveraging structural protocols and the r result pattern, developers can build resilient integrations that are compatible across multiple LDAP implementations including OpenLDAP and Oracle Unified Directory.
Sources: examples/README.md:27-30, src/flext_ldap/protocols.py:25-30