Error Handling & Exceptions
Relevant source files
The following files were used as context for generating this wiki page:
The flext-oracle-wms library implements an enterprise-grade error handling strategy that combines traditional Python exception hierarchies with Railway-Oriented Programming (ROP) patterns. This dual approach ensures that the system provides both robust runtime protection and consistent business logic flow for data integration pipelines.
The primary goal of the error handling system is to categorize Oracle WMS Cloud-specific issues—such as authentication failures, connection timeouts, and validation errors—into a structured format that integrates seamlessly with the broader FLEXT ecosystem. This allows developers to handle errors gracefully whether they prefer try-except blocks or functional result processing.
Sources: src/README.md:37-41, src/flext_oracle_wms/README.md:46-50
Exception Hierarchy
The library provides a comprehensive exception hierarchy rooted in FlextOracleWmsError. This structure allows for granular error catching based on the specific failure mode of the Oracle WMS integration.
Core Exception Classes
| Exception Class | Description |
|---|---|
FlextOracleWmsError | The base exception for all library-specific errors. |
FlextOracleWmsValidationError | Raised when input parameters or configuration fail validation rules. |
FlextOracleWmsConnectionError | Raised during network-level failures or unreachable Oracle WMS endpoints. |
FlextOracleWmsAuthenticationError | Specifically handles failed Basic, Bearer, or API Key authentication attempts. |
Sources: src/README.md:104-114, src/flext_oracle_wms/README.md:124-142, src/flext_oracle_wms/errors.py
Class Relationship Diagram
The following diagram illustrates the relationship between the base error and specialized exception types used within the module.
This hierarchy ensures that high-level catch blocks can intercept any Oracle WMS failure while specific handlers target network or credential issues.
Sources: src/flext_oracle_wms/README.md:20-25, src/flext_oracle_wms/errors.py
Railway-Oriented Programming (ROP)
Beyond standard exceptions, the library utilizes the Result pattern (often referred to as r in the codebase) from the flext-core foundation. This pattern allows operations to return a container that represents either a successful value or a failure object, avoiding the need for deep nesting of try-except blocks.
Logic Flow with Results
When an operation like discover_entities() or get_entity_data() is called, it returns a Result object. The developer checks the .success or .failure attributes to determine the next course of action.
The logic flow ensures that even if a network request fails, the application can continue execution and handle the failure as data rather than an unhandled interruption.
Sources: src/flext_oracle_wms/README.md:73-77, examples/01_basic_usage.py:92-108
Result Pattern Implementation
Example of handling a failed entity query using the result pattern:
result = client.get_entity_data("inventory")
if result.is_failure:
# Handle business logic errors via Result
u.fetch_logger(__name__).error("Query failed", error=result.error)
else:
# Process successful result
inventory_data = result.value
Sources: src/flext_oracle_wms/README.md:127-133, examples/01_basic_usage.py:111-124
Validation and Configuration Errors
The library enforces strict validation for configuration settings using Pydantic. If the FlextOracleWmsSettings are initialized with invalid values (e.g., a malformed URL or missing credentials), a validation error is raised immediately.
Validation Workflow
- Input Collection: Settings are loaded from environment variables or direct instantiation.
- Schema Check: Pydantic validates types and required fields.
- Business Rule Validation: The
validate_config()method checks for deeper integration requirements.
Resilience and Recovery
The library includes built-in resilience patterns to handle transient errors automatically.
Retry Logic and Timeouts
Configuration allows for defining retry attempts and exponential backoff strategies.
- Retry Attempts: Configurable via
retry_attemptsin settings (defaults to 3). - Timeouts: Configurable via
timeout(defaults to 30 seconds). - Connection Pooling: Managed via HTTPX to prevent socket exhaustion.
Health Monitoring
The client provides a health_check() method that returns a detailed status of the connection to the Oracle WMS Cloud instance. This is used in enterprise environments to monitor integration health.
Sources: src/README.md:44-48, examples/03_complete_functionality_showcase.py:175-182, tests/unit/test_declarative.py:75-88
Summary
The error handling system in flext-oracle-wms provides a multi-layered approach to reliability. By combining a strict exception hierarchy with the Result pattern, it caters to both infrastructure-level recovery (via FlextOracleWmsError) and application-level flow control (via ROP). Integrated validation and health checks further ensure that errors are caught early in the data lifecycle, maintaining the integrity of data integration pipelines.