iris-devtester 1.19.0__tar.gz → 1.19.2__tar.gz

{iris_devtester-1.19.0 → iris_devtester-1.19.2}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to iris-devtester will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.19.2] - 2026-07-30 - Fix connect_function ImportError when module absent from sys.modules
+
+### Fixed
+
+- **`DBAPIPackageInfo.connect_function` raises after `patch.dict` exit** (`utils/dbapi_compat.py`): `patch.dict(sys.modules, ...)` deletes keys that were absent before the patch when it exits — the common case for unit tests that mock `intersystems_iris` before it has been imported. The 1.19.1 `@property` resolved the MagicMock poisoning but left `sys.modules.get()` returning `None` in this scenario, raising `ImportError: IRIS DBAPI module 'intersystems_iris' is no longer in sys.modules`. The module was importable the whole time. Fixed by falling back to `importlib.import_module(import_path)` when `sys.modules.get()` returns `None`.
+
+## [1.19.1] - 2026-07-30 - Fix dbapi_compat singleton poisoning under test mocks
+
+### Fixed
+
+- **`DBAPIConnectionAdapter` singleton mock poisoning** (`utils/dbapi_compat.py`): when a test patched `intersystems_iris` via `patch.dict(sys.modules, ...)` and the adapter singleton was first built during that patch, the adapter held a reference to the mock's `connect` function for the rest of the process — after `sys.modules` was fully restored. Downstream tests then silently operated against a `MagicMock` connection. Fixed by making `DBAPIPackageInfo.connect_function` a `@property` that resolves the function from `sys.modules` on every call instead of binding it at detection time. The per-call cost is a single `sys.modules` lookup and `getattr` — negligible against opening a socket.
+
+### Added
+
+- **`dbapi_compat.reset_adapter()`**: public function to clear the singleton so tests can force re-detection after their patch exits. Previously the only workaround was reaching into the private `_adapter` global from `conftest.py`. Added to `__all__`.
+
 ## [1.19.0] - 2026-07-19 - iris-agentic-dev Handoff Contract + Discrete Skills
 
 ### Added
@@ -983,6 +999,7 @@ v1.4.3 added connection-based verification with retry logic, which is valuable f
     - `iris_devtester/utils/iris_container_adapter.py` (Docker SDK volume application)
     - `iris_devtester/config/container_config.py` (validate_volume_paths method)
   - **Example**:
+
     ```yaml
     volumes:
       - ./workspace:/external/workspace # Read-write
@@ -1087,6 +1104,7 @@ v1.4.3 added connection-based verification with retry logic, which is valuable f
   - **Impact**: Configuration-defined volumes now work correctly (previously ignored)
   - **Location**: `iris_devtester/utils/iris_container_adapter.py:52-58`
   - **Example**:
+
     ```yaml
     volumes:
       - ./data:/external # Read-write mount

{iris_devtester-1.19.0 → iris_devtester-1.19.2}/CLAUDE.md

@@ -123,3 +123,19 @@ reset), 033 (health/ai_hub editions), 034 (CPF-first password strategy).
 
 `~/ws/rag-templates/` contains original production code this was extracted from. Consult
 it when the current implementation is unclear — especially `common/iris_connection_manager.py`.
+
+<!-- codebase-memory-mcp: Code Discovery Protocol -->
+## Code Discovery Protocol (codebase-memory-mcp)
+
+**ALWAYS use `codebase-memory-mcp` tools FIRST for any code exploration:**
+
+- `search_graph(name_pattern/label/qn_pattern)` — find functions, classes, routes
+- `trace_path(function_name, mode=calls|data_flow|cross_service)` — call chains
+- `get_code_snippet(qualified_name)` — exact symbol source with precise line ranges
+- `query_graph(query)` — complex Cypher patterns across the codebase graph
+- `get_architecture(aspects)` — project structure overview
+- `search_code(pattern)` — graph-augmented text search
+
+Use `Grep`/`Glob`/`Read` freely for text, configs, and non-code files, and always
+`Read` a file before editing it. If the project is not indexed yet, run
+`index_repository` first.

