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

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

@@ -5,6 +5,26 @@ 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.4] - 2026-08-25 - Fix plaintext password in CPF merge + wildcard unexpire on attach
+
+### Fixed
+
+- **`start()` passes plaintext password into `PasswordHash=` CPF field** (`containers/iris_container.py`): when `with_preconfigured_password()` was used, `start()` built a custom CPF merge that set `PasswordHash={plaintext}`. The `PasswordHash=` field in a CPF merge file expects a `hash,salt` PBKDF2 format string — passing plaintext produces a corrupt stored hash that causes every subsequent login to fail silently with `<ACCESS VIOLATION>`. Fixed by always using `CPFPreset.SECURE_DEFAULTS` for the CPF merge (handles CallIn enablement and expiry flags correctly) and applying any custom password post-start via `reset_password()` which uses `PasswordExternal` — the IRIS Security API field that accepts plaintext and handles PBKDF2 hashing internally.
+
+### Added
+
+- **`IRISContainer.attach(unexpire_passwords=True)`** (`containers/iris_container.py`): enterprise and HealthShare images commonly ship with expired `_SYSTEM` passwords or `ChangePassword=1` set. Without wildcard unexpire, the first programmatic login silently fails. `attach()` now calls `unexpire_all_passwords(container_name)` after successful container inspection by default. Failure is swallowed — the container is already attached and the caller may have valid credentials. Pass `unexpire_passwords=False` to skip when credentials are known-good and you want to avoid the overhead.
+
+### Documentation
+
+- **`CONSTITUTION.md` Principle 6** — added `_SYSTEM` Password Assumption section documenting: (1) community vs. enterprise default credential differences, (2) why `PasswordHash=` in CPF must never receive plaintext, (3) how IDT's CPF + post-start `reset_password()` dance works, and (4) the wildcard unexpire backstop in `attach()`.
+
+## [1.19.3] - 2026-08-02 - Fix attach() ignoring explicit port override
+
+### Fixed
+
+- **`IRISContainer.attach()` ignores explicit port, always uses docker port lookup** (`containers/iris_container.py`): `attach()` had no port parameter. It always derived the host-side SuperServer port from `docker port <container> 1972/tcp`, which fails on macOS Docker Desktop with irishealth enterprise: Docker Desktop NAT rewrites the source IP from `127.0.0.1` to a bridge address, so IRIS RSTs the connection even though the port binding exists. The user-supplied `IVG_PORT=31971` was silently ignored. Added `port: Optional[int]` to `attach()`; when supplied, `_mapped_port` is pinned immediately so `get_mapped_port(1972)` returns it without calling `get_exposed_port()`. Also reads `IVG_PORT` and `IRIS_PORT` env vars as fallbacks when `port=` is not passed explicitly.
+
 ## [1.19.2] - 2026-07-30 - Fix connect_function ImportError when module absent from sys.modules
 
 ### Fixed

{iris_devtester-1.19.2 → iris_devtester-1.19.4}/CONSTITUTION.md

@@ -15,10 +15,12 @@ This constitution codifies the hard-won lessons, blind alleys avoided, and battl
 **ABSOLUTE REQUIREMENT**: This project uses `intersystems-irispython` as the ONLY Python package for IRIS connectivity.
 
 **FORBIDDEN PACKAGES**:
+
 - ❌ `intersystems-iris` (old package, deprecated)
 - ❌ Any other IRIS Python packages
 
 **Why This Matters**:
+
 - `intersystems-irispython` is the modern, maintained package (v5.3.0+)
 - `intersystems-iris` is the legacy package (v3.0.0+) with known issues
 - Mixing packages causes import conflicts and mysterious failures
@@ -35,6 +37,7 @@ This constitution codifies the hard-won lessons, blind alleys avoided, and battl
 This single document answers the most critical question in IRIS development: "How do I execute this operation?"
 
 **Why This Matters**:
+
 - Using the wrong execution method causes mysterious failures
 - 53 integration tests failed because of this misunderstanding
 - DBAPI is 3x faster for SQL but CANNOT execute ObjectScript
@@ -50,11 +53,13 @@ This single document answers the most critical question in IRIS development: "Ho
 **The Principle**: Infrastructure problems must be automatically detected and remediated without developer intervention.
 
 **Why It Matters**:
+
 - Password expiration errors have wasted hundreds of developer hours
 - Manual remediation breaks CI/CD pipelines
 - "Works on my machine" scenarios damage team productivity
 
 **Implementation Requirements**:
+
 - ✅ Password change required → automatic reset
 - ✅ Container not found → automatic start
 - ✅ Port conflicts → automatic port reassignment
@@ -62,11 +67,13 @@ This single document answers the most critical question in IRIS development: "Ho
 - ✅ Connection failures → automatic retry with backoff
 
 **Forbidden**:
+
 - ❌ Error messages without remediation steps
 - ❌ Requiring manual Docker commands
 - ❌ Silent failures without auto-recovery attempts
 
 **Example**:
+
 ```python
 # WRONG: Manual intervention required
 raise ConnectionError("Password change required. Run: docker exec...")
@@ -82,6 +89,7 @@ if "Password change required" in str(error):
 **The Principle**: Use the appropriate connection method based on what operation you need to perform.
 
 **Why It Matters**:
+
 - IRIS has **two distinct execution paths**: SQL (via DBAPI) and ObjectScript (via iris.connect())
 - Using the wrong tool causes mysterious failures
 - DBAPI is 3x faster for SQL operations
@@ -90,17 +98,18 @@ if "Password change required" in str(error):
 
 **The Decision Matrix**:
 
-| Operation Type | Use | Speed | Example |
-|----------------|-----|-------|---------|
-| SQL queries (SELECT, INSERT, UPDATE, DELETE) | **DBAPI** | Fast (3x) | `cursor.execute("SELECT * FROM MyTable")` |
-| SQL DDL (CREATE TABLE, DROP TABLE) | **DBAPI** | Fast (3x) | `cursor.execute("CREATE TABLE ...")` |
-| Backup/Restore namespace | **DBAPI** + $SYSTEM.OBJ.Execute() | Medium | `cursor.execute("SELECT $SYSTEM.OBJ.Execute('...')")` |
-| Create/Delete namespace | **iris.connect()** | Medium | `iris_obj.classMethodValue("Config.Namespaces", "Create", "TEST")` |
-| Task Manager operations | **iris.connect()** | Medium | `iris_obj.execute("Set task = ##class(%SYS.Task).%New()")` |
-| Global variables | **iris.connect()** | Medium | `iris_obj.set("^MyGlobal", "value")` |
-| User/password management | **docker exec** | Slow | `docker exec iris_db iris session IRIS ...` |
+| Operation Type                               | Use                               | Speed     | Example                                                            |
+| -------------------------------------------- | --------------------------------- | --------- | ------------------------------------------------------------------ |
+| SQL queries (SELECT, INSERT, UPDATE, DELETE) | **DBAPI**                         | Fast (3x) | `cursor.execute("SELECT * FROM MyTable")`                          |
+| SQL DDL (CREATE TABLE, DROP TABLE)           | **DBAPI**                         | Fast (3x) | `cursor.execute("CREATE TABLE ...")`                               |
+| Backup/Restore namespace                     | **DBAPI** + $SYSTEM.OBJ.Execute() | Medium    | `cursor.execute("SELECT $SYSTEM.OBJ.Execute('...')")`              |
+| Create/Delete namespace                      | **iris.connect()**                | Medium    | `iris_obj.classMethodValue("Config.Namespaces", "Create", "TEST")` |
+| Task Manager operations                      | **iris.connect()**                | Medium    | `iris_obj.execute("Set task = ##class(%SYS.Task).%New()")`         |
+| Global variables                             | **iris.connect()**                | Medium    | `iris_obj.set("^MyGlobal", "value")`                               |
+| User/password management                     | **docker exec**                   | Slow      | `docker exec iris_db iris session IRIS ...`                        |
 
 **Implementation Requirements**:
+
 - ✅ Use DBAPI for all SQL operations (SELECT, INSERT, UPDATE, DELETE, CREATE TABLE)
 - ✅ Use iris.connect() for ObjectScript operations (namespaces, Task Manager, globals)
 - ✅ Use docker exec only for admin operations (password reset, system config)
@@ -108,6 +117,7 @@ if "Password change required" in str(error):
 - ✅ Log which connection type is used for each operation
 
 **Forbidden**:
+
 - ❌ `cursor.execute("DO ##class(...)...")` - DBAPI cannot execute ObjectScript
 - ❌ `cursor.execute("Set ^GlobalData = 'value'")` - DBAPI cannot set globals
 - ❌ Using iris.connect() for simple SQL queries (3x slower than DBAPI)
@@ -144,6 +154,7 @@ cursor.execute("SELECT $SYSTEM.OBJ.Execute('Do ##class(Config.Namespaces).Create
 ```
 
 **Performance Evidence**:
+
 ```
 Benchmark Results (1000 simple queries):
 - DBAPI: 2.3 seconds
@@ -163,23 +174,27 @@ For admin ops → Use docker exec (when iris.connect() unavailable)
 **The Principle**: Every test suite gets its own isolated IRIS instance unless explicitly shared.
 
 **Why It Matters**:
+
 - Shared databases cause test pollution
 - Parallel test execution requires isolation
 - Cleanup failures cascade to other tests
 - "Works alone but fails in suite" mysteries
 
 **Implementation Requirements**:
+
 - ✅ Testcontainers for test isolation
 - ✅ Unique namespaces per test class
 - ✅ test_run_id tracking for data cleanup
 - ✅ Automatic cleanup even on test failure
 
 **Forbidden**:
+
 - ❌ Shared databases without cleanup
 - ❌ Assuming tests run sequentially
 - ❌ Leaving test data behind
 
 **Scope Guidelines**:
+
 ```python
 # Module scope: Fast, shared state acceptable
 @pytest.fixture(scope="module")
@@ -199,12 +214,14 @@ def iris_db_isolated():
 **The Principle**: `pip install iris-devtester && pytest` must work without configuration.
 
 **Why It Matters**:
+
 - Reduces onboarding friction
 - Enables quick experimentation
 - Makes examples self-contained
 - CI/CD "just works"
 
 **Implementation Requirements**:
+
 - ✅ Sensible defaults for all configuration
 - ✅ Auto-discovery of IRIS instances
 - ✅ Community edition defaults
@@ -212,11 +229,13 @@ def iris_db_isolated():
 - ✅ Explicit configuration always possible
 
 **Forbidden**:
+
 - ❌ Required configuration files
 - ❌ Mandatory environment variables
 - ❌ Undocumented prerequisites
 
 **Configuration Hierarchy** (highest priority first):
+
 1. Explicit constructor arguments
 2. Environment variables
 3. .env files in project root
@@ -228,11 +247,13 @@ def iris_db_isolated():
 **The Principle**: Errors must be detected immediately with clear remediation steps.
 
 **Why It Matters**:
+
 - Debugging time is expensive
 - Stack traces without context are useless
 - Developers need actionable guidance
 
 **Implementation Requirements**:
+
 - ✅ Detect errors at initialization, not first use
 - ✅ Include "What went wrong" explanation
 - ✅ Include "How to fix it" remediation
@@ -240,11 +261,13 @@ def iris_db_isolated():
 - ✅ Link to relevant documentation
 
 **Forbidden**:
+
 - ❌ Generic error messages
 - ❌ Stack traces without explanation
 - ❌ "Contact administrator" without details
 
 **Example**:
+
 ```python
 # WRONG
 raise ConnectionError("Failed to connect")
@@ -275,12 +298,14 @@ raise ConnectionError(
 **The Principle**: Support both Community and Enterprise editions equally well.
 
 **Why It Matters**:
+
 - Different projects have different needs
 - Development often uses Community, production uses Enterprise
 - License management is complex
 - Mirror configurations are enterprise-only
 
 **Implementation Requirements**:
+
 - ✅ Community edition as default
 - ✅ Enterprise edition via license_key parameter
 - ✅ Auto-discovery of license files
@@ -288,28 +313,51 @@ raise ConnectionError(
 - ✅ Clear documentation of edition differences
 
 **Forbidden**:
+
 - ❌ Hardcoded edition assumptions
 - ❌ Enterprise-only code paths without community fallback
 - ❌ Obscure license errors
 
 **License Discovery Order**:
+
 1. Explicit `license_key` parameter
 2. `IRIS_LICENSE_KEY` environment variable
 3. `~/.iris/iris.key`
 4. `./iris.key` in project root
 5. Auto-discovered from Docker volume mounts
 
+**`_SYSTEM` Password Assumption — Read Before Using Enterprise Images**:
+
+IDT's default credential (`_SYSTEM`/`SYS`) reflects the factory default shipped in InterSystems community images. Enterprise and HealthShare images often ship with:
+
+- Expired `_SYSTEM` password requiring immediate change at first login
+- Different default password or no default password at all
+- `ChangePassword=1` flag set, blocking programmatic login
+
+`attach()` calls `unexpire_all_passwords()` by default (wildcard unexpire via
+`UnExpireUserPasswords("*")`) to handle this silently. For `start()`-managed
+containers the CPF merge sets `PasswordNeverExpires=1` for `SuperUser` and
+`_SYSTEM` pre-boot, then `reset_password()` applies any custom password
+post-start via `PasswordExternal` (accepts plaintext — **never** put plaintext
+into `PasswordHash=` in a CPF file, which expects `hash,salt` PBKDF2 format).
+
+If login fails against an enterprise image with "password expired" or "access
+denied" even after attach, call `unexpire_all_passwords(container_name)` manually
+or pass `unexpire_passwords=True` explicitly.
+
 ### 7. MEDICAL-GRADE RELIABILITY
 
 **The Principle**: All code must be battle-tested in production scenarios with comprehensive error handling.
 
 **Why It Matters**:
+
 - Healthcare applications require 99.9%+ uptime
 - Silent failures are unacceptable
 - Diagnostic data saves hours of debugging
 - Idempotency prevents cascading failures
 
 **Implementation Requirements**:
+
 - ✅ 95%+ test coverage
 - ✅ All error paths tested
 - ✅ Idempotent operations (safe to retry)
@@ -319,12 +367,14 @@ raise ConnectionError(
 - ✅ Health check endpoints
 
 **Forbidden**:
+
 - ❌ Untested error paths
 - ❌ Non-idempotent operations
 - ❌ Silent failures
 - ❌ Assumptions about state
 
 **Reliability Checklist**:
+
 ```python
 # Every operation must answer:
 - [ ] What happens if this fails?
@@ -340,24 +390,28 @@ raise ConnectionError(
 **The Principle**: MUST use the official `iris.connect()` interface from InterSystems documentation. NEVER use undocumented private attributes like `_DBAPI`.
 
 **Why It Matters**:
+
 - `_DBAPI` does NOT exist in intersystems-irispython (tested in v5.1.2 and v5.3.0)
 - Using non-existent attributes causes mysterious import failures
 - Official API is `iris.connect()` per InterSystems documentation
 - Private attributes are subject to change without warning
 
 **Implementation Requirements**:
+
 - ✅ Use `iris.connect()` for DBAPI connections (official DB-API 2.0 interface)
-- ✅ Follow official InterSystems documentation: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=BPYNAT_pyapi
+- ✅ Follow official InterSystems documentation: <https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=BPYNAT_pyapi>
 - ✅ Never import from private modules (anything starting with `_`)
 - ✅ Test compatibility with both v5.1.2 and v5.3.0
 
 **Forbidden**:
-- ❌ `from intersystems_iris.dbapi._DBAPI import connect` - **_DBAPI does not exist!**
+
+- ❌ `from intersystems_iris.dbapi._DBAPI import connect` - **\_DBAPI does not exist!**
 - ❌ `iris._DBAPI.connect()` - **No such attribute!**
 - ❌ Any code relying on undocumented internal APIs
 - ❌ Assuming package structure without verification
 
 **Correct API Usage**:
+
 ```python
 # ✅ CORRECT - Official DB-API 2.0 interface
 import iris
@@ -378,6 +432,7 @@ iris._DBAPI.connect(...)  # AttributeError!
 ```
 
 **Empirical Evidence**:
+
 ```python
 # Tested on intersystems-irispython v5.1.2 and v5.3.0
 import iris
@@ -386,8 +441,9 @@ hasattr(iris, 'connect')  # True in BOTH versions!
 ```
 
 **Official Documentation**:
-- InterSystems Python API: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=BPYNAT_pyapi
-- DB-API 2.0 Specification: https://peps.python.org/pep-0249/
+
+- InterSystems Python API: <https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=BPYNAT_pyapi>
+- DB-API 2.0 Specification: <https://peps.python.org/pep-0249/>
 
 **Reference**: See hipporag2-pipeline CONSTITUTION.md Principle 9 for detailed empirical testing results.
 
@@ -396,12 +452,14 @@ hasattr(iris, 'connect')  # True in BOTH versions!
 **The Principle**: IRIS setup and connectivity should be invisible. A developer should go from "nothing" to "connected" with zero manual configuration.
 
 **Why It Matters**:
+
 - SQLite is the benchmark for "zero-friction" development
 - Infrastructure setup is a major barrier to IRIS adoption
 - Developer "flow" is interrupted by infrastructure management
 - If a user has to think about ports, passwords, or container lifecycles, we have more work to do.
 
 **Implementation Requirements**:
+
 - ✅ `get_connection()` with zero-config auto-discovery
 - ✅ Automatic container lifecycle management (transparent to the user)
 - ✅ Standardized default credentials (`_SYSTEM`/`SYS`)
@@ -409,11 +467,13 @@ hasattr(iris, 'connect')  # True in BOTH versions!
 - ✅ Silent infrastructure: infrastructure "noise" (logs, status) is hidden unless an error occurs
 
 **Forbidden**:
+
 - ❌ Requiring manual Docker commands for basic connectivity
 - ❌ Mandatory configuration files for local dev
 - ❌ Exposing infrastructure complexity in the primary API
 
 **Example**:
+
 ```python
 # THE NORTH STAR EXPERIENCE
 from iris_devtester import IRISContainer
@@ -427,25 +487,28 @@ conn = IRISContainer.community().get_connection()
 **The Principle**: Failed approaches must be documented to prevent repetition.
 
 **Why It Matters**:
+
 - Developers waste time rediscovering "why not"
 - Institutional knowledge must be preserved
 - Context for design decisions is valuable
 - Prevents regression to worse solutions
 
 **Documented Blind Alleys**:
+
 - **Why not JDBC-only?** → DBAPI is 3x faster, see benchmark
 - **Why not shared test databases?** → Data pollution, see case study
 - **Why not manual password resets?** → CI/CD breaks, see incident report
 - **Why not port 1972 hardcoded?** → Conflicts in parallel tests, see issue #42
 - **Why not prefer `iris.connect()`?** → In `intersystems-irispython` 5.3.1+, `iris.connect` uses the `_elsdk_` driver which has a critical `SIGSEGV` bug with `FETCH FIRST N ROWS ONLY` syntax. Prefer `intersystems_iris.connect` (the stable `_IRISNative` path) instead.
 
-
 **Example Documentation**:
+
 ```markdown
 ## Why Not Use Docker Compose for Tests?
 
 **What we tried**: Using docker-compose.yml for test database
 **Why it didn't work**:
+
 - Parallel tests conflicted on ports
 - Cleanup required manual intervention
 - CI/CD required docker-compose installation
@@ -462,12 +525,14 @@ conn = IRISContainer.community().get_connection()
 ### Amendment Process
 
 Principles may be amended when:
+
 1. New evidence contradicts existing principle
 2. Technology landscape changes materially
 3. Production experience reveals gap
 4. Community consensus emerges
 
 **Amendment requires**:
+
 - Concrete evidence (benchmarks, case studies, incident reports)
 - Backwards compatibility analysis
 - Migration guide for existing code
@@ -477,18 +542,21 @@ Principles may be amended when:
 ### Enforcement
 
 **Pre-commit hooks** validate:
+
 - [ ] No hardcoded passwords or credentials
 - [ ] All database operations are idempotent
 - [ ] Error messages include remediation
 - [ ] Test isolation via testcontainers or unique namespaces
 
 **CI/CD validates**:
+
 - [ ] 95%+ test coverage
 - [ ] All platforms (Linux, Mac, Windows)
 - [ ] Both Community and Enterprise editions
 - [ ] Performance benchmarks (no regressions)
 
 **Code review checklist**:
+
 - [ ] Follows DBAPI-first principle
 - [ ] Automatic remediation implemented
 - [ ] Comprehensive error handling
@@ -498,12 +566,14 @@ Principles may be amended when:
 ## Version History
 
 ### v1.2.0 (2026-02-06)
+
 - Added Principle 9: SQLite-Level Ergonomics (The North Star)
 - Renumbered Principle 9 "Document the Blind Alleys" → Principle 10
 - Standardized on `_SYSTEM` as the default toolkit username
 - Renamed project to `iris-devtester` consistently across documentation
 
 ### v1.1.0 (2025-11-23)
+
 - Added Principle 8: Use Official IRIS Python API (No Private Attributes)
 - Documents empirically tested fact that `_DBAPI` does NOT exist in intersystems-irispython v5.1.2 or v5.3.0
 - Mandates use of official `iris.connect()` API per InterSystems documentation
@@ -511,6 +581,7 @@ Principles may be amended when:
 - Based on critical findings from hipporag2-pipeline project testing
 
 ### v1.0.0 (2025-10-05)
+
 - Initial constitution
 - 8 core principles established
 - Based on rag-templates production experience

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-devtester
-Version: 1.19.2
+Version: 1.19.4
 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.2 → iris_devtester-1.19.4}/iris_devtester/__init__.py

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

{iris_devtester-1.19.2 → iris_devtester-1.19.4}/iris_devtester/containers/cpf_manager.py

@@ -40,15 +40,18 @@ class TempCPFManager:
             file_path = os.path.abspath(tmp.name)
             self._temp_files.add(file_path)
 
-            # Register for automatic cleanup
-            weakref.finalize(self, self._delete_file, file_path)
+            # Register for automatic cleanup.
+            # Must use the unbound method — passing self._delete_file would hold
+            # a strong reference to self through the bound method, preventing GC.
+            weakref.finalize(self, TempCPFManager._delete_file, file_path)
 
             logger.debug(f"Created temporary CPF file: {file_path}")
             return file_path
         finally:
             tmp.close()
 
-    def _delete_file(self, file_path: str):
+    @staticmethod
+    def _delete_file(file_path: str):
         """Internal helper to safely delete a file."""
         try:
             if os.path.exists(file_path):

{iris_devtester-1.19.2 → iris_devtester-1.19.4}/iris_devtester/containers/iris_container.py

@@ -7,6 +7,7 @@ from iris_devtester.config import IRISConfig
 from iris_devtester.connections import get_connection
 from iris_devtester.containers.connection_info import IRISConnectionInfo
 from iris_devtester.containers.models import ContainerHealth, ContainerHealthStatus, HealthCheckLevel, ValidationResult
+from iris_devtester.utils.password import reset_password, unexpire_all_passwords
 
 logger = logging.getLogger(__name__)
 
@@ -350,7 +351,13 @@ class IRISContainer(IRISBase):
         return container
 
     @classmethod
-    def attach(cls, container_name: str, **kwargs) -> "IRISContainer":
+    def attach(
+        cls,
+        container_name: str,
+        port: Optional[int] = None,
+        unexpire_passwords: bool = True,
+        **kwargs,
+    ) -> "IRISContainer":
         """
         Attach to an existing IRIS container by name.
 
@@ -360,18 +367,47 @@ class IRISContainer(IRISBase):
 
         Args:
             container_name: Name of the existing Docker container.
+            port: Host-side SuperServer port to use instead of the Docker-inspected
+                binding. Required when Docker Desktop NAT rewrites the source IP and
+                IRIS rejects the connection (macOS Docker Desktop with irishealth
+                enterprise). When supplied, the docker port lookup is skipped entirely.
+                Also honoured via ``IVG_PORT`` or ``IRIS_PORT`` environment variables
+                when ``port`` is not provided explicitly.
+            unexpire_passwords: When True (default), call unexpire_all_passwords() after
+                attaching. Enterprise images often ship with expired passwords; this
+                prevents silent login failures. Set to False when the container is known
+                to have valid credentials and you want to skip the overhead.
             **kwargs: Additional configuration (username, password, namespace).
 
         Returns:
             An IRISContainer instance attached to the existing container.
         """
+        import os
+
         if not container_name:
             raise ValueError("container_name must be a non-empty string")
 
+        # Resolve explicit port override: parameter > IVG_PORT > IRIS_PORT
+        if port is None:
+            for env_var in ("IVG_PORT", "IRIS_PORT"):
+                env_val = os.environ.get(env_var)
+                if env_val:
+                    try:
+                        port = int(env_val)
+                    except ValueError:
+                        pass
+                    else:
+                        break
+
         instance = cls(image="", name=container_name, **kwargs)
         instance._is_attached = True
         instance._container_name = container_name
 
+        # Pin the mapped port immediately so get_mapped_port(1972) never falls
+        # through to the docker port lookup, regardless of which code path below runs.
+        if port is not None:
+            instance._mapped_port = port
+
         try:
             import docker
 
@@ -379,15 +415,16 @@ class IRISContainer(IRISBase):
             container = client.containers.get(container_name)
             instance._container = container
 
-            # If it's a mock container, we need to set these manually
             if not HAS_TESTCONTAINERS:
                 instance.host = "localhost"
-                # Try to find port from container ports
-                ports = container.attrs.get("NetworkSettings", {}).get("Ports", {})
-                if "1972/tcp" in ports and ports["1972/tcp"]:
-                    instance._mapped_port = int(ports["1972/tcp"][0]["HostPort"])
+                # Only read docker port binding when no explicit port was given
+                if port is None:
+                    ports = container.attrs.get("NetworkSettings", {}).get("Ports", {})
+                    if "1972/tcp" in ports and ports["1972/tcp"]:
+                        instance._mapped_port = int(ports["1972/tcp"][0]["HostPort"])
             else:
-                # testcontainers will handle discovery via get_config()
+                # testcontainers will handle host/port discovery via get_config(),
+                # but _mapped_port is already pinned above if port was supplied.
                 instance.get_config()
 
         except Exception as e:
@@ -404,6 +441,15 @@ class IRISContainer(IRISBase):
                 "  3. Check if your user has permission to access the Docker socket"
             )
 
+        if unexpire_passwords:
+            # Enterprise images often ship with expired passwords; wildcard unexpire
+            # prevents silent login failures. Failure is non-fatal — the container
+            # is already attached and the caller may supply valid credentials.
+            try:
+                unexpire_all_passwords(container_name)
+            except Exception:
+                pass
+
         return instance
 
     def with_name(self, name: str) -> "IRISContainer":
@@ -837,17 +883,14 @@ class IRISContainer(IRISBase):
         from iris_devtester.config.presets import CPFPreset
 
         if not hasattr(self, "_cpf_temp_files") or not self._cpf_temp_files:
-            if self._preconfigure_password:
-                cpf = (
-                    "[Actions]\n"
-                    "ModifyService:Name=%Service_CallIn,Enabled=1,AutheEnabled=48\n"
-                    f"ModifyUser:Name=SuperUser,PasswordHash={self._preconfigure_password},"
-                    "ChangePassword=0,PasswordNeverExpires=1\n"
-                    "ModifyUser:Name=_SYSTEM,ChangePassword=0,PasswordNeverExpires=1"
-                )
-            else:
-                cpf = CPFPreset.SECURE_DEFAULTS
-            self.with_cpf_merge(cpf)
+            # Always use SECURE_DEFAULTS for the CPF merge — it handles CallIn
+            # and clears expiry flags for SuperUser/_SYSTEM via proper CPF fields.
+            # When a custom password is requested we reset it post-start via
+            # PasswordExternal (plaintext accepted) rather than injecting it into
+            # PasswordHash= here, which requires a pre-computed PBKDF2 hash,salt
+            # string — passing plaintext into PasswordHash= sets a corrupt hash
+            # and makes every subsequent login fail silently.
+            self.with_cpf_merge(CPFPreset.SECURE_DEFAULTS)
 
         self._password_handled = True
 
@@ -866,6 +909,21 @@ class IRISContainer(IRISBase):
 
         super().start()
         self.get_config()
+
+        # Post-start: apply custom password via PasswordExternal (accepts plaintext).
+        # Must happen after super().start() so the container is ready.
+        if self._preconfigure_password:
+            config = self.get_config()
+            username = self._preconfigure_username or "SuperUser"
+            reset_password(
+                container_name=self.get_container_name(),
+                username=username,
+                new_password=self._preconfigure_password,
+                hostname=config.host,
+                port=config.port,
+                verify=False,
+            )
+
         self._password_preconfigured = True
         return self
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-devtester
-Version: 1.19.2
+Version: 1.19.4
 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>