Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
Local development for flext-tap-oracle-wms involves configuring a Python 3.13+ environment, managing dependencies via pyproject.toml, and setting up the necessary mock infrastructure to bypass external Oracle WMS dependencies during testing. The project adheres to the FLEXT ecosystem standards, utilizing flext-core, flext-cli, and flext-oracle-wms as primary dependencies.
The setup focus is on maintaining a "zero-debt baseline" and following the "Universal Agent Law" for engineering conduct, ensuring that all changes are validated through a standardized make contract.
Sources: pyproject.toml:28-35, README.md:5-7, AGENTS.md:12-15
Environment Prerequisites
The project requires Python 3.13. Development dependencies are consolidated under the dev extra in pyproject.toml, covering linting, testing, and documentation tools.
Core Requirements
| Requirement | Specification | Source |
|---|---|---|
| Python Version | >=3.13, <3.14 | pyproject.toml:44 |
| Build System | hatchling | pyproject.toml:6-8 |
| Primary Framework | Singer SDK | src/flext_tap_oracle_wms/README.md:88 |
| Orchestration | Meltano | meltano.yml:2 |
Dependency Installation
To install the project in editable mode with development tools:
pip install -e ".[dev]"
Sources: pyproject.toml:49-130, meltano.yml:48
Project Architecture and Components
The development environment is structured to support the Singer protocol for data extraction from Oracle WMS.
The diagram shows the relationship between local CLI components and the shared FLEXT libraries that provide logging, result handling, and API client logic.
Sources: README.md:27-33, src/flext_tap_oracle_wms/README.md:23-55
Configuration Management
Configuration is handled via Pydantic models and can be passed through environment variables or a settings.json file. For Meltano integration, variables are prefixed as defined in the meltano.yml.
Essential Development Variables
| Variable | Description | Default/Example |
|---|---|---|
WMS_BASE_URL | Oracle WMS Instance URL | https://instance.wms.oraclecloud.com |
WMS_AUTH_METHOD | Authentication type | basic or oauth2 |
WMS_USERNAME | WMS account username | - |
WMS_PASSWORD | WMS account password | - |
WMS_COMPANY_CODE | WMS Company Identifier | DEMO |
Sources: meltano.yml:144-154, tests/README.md:120-126
Testing Infrastructure
A significant portion of the test suite (approx. 27%) requires external dependencies. Local development relies heavily on mocking to achieve isolation.
Test Strategy Flow
Unit tests focus on individual components in isolation, while integration and E2E tests are designed to use a Mock WMS API server to simulate Oracle HATEOAS pagination and metadata responses.
Sources: tests/unit/README.md:18-20, tests/integration/README.md:13-17, tests/README.md:24-30
Running Tests
Standardized make verbs are used for quality gates:
make test-unit: Executes isolated unit tests.make test-fast: Runs tests excluding slow operations.make check: Runs Ruff linting and MyPy type checking.
Sources: tests/unit/README.md:104-112, AGENTS.md:133
Quality Standards and Linting
The project enforces strict quality gates through pyproject.toml configurations for Ruff, MyPy, and Coverage.
- Typing: MyPy strict mode is used.
pyrightis also configured for strict type checking insrcandtests. - Linting: Ruff is configured with the
ALLselection, though several rules are ignored to align with FLEXT ecosystem patterns. - Coverage: Target coverage for enabled tests is 95%. The current failure threshold is set to 20% in
pyproject.tomldue to disabled integration tests.
Sources: pyproject.toml:161-177, pyproject.toml:440-445, pyproject.toml:500-510
Development Workflow (AGENTS.md Contract)
All developers (human or AI) must follow the "Universal Agent Law" documented in AGENTS.md. Key rules include:
- Zero-Tolerance: Fix the root cause, never use workarounds or stubs "for later".
- Fix-Forward-Only: Do not revert shared work; always move the state forward.
- SSOT (Single Source of Truth): Reference authoritative config (like
pyproject.toml) and fail if it is missing. - Evidence: Every "done" task must include the command, exit code, and output evidence.
Sources: AGENTS.md:18-45, AGENTS.md:68-71
Summary
Setting up the local development environment for flext-tap-oracle-wms requires a Python 3.13+ environment, installation of development extras via pip, and strict adherence to the FLEXT quality gates and AGENTS.md engineering laws. Developers must utilize the provided mock patterns to maintain test suite reliability in the absence of a live Oracle WMS instance.