Strict Type Definitions
Relevant source files
The following files were used as context for generating this wiki page:
Strict Type Definitions in the flext-oracle-oic project represent a core engineering pillar designed to ensure reliability, maintainability, and enterprise-grade validation for Oracle Integration Cloud (OIC) extensions. By leveraging Python 3.13 features, Pydantic, and the "Universal Agent Law," the project enforces a zero-tolerance policy against loosely typed escape hatches like Any or unchecked casts.
The architecture centralizes these definitions in a unified pattern, utilizing Pydantic for data models, StrEnum for fixed domain values, and specialized regex patterns for domain-specific validation. This approach ensures that every integration status, connection type, and configuration parameter is validated at the boundary, preventing runtime errors caused by malformed data.
Sources: AGENTS.md:86-89, src/flext_oracle_oic/constants.py:15-32, pyproject.toml:138-161
Core Typing Architecture
The typing system is built on a hierarchy of inherited constants and models that provide a Single Source of Truth (SSOT). The FlextOracleOicConstants class (aliased as c) serves as the foundation, providing enumerations and regex patterns that are subsequently consumed by Pydantic models in m and runtime settings in FlextOracleOicSettings.
Strict Typing Principles
The project adheres to the following strict typing rules as defined in the repository's governing documents:
- Most Restrictive Type: Use the most restrictive type that compiles.
- No Escape Hatches: Explicit prohibition of
Any, bareobject, or suppression of type errors without documented justification. - Railway-Oriented Validation: Use of result types (
p.Result[T]) to handle validation outcomes without relying on exceptions for flow control.
Sources: AGENTS.md:86-89, src/flext_oracle_oic/constants.py:46-55
Validation and Type Flow
This diagram illustrates how raw input data is processed through the strict typing layers before reaching the internal service logic.
The flow ensures that data is sanitized and typed before it is used by any business logic components.
Sources: src/flext_oracle_oic/_utilities/oracle_oic.py:44-77, src/flext_oracle_oic/settings.py:20-43
Enumerations and Domain Types
The project uses StrEnum to define immutable domain values. These enums act as the primary source for Literals and type checks across the codebase.
| Enum Class | Values | Description |
|---|---|---|
OICApiVersion | v1, v2 | Supported Oracle OIC REST API versions. |
Integration.Status | ACTIVATED, DEACTIVATED, DRAFT, RUNNING, STOPPED, ERROR | Lifecycle states of an OIC integration. |
Connection.Status | ACTIVE, INACTIVE, ERROR, unknown | Connectivity status of external adapters. |
Connection.Type | REST, SOAP, DATABASE, FILE, FTP | Supported adapter protocols. |
HealthStatus | healthy, unhealthy, error, unknown | Monitoring status for OIC components. |
Sources: src/flext_oracle_oic/constants.py:64-135
Validation Specifications
Strict types are enforced using specialized validation constants. These include minimum/maximum lengths and pre-compiled regex patterns for specific OIC identifiers.
Integration Validation Constants
# Regex authority for the OracleOicValidation domain
INTEGRATION_NAME_RE: Final[t.RegexPattern] = re.compile(r"^[a-zA-Z0-9_\-\s]+$")
VERSION_PATTERN: Final[t.RegexPattern] = re.compile(r"^\\d{2}\\.\\d{2}\\.\\d{4}$")
MIN_INTEGRATION_NAME_LENGTH: Final[int] = 1
MAX_INTEGRATION_NAME_LENGTH: Final[int] = 100
Sources: src/flext_oracle_oic/constants.py:168-185
Result-Based Validation Logic
Validation utilities return a p.Result[str] or p.Result[t.JsonMapping], adhering to the railway-oriented pattern to ensure type safety in error handling.
Configuration and Runtime Settings
The FlextOracleOicSettings class implements strict typing for environmental configuration. It utilizes Pydantic's Annotated types combined with custom validators and standard types like SecretStr.
Runtime Configuration Fields
| Field | Type | Default Value | Description |
|---|---|---|---|
base_url | t.NonEmptyStr | c.OracleOic.DEFAULT_BASE_URL | Integration Cloud endpoint URL. |
api_version | c.OICApiVersion | c.OICApiVersion.V1 | Default REST API version to use. |
oauth_client_secret | t.SecretStr | "" | Sensitive credential, masked in logs. |
request_timeout | t.PositiveInt | c.DEFAULT_TIMEOUT_SECONDS | Maximum time allowed for API requests. |
Sources: src/flext_oracle_oic/settings.py:27-43, tests/unit/test_config.py:15-50
Model-Driven Data Structures
Data models in the tests/unit/test_models.py and src/flext_oracle_oic/models.py (referenced via m) provide the concrete structures for API responses and requests.
OIC Data Model Hierarchy
Sources: tests/unit/test_models.py:17-105
Summary of Strict Typing Benefits
- Safety: Catching invalid integration IDs or malformed versions before network calls are dispatched via
validate_integration_version. - Security: Use of
t.SecretStrfor client secrets ensures sensitive data is not leaked in telemetry or error logs. - Consistency: SSOT via
FlextOracleOicConstantsprevents duplication of domain strings like status names.
Sources: src/flext_oracle_oic/_utilities/oracle_oic.py:139-152, src/flext_oracle_oic/settings.py:38, src/flext_oracle_oic/constants.py:87-95