Add Oracle TestContainer integration and Family domain test entities

Complete the test infrastructure for Python DataJam implementation:

- Oracle TestContainer manager with proper lifecycle management
- Family domain test entities (Person, Father, Mother, Child) with inheritance
- SQLAlchemy entity mappings with Oracle naming conventions
- Integration test framework using pytest and async fixtures
- Working Oracle Free container setup with connection testing
- Test support utilities and domain-specific queries
- Updated dependencies to use modern python-oracledb driver

The test infrastructure now supports full integration testing against
real Oracle databases using TestContainers, following the same patterns
as the .NET implementation while being adapted for Python async/await.

Author: ericburcham

.claude/settings.local.json

@@ -3,7 +3,14 @@
     "allow": [
       "Bash(dotnet test:*)",
       "WebFetch(domain:github.com)",
-      "Bash(dotnet build:*)"
+      "Bash(dotnet build:*)",
+      "Bash(tree:*)",
+      "Bash(cat:*)",
+      "Bash(python:*)",
+      "Bash(nox:*)",
+      "Bash(git add:*)",
+      "Bash(pip install:*)",
+      "WebFetch(domain:testcontainers-python.readthedocs.io)"
     ],
     "deny": [],
     "ask": []

python/noxfile.py

@@ -7,7 +7,7 @@
 import nox
 
 # Python versions to test against
-PYTHON_VERSIONS = ["3.10", "3.11", "3.12"]
+PYTHON_VERSIONS = ["3.13"]
 PROJECT_ROOT = Path(__file__).parent
 SRC_DIR = PROJECT_ROOT / "src"
 TESTS_DIR = PROJECT_ROOT / "tests"

python/pyproject.toml

@@ -22,6 +22,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Database",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
@@ -30,7 +31,7 @@ dependencies = []
 [project.optional-dependencies]
 sqlalchemy = [
     "SQLAlchemy>=2.0.0",
-    "sqlalchemy[oracle]>=2.0.0",
+    "oracledb>=1.4.0",
 ]
 testing = [
     "pytest>=7.0.0",

python/src/datajam_sqlalchemy/oracle_utils.py

@@ -70,5 +70,5 @@ def create_oracle_connection_string(
     username: str = "system",
     password: str = "oracle",
 ) -> str:
-    """Create an Oracle connection string for SQLAlchemy."""
+    """Create an Oracle connection string for SQLAlchemy using python-oracledb."""
     return f"oracle+oracledb://{username}:{password}@{host}:{port}/?service_name={service_name}"

python/tests/conftest.py

@@ -0,0 +1,43 @@
+"""Pytest configuration and fixtures for DataJam tests."""
+
+import asyncio
+from collections.abc import AsyncGenerator
+
+import pytest
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from tests.integration.oracle.oracle_container_manager import (
+    OracleContainerManager,
+    cleanup_oracle_container,
+    oracle_container_fixture,
+)
+
+
+@pytest.fixture(scope="session")
+def event_loop():
+    """Create an instance of the default event loop for the test session."""
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+
+
+@pytest_asyncio.fixture(scope="session")
+async def oracle_container() -> AsyncGenerator[OracleContainerManager, None]:
+    """Session-scoped Oracle container fixture."""
+    async for container in oracle_container_fixture():
+        yield container
+
+
+@pytest_asyncio.fixture(scope="session")
+async def oracle_engine(oracle_container: OracleContainerManager) -> AsyncEngine:
+    """Session-scoped Oracle engine fixture."""
+    return oracle_container.engine
+
+
+@pytest.fixture(scope="session", autouse=True)
+def cleanup_containers():
+    """Ensure containers are cleaned up after all tests."""
+    yield
+    # This will run after all tests are complete
+    asyncio.run(cleanup_oracle_container())

python/tests/integration/oracle/__init__.py

@@ -0,0 +1 @@
+"""Oracle integration tests for DataJam."""

python/tests/integration/oracle/container_constants.py

@@ -0,0 +1,9 @@
+"""Constants for Oracle TestContainer configuration."""
+
+# Oracle container configuration
+ORACLE_CONTAINER_NAME = "oracle_test_container"
+ORACLE_PASSWORD = "oracle123"
+ORACLE_IMAGE = "gvenzl/oracle-xe:21-slim-faststart"
+ORACLE_PORT = 1521
+ORACLE_SERVICE_NAME = "XE"
+ORACLE_USERNAME = "system"

python/tests/integration/oracle/family_domain.py

@@ -0,0 +1,47 @@
+"""Oracle-specific Family domain implementation for integration tests."""
+
+from __future__ import annotations
+
+from sqlalchemy import MetaData
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from datajam import IConfigureDomainMappings
+from datajam_sqlalchemy import Domain, OracleNamingConvention
+from tests.test_support.family.entities import Base
+
+
+class FamilyMappingConfigurator(IConfigureDomainMappings[MetaData]):
+    """Mapping configurator for the Family domain with Oracle-specific settings."""
+
+    def configure(self, metadata: MetaData) -> None:
+        """Configure entity mappings for Oracle."""
+        # Apply Oracle naming conventions to all tables
+        OracleNamingConvention.configure_metadata_for_oracle(metadata)
+
+
+class OracleFamilyDomain(Domain):
+    """Oracle-specific Family domain implementation."""
+
+    def __init__(self, engine: AsyncEngine, connection_string: str) -> None:
+        """Initialize the Oracle Family domain."""
+        # Create metadata from our entities
+        metadata = Base.metadata
+
+        # Create mapping configurator
+        mapping_configurator = FamilyMappingConfigurator()
+
+        # Initialize the domain
+        super().__init__(
+            connection_string=connection_string,
+            engine=engine,
+            mapping_configurator=mapping_configurator,
+            metadata=metadata,
+        )
+
+    async def create_schema(self) -> None:
+        """Create the database schema for the Family domain."""
+        await self.create_tables()
+
+    async def drop_schema(self) -> None:
+        """Drop the database schema for the Family domain."""
+        await self.drop_tables()

python/tests/integration/oracle/oracle_container_manager.py

@@ -0,0 +1,164 @@
+"""Oracle TestContainer manager for integration tests."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+from testcontainers.oracle import OracleDbContainer
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+from datajam_sqlalchemy import create_oracle_connection_string
+
+from .container_constants import (
+    ORACLE_IMAGE,
+    ORACLE_PASSWORD,
+    ORACLE_PORT,
+    ORACLE_SERVICE_NAME,
+    ORACLE_USERNAME,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class OracleContainerManager:
+    """Manages Oracle TestContainer lifecycle for integration tests."""
+
+    def __init__(self) -> None:
+        """Initialize the Oracle container manager."""
+        self._container: OracleDbContainer | None = None
+        self._engine: AsyncEngine | None = None
+        self._connection_string: str | None = None
+
+    async def start_container(self) -> None:
+        """Start the Oracle container and wait for it to be ready."""
+        if self._container is not None:
+            logger.warning("Oracle container already started")
+            return
+
+        logger.info("Starting Oracle container...")
+
+        # Create and start the Oracle container using the free image
+        self._container = OracleDbContainer(
+            image="gvenzl/oracle-free:slim"  # Use the official free image
+        )
+
+        # Start the container (this will block until ready)
+        self._container.start()
+
+        # Get connection URL directly from the container
+        self._connection_string = self._container.get_connection_url()
+
+        # For async support, convert the connection string to use async driver
+        if self._connection_string.startswith("oracle+cx_oracle://"):
+            async_connection_string = self._connection_string.replace("oracle+cx_oracle://", "oracle+oracledb_async://")
+        elif self._connection_string.startswith("oracle+oracledb://"):
+            async_connection_string = self._connection_string.replace("oracle+oracledb://", "oracle+oracledb_async://")
+        else:
+            async_connection_string = self._connection_string
+
+        self._engine = create_async_engine(
+            async_connection_string,
+            echo=True,  # Enable SQL logging for debugging
+            future=True,
+        )
+
+        logger.info(f"Oracle container started with connection: {self._connection_string}")
+
+        # Test the connection
+        await self._test_connection()
+
+    async def _test_connection(self) -> None:
+        """Test the Oracle connection."""
+        if not self._engine:
+            raise RuntimeError("Engine not initialized")
+
+        try:
+            from sqlalchemy import text
+            async with self._engine.begin() as conn:
+                result = await conn.execute(text("SELECT 1 FROM DUAL"))
+                row = result.fetchone()
+                if row and row[0] == 1:
+                    logger.info("Oracle connection test successful")
+                else:
+                    raise RuntimeError("Oracle connection test failed")
+        except Exception as e:
+            logger.error(f"Oracle connection test failed: {e}")
+            raise
+
+    async def stop_container(self) -> None:
+        """Stop the Oracle container and clean up resources."""
+        if self._engine:
+            await self._engine.dispose()
+            self._engine = None
+
+        if self._container:
+            logger.info("Stopping Oracle container...")
+            self._container.stop()
+            self._container = None
+
+        self._connection_string = None
+        logger.info("Oracle container stopped")
+
+    @property
+    def connection_string(self) -> str:
+        """Get the Oracle connection string."""
+        if not self._connection_string:
+            raise RuntimeError("Oracle container not started")
+        return self._connection_string
+
+    @property
+    def async_connection_string(self) -> str:
+        """Get the Oracle async connection string."""
+        connection_string = self.connection_string
+        return connection_string.replace("oracle+oracledb://", "oracle+oracledb_async://")
+
+    @property
+    def engine(self) -> AsyncEngine:
+        """Get the SQLAlchemy async engine."""
+        if not self._engine:
+            raise RuntimeError("Oracle container not started")
+        return self._engine
+
+    async def __aenter__(self) -> OracleContainerManager:
+        """Enter async context manager."""
+        await self.start_container()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit async context manager."""
+        await self.stop_container()
+
+
+# Global container manager instance
+_oracle_manager: OracleContainerManager | None = None
+
+
+async def get_oracle_container() -> OracleContainerManager:
+    """Get or create the global Oracle container manager."""
+    global _oracle_manager
+
+    if _oracle_manager is None:
+        _oracle_manager = OracleContainerManager()
+        await _oracle_manager.start_container()
+
+    return _oracle_manager
+
+
+async def cleanup_oracle_container() -> None:
+    """Clean up the global Oracle container manager."""
+    global _oracle_manager
+
+    if _oracle_manager is not None:
+        await _oracle_manager.stop_container()
+        _oracle_manager = None
+
+
+# Pytest fixture for Oracle container
+async def oracle_container_fixture() -> AsyncGenerator[OracleContainerManager, None]:
+    """Pytest fixture that provides an Oracle container for tests."""
+    async with OracleContainerManager() as container:
+        yield container

python/tests/integration/oracle/test_when_persisting_and_retrieving_a_child.py

@@ -0,0 +1,78 @@
+"""Oracle integration test for persisting and retrieving a child - Python port of .NET test."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from tests.integration.oracle.family_domain import OracleFamilyDomain
+from tests.test_support.family import Child, Father, GetChildren, Mother
+
+if TYPE_CHECKING:
+    from tests.integration.oracle.oracle_container_manager import OracleContainerManager
+
+
+class TestWhenPersistingAndRetrievingAChild:
+    """Test class for persisting and retrieving a child entity - matches .NET test pattern."""
+
+    @pytest.fixture(autouse=True)
+    async def setup_and_teardown(
+        self,
+        oracle_container: OracleContainerManager,
+        oracle_engine: AsyncEngine,
+    ) -> None:
+        """Setup and teardown for each test method."""
+        # Create domain
+        self.domain = OracleFamilyDomain(
+            engine=oracle_engine,
+            connection_string=oracle_container.async_connection_string,
+        )
+
+        # Create schema
+        await self.domain.create_schema()
+
+        # Create repository and execute the test scenario
+        repository = await self.domain.create_repository()
+
+        try:
+            # Arrange - Create family entities
+            father = Father(name="Dad")
+            mother = Mother(name="Mom")
+            child = Child(name="Kid")
+            child.add_parents(father, mother)
+
+            # Add child to repository (which should also add parents due to relationships)
+            repository.context.add(child)
+            await repository.context.commit()
+
+            # Act - Retrieve the child
+            scalar_query = GetChildren()
+            self.result = await repository.find_scalar(scalar_query)
+
+        finally:
+            # Cleanup
+            await repository.context.__aexit__(None, None, None)
+
+        yield
+
+        # Teardown - Drop schema
+        await self.domain.drop_schema()
+
+    async def test_it_should_have_the_correct_name(self) -> None:
+        """Test that the retrieved child has the correct name."""
+        assert self.result is not None
+        assert self.result.name == "Kid"
+
+    async def test_it_should_have_the_correct_father(self) -> None:
+        """Test that the retrieved child has the correct father."""
+        assert self.result is not None
+        assert self.result.father is not None
+        assert self.result.father.name == "Dad"
+
+    async def test_it_should_have_the_correct_mother(self) -> None:
+        """Test that the retrieved child has the correct mother."""
+        assert self.result is not None
+        assert self.result.mother is not None
+        assert self.result.mother.name == "Mom"