Singleton Configuration Pattern
Relevant source files
The following files were used as context for generating this wiki page:
The Singleton Configuration Pattern in the flext-oracle-wms project provides a centralized, type-safe mechanism for managing Oracle WMS Cloud integration settings. This pattern ensures that configuration state is consistent across the application lifecycle, supporting environment-driven overrides, Pydantic-based validation, and global accessibility through the FLEXT ecosystem's containerization.
Sources: examples/02_singleton_config.py:1-12, src/README.md:95-103
Architecture and Components
The configuration architecture leverages FlextOracleWmsSettings as the primary data model. It extends the foundation patterns from flext-core to implement a singleton that can be initialized with defaults, updated with dynamic parameters, or reset to a fresh state.
Key Classes and Structures
| Component | Description |
|---|---|
FlextOracleWmsSettings | The core Pydantic-based settings class managing URL, credentials, and timeouts. |
FlextContainer | The shared registry used to bind and retrieve settings globally. |
FlextOracleWmsConstants | Provides default values (e.g., timeouts, retries) used during initialization. |
Sources: examples/02_singleton_config.py:25-45, src/flext_oracle_wms/README.md:38-41
Configuration Data Flow
The following diagram illustrates how configuration is resolved from environment variables and programmatically updated within the singleton instance.
The flow ensures that the FlextOracleWmsClient always operates on a validated, synchronized set of parameters retrieved from the shared container.
Sources: examples/01_basic_usage.py:47-65, examples/02_singleton_config.py:75-82
Implementation Details
Singleton Life Cycle
The singleton pattern allows developers to interact with settings in various stages, including initial load, runtime updates, and testing-specific overrides.
- Global Instance Access: Initializing
FlextOracleWmsSettings()without arguments retrieves the current global state. - Updating Parameters: Re-instantiating with new values (e.g.,
timeout=60) updates the existing singleton instance. - Testing Configuration: The
.testing_config()method provides a pre-configured instance suitable for unit tests. - Validation: The
.validate_config()method returns aFlextResult(r pattern) indicating if the current settings meet business rules.
Sources: examples/02_singleton_config.py:28-72
Environment Integration
Settings are automatically prefixed and loaded from environment variables using the FLEXT_ORACLE_WMS_ naming convention.
# Example Environment Variables
export FLEXT_ORACLE_WMS_BASE_URL="https://your-wms.oraclecloud.com"
export FLEXT_ORACLE_WMS_USERNAME="your_username"
export FLEXT_ORACLE_WMS_TIMEOUT="60"
Sources: examples/02_singleton_config.py:104-110, src/README.md:106-114
Dependency Injection and Containerization
The configuration is integrated into the FlextContainer to support dependency injection. This allows the client to be instantiated without explicitly passing settings if they have already been bound to the container.
This sequence demonstrates the decoupling of configuration definition from client usage.
Sources: examples/01_basic_usage.py:47-65, src/flext_oracle_wms/README.md:83-90
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
base_url | String | https://wms.oraclecloud.com | The Oracle WMS Cloud instance URL. |
username | String | Required | The authentication username. |
password | String | Required | The authentication password (masked in logs). |
timeout | Float | 30.0 | Request timeout in seconds. |
retry_attempts | Integer | 3 | Number of connection retry attempts. |
verify_ssl | Boolean | True | Whether to verify SSL certificates. |
Sources: src/README.md:106-114, examples/02_singleton_config.py:48-62, examples/03_complete_functionality_showcase.py:65-75
Conclusion
The Singleton Configuration Pattern serves as the "Single Source of Truth" (SSOT) for the library. By centralizing settings within FlextOracleWmsSettings and the FlextContainer, the project maintains architectural compliance with FLEXT standards, ensuring that configuration is immutable during specific execution slices but globally manageable for enterprise integration.
Sources: AGENTS.md:15-25, src/README.md:95-103