Public API Contract
Relevant source files
The following files were used as context for generating this wiki page:
The flext-ldap public API contract defines a frozen surface for enterprise LDAP operations within the FLEXT framework. It provides a high-level facade designed for type safety, maintainability, and server-agnosticism. The library follows a strict "zero ceremony" approach where the primary interaction occurs through a unified ldap instance or facade class, utilizing r result patterns for explicit error handling rather than standard exceptions.
Sources: src/flext_ldap/_exports.py, examples/README.md:21-25
Root Exports and Namespaces
The package root exposes a set of canonical aliases and facade classes that organize the library's functionality into logical namespaces. This structure ensures that domain-specific logic (models, constants, protocols) is separated while remaining easily accessible through short, standardized aliases.
Primary Facades and Aliases
| Alias | Full Class Reference | Purpose |
|---|---|---|
c | FlextLdapConstants | Shared LDAP constants (scopes, timeouts, defaults) |
m | FlextLdapModels | Pydantic models for entries, searches, and configurations |
p | FlextLdapProtocols | Structural typing contracts for DIP compliance |
s | FlextLdapService | Base service layer implementations |
t | FlextLdapTypes | Type aliases and sequence definitions |
u | FlextLdapUtilities | Shared helper functions and validation logic |
ldap | FlextLdap (instance) | The primary API facade instance for all operations |
Sources: src/flext_ldap/_exports.py:7-18, tests/unit/test_public_api_contract.py:53-72
Metadata and Versioning
The following attributes are exported at the root to provide project identity and versioning information:
__version__,__version_info____title__,__description____author__,__author_email__,__license__,__url__
Sources: src/flext_ldap/_exports.py:22-30
The FlextLdap Facade (MRO)
The FlextLdap class serves as the primary entry point. It utilizes a Method Resolution Order (MRO) based inheritance structure to compose functionality from specialized internal services.
The diagram shows the frozen inheritance hierarchy of the FlextLdap facade.
The ldap object provided by the library is a public instance of the FlextLdap facade, allowing for direct usage of all inherited methods without manual instantiation.
Sources: tests/unit/test_public_api_contract.py:77-87, tests/unit/test_api.py:16-18
Protocol-Based Integration
The library promotes the Dependency Inversion Principle (DIP) through FlextLdapProtocols. External services are encouraged to type against these structural protocols rather than concrete models to maintain decoupling.
Key Protocol Definitions
- LdapClient: Defines the standard interface for CRUD and batch operations.
- ConnectionConfig: Provides a structural contract for LDAP server connection parameters (host, port, SSL, etc.).
- SearchOptions: Standardizes parameters for search operations, including base DN, scope, and filters.
- Ldap3Connection: A structural contract for internal
ldap3compatibility, allowing for adapter swaps.
Sources: src/flext_ldap/protocols.py:44-50, src/flext_ldap/protocols.py:126-140
Architecture flow showing dependency on structural protocols for service boundaries.
Sources: src/flext_ldap/protocols.py:30-41
Operational Patterns
The API enforces specific patterns to ensure reliability in enterprise environments.
Context Management
The ldap facade implements the context manager protocol (__enter__ / __exit__), ensuring that connections are automatically closed and resources released.
from flext_ldap import ldap
with ldap as api:
api.connect()
# Perform operations
# Unbind is handled automatically on exit
Sources: tests/unit/test_api.py:21-26, examples/README.md:273-288
Result Handling with r
All LDAP operations return a Result object (aliased as r). This requires explicit checks for success or failure before unwrapping data, preventing unhandled exceptions from propagating through the domain logic.
result = api.search(search_options)
if result.is_failure:
# Handle error: result.error
return
entries = result.unwrap()
Sources: examples/README.md:290-305, src/flext_ldap/protocols.py:157-160
Conclusion
The flext-ldap Public API Contract is built on a foundation of structural typing, a composed facade hierarchy, and explicit result patterns. By exposing namespaced aliases (c, m, p, s, t, u) and a singleton ldap instance, the library provides a consistent and safe interface for interacting with diverse LDAP infrastructures while adhering to Clean Architecture principles.