{iris_devtester-1.19.0/iris_devtester.egg-info → iris_devtester-1.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-devtester
-Version: 1.19.0
+Version: 1.19.2
 Summary: Battle-tested InterSystems IRIS infrastructure utilities for Python development
 Author-email: InterSystems Community <community@intersystems.com>
 Maintainer-email: Thomas Dyar <thomas.dyar@intersystems.com>

{iris_devtester-1.19.0 → iris_devtester-1.19.2}/iris_devtester/__init__.py

@@ -26,7 +26,7 @@ LangChain Integration:
     ...     # Build your RAG app...
 """
 
-__version__ = "1.19.0"
+__version__ = "1.19.2"
 __author__ = "InterSystems Community"
 __license__ = "MIT"
 

{iris_devtester-1.19.0 → iris_devtester-1.19.2}/iris_devtester/utils/dbapi_compat.py

@@ -29,9 +29,10 @@ Logging Levels:
 
 import importlib.metadata
 import logging
+import sys
 import time
 from dataclasses import dataclass
-from typing import Any, Callable, Optional
+from typing import Any, Optional
 
 from packaging import version
 
@@ -45,18 +46,38 @@ class DBAPIPackageInfo:
 
     Attributes:
         package_name: One of "intersystems-irispython" or "intersystems-iris"
-        import_path: Module import path (e.g., "intersystems_iris.dbapi._DBAPI")
+        import_path: Module import path (e.g., "intersystems_iris")
         version: Package version (e.g., "5.3.0")
-        connect_function: Reference to the connect() function
+        connect_attr: Attribute name of the connect function on the module (usually "connect")
         detection_time_ms: Time taken to detect package in milliseconds
     """
 
     package_name: str
     import_path: str
     version: str
-    connect_function: Callable[..., Any]
+    connect_attr: str
     detection_time_ms: float
 
+    @property
+    def connect_function(self) -> Any:
+        """Resolve connect function live from sys.modules on every access.
+
+        Resolving at call time (not at detection time) ensures that test patches
+        applied via patch.dict(sys.modules, ...) take effect for exactly the
+        duration of the patch and do not poison the singleton after the patch exits.
+
+        patch.dict removes keys that were absent before the patch, so after exit
+        the module may be gone from sys.modules even though it is importable.
+        Fall back to importlib.import_module() in that case rather than raising.
+        See IDT-BUG-dbapi-adapter-singleton.md.
+        """
+        import importlib
+
+        module = sys.modules.get(self.import_path)
+        if module is None:
+            module = importlib.import_module(self.import_path)
+        return getattr(module, self.connect_attr)
+
 
 def validate_package_version(package_name: str, installed_version: str, min_version: str) -> None:
     """Validate that installed package meets minimum version requirement.
@@ -154,7 +175,7 @@ def detect_dbapi_package() -> DBAPIPackageInfo:
                 package_name="intersystems-irispython",
                 import_path="intersystems_iris",
                 version=pkg_version,
-                connect_function=intersystems_iris.connect,
+                connect_attr="connect",
                 detection_time_ms=elapsed_ms,
             )
     except (ImportError, importlib.metadata.PackageNotFoundError):
@@ -220,7 +241,7 @@ def detect_dbapi_package() -> DBAPIPackageInfo:
             package_name="intersystems-irispython",
             import_path="iris",
             version=pkg_version,
-            connect_function=iris.connect,
+            connect_attr="connect",
             detection_time_ms=elapsed_ms,
         )
 
@@ -239,7 +260,7 @@ def detect_dbapi_package() -> DBAPIPackageInfo:
             package_name="intersystems-iris",
             import_path="iris.irissdk",
             version=pkg_version,
-            connect_function=iris.irissdk.connect,
+            connect_attr="connect",
             detection_time_ms=elapsed_ms,
         )
     except ImportError:
@@ -314,6 +335,17 @@ def _get_adapter() -> DBAPIConnectionAdapter:
     return _adapter
 
 
+def reset_adapter() -> None:
+    """Clear the singleton adapter so it is re-detected on next use.
+
+    Intended for test teardown. Allows tests that patch sys.modules to restore
+    a clean adapter after their patch exits, without reaching into private globals.
+    See IDT-BUG-dbapi-adapter-singleton.md.
+    """
+    global _adapter
+    _adapter = None
+
+
 def get_connection(*args, **kwargs) -> Any:
     """Get DBAPI connection using detected package.
 
@@ -354,4 +386,5 @@ __all__ = [
     "DBAPIConnectionAdapter",
     "get_connection",
     "get_package_info",
+    "reset_adapter",
 ]

{iris_devtester-1.19.0 → iris_devtester-1.19.2/iris_devtester.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-devtester
-Version: 1.19.0
+Version: 1.19.2
 Summary: Battle-tested InterSystems IRIS infrastructure utilities for Python development
 Author-email: InterSystems Community <community@intersystems.com>
 Maintainer-email: Thomas Dyar <thomas.dyar@intersystems.com>

{iris_devtester-1.19.0 → iris_devtester-1.19.2}/iris_devtester.egg-info/SOURCES.txt

@@ -265,4 +265,5 @@ tests/unit/test_wait_strategies.py
 tests/unit/config/test_config_hierarchy.py
 tests/unit/config/test_container_config.py
 tests/unit/config/test_yaml_loader.py
+tests/unit/utils/test_dbapi_compat.py
 tests/unit/utils/test_iris_container_adapter.py

{iris_devtester-1.19.0 → iris_devtester-1.19.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "iris-devtester"
-version = "1.19.0"
+version = "1.19.2"
 description = "Battle-tested InterSystems IRIS infrastructure utilities for Python development"
 readme = "README.md"
 requires-python = ">=3.9"

iris_devtester-1.19.2/tests/unit/utils/test_dbapi_compat.py

@@ -0,0 +1,183 @@
+"""Tests for dbapi_compat singleton-poisoning fix.
+
+Verifies that mocking intersystems_iris does not permanently poison the
+DBAPIConnectionAdapter singleton — the core defect reported in
+IDT-BUG-dbapi-adapter-singleton.md.
+"""
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import iris_devtester.utils.dbapi_compat as dc
+
+
+@pytest.fixture(autouse=True)
+def reset_adapter():
+    """Ensure each test starts with a clean adapter."""
+    dc.reset_adapter()
+    yield
+    dc.reset_adapter()
+
+
+class TestModuleAbsentAfterPatch:
+    """patch.dict removes keys that were absent before the patch on exit.
+
+    The module is importable but not in sys.modules. connect_function must
+    import it rather than raising ImportError.
+    """
+
+    def test_connect_function_importable_when_absent_from_sys_modules(self):
+        """If import_path was absent pre-patch, it's deleted post-patch; must still resolve."""
+        import importlib
+
+        # Ensure the module is absent from sys.modules, then mock it
+        real_module = sys.modules.pop("intersystems_iris", None)
+        fake = MagicMock()
+        fake.connect = object()  # sentinel
+
+        try:
+            assert "intersystems_iris" not in sys.modules, "pre-condition: key must be absent"
+            with patch.dict(sys.modules, {"intersystems_iris": fake}):
+                dc.reset_adapter()
+                dc.get_package_info()  # singleton built while mock is present
+
+            # After patch.dict exit the key is gone (was absent before)
+            assert "intersystems_iris" not in sys.modules
+
+            # connect_function must import the real module, not raise
+            info = dc.get_package_info()
+            # Should not raise; real module is importable
+            fn = info.connect_function
+            assert not isinstance(fn, MagicMock), (
+                "connect_function returned MagicMock after patch exit with absent key"
+            )
+        finally:
+            # Restore original state
+            if real_module is not None:
+                sys.modules["intersystems_iris"] = real_module
+            elif "intersystems_iris" in sys.modules:
+                del sys.modules["intersystems_iris"]
+
+    def test_connect_function_does_not_raise_when_module_absent_from_sys_modules(self):
+        """connect_function must not raise ImportError when module absent but importable."""
+        import importlib
+
+        real_module = sys.modules.pop("intersystems_iris", None)
+        fake = MagicMock()
+        fake.connect = MagicMock()
+
+        try:
+            with patch.dict(sys.modules, {"intersystems_iris": fake}):
+                dc.reset_adapter()
+                info = dc.get_package_info()
+
+            assert "intersystems_iris" not in sys.modules
+
+            # Must not raise
+            dc.reset_adapter()
+            try:
+                info2 = dc.get_package_info()
+                _ = info2.connect_function
+            except ImportError as e:
+                pytest.fail(f"connect_function raised ImportError for importable module: {e}")
+        finally:
+            if real_module is not None:
+                sys.modules["intersystems_iris"] = real_module
+            elif "intersystems_iris" in sys.modules:
+                del sys.modules["intersystems_iris"]
+
+
+class TestSingletonPoisoning:
+    """Fix #1: connect resolved at call time, not detection time."""
+
+    def test_mock_does_not_poison_after_patch_exits(self):
+        """After patch context exits, get_connection must use real connect, not MagicMock."""
+        fake = MagicMock()
+        with patch.dict(sys.modules, {"intersystems_iris": fake}):
+            dc.reset_adapter()  # force re-detection while mock is active
+            info_inside = dc.get_package_info()
+            assert isinstance(info_inside.connect_function, MagicMock)
+
+        # sys.modules restored — real module back
+        dc.reset_adapter()
+        try:
+            info_after = dc.get_package_info()
+            # connect_function must now be the real one, not the MagicMock
+            assert not isinstance(info_after.connect_function, MagicMock), (
+                "Singleton poisoning: connect_function is still a MagicMock after patch exited"
+            )
+        except Exception:
+            # Package not installed in test env — that's fine, not the bug we're testing
+            pass
+
+    def test_connect_function_is_live_attr_not_bound_at_detection(self):
+        """connect_function property must return current module attribute, not cached ref."""
+        fake_module = MagicMock()
+        real_connect = object()  # sentinel
+        fake_module.connect = real_connect
+
+        with patch.dict(sys.modules, {"intersystems_iris": fake_module}):
+            dc.reset_adapter()
+            info = dc.get_package_info()
+            assert info.connect_function is real_connect
+
+            # Swap the connect on the live module — info.connect_function must follow
+            new_connect = object()
+            fake_module.connect = new_connect
+            assert info.connect_function is new_connect, (
+                "connect_function is bound at detection time instead of being resolved live"
+            )
+
+
+class TestResetAdapter:
+    """Fix #2: public reset_adapter() lets consumers manage the singleton cleanly."""
+
+    def test_reset_adapter_clears_singleton(self):
+        fake = MagicMock()
+        with patch.dict(sys.modules, {"intersystems_iris": fake}):
+            dc.reset_adapter()
+            _ = dc.get_package_info()  # builds singleton with mock
+        # Private global should be None after reset
+        dc.reset_adapter()
+        assert dc._adapter is None
+
+    def test_reset_adapter_exported(self):
+        assert "reset_adapter" in dc.__all__
+
+    def test_reset_adapter_idempotent(self):
+        dc.reset_adapter()
+        dc.reset_adapter()  # must not raise
+        assert dc._adapter is None
+
+
+class TestDBAPIPackageInfo:
+    """connect_function must be a live property, not a stored Callable."""
+
+    def test_connect_function_property_returns_current_module_attr(self):
+        fake = MagicMock()
+        sentinel_1 = object()
+        sentinel_2 = object()
+        fake.connect = sentinel_1
+
+        with patch.dict(sys.modules, {"intersystems_iris": fake}):
+            dc.reset_adapter()
+            info = dc.get_package_info()
+            assert info.connect_function is sentinel_1
+
+            fake.connect = sentinel_2
+            assert info.connect_function is sentinel_2
+
+    def test_package_info_still_has_package_name_and_version(self):
+        fake = MagicMock()
+        fake.connect = MagicMock()
+
+        with patch.dict(sys.modules, {"intersystems_iris": fake}), patch(
+            "importlib.metadata.version", return_value="5.2.0"
+        ):
+            dc.reset_adapter()
+            info = dc.get_package_info()
+        assert info.package_name == "intersystems-irispython"
+        assert info.version == "5.2.0"
+        assert info.import_path == "intersystems_iris"