iris-devtester 1.10.0__tar.gz → 1.10.2__tar.gz

{iris_devtester-1.10.0 → iris_devtester-1.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-devtester
-Version: 1.10.0
+Version: 1.10.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.10.2/docs/GETTING_STARTED.md

@@ -0,0 +1,372 @@
+# Getting Started with iris-devtester
+
+**Version**: 1.10.1  
+**Package**: [iris-devtester on PyPI](https://pypi.org/project/iris-devtester/)
+
+## What Is This?
+
+`iris-devtester` is a Python testing toolkit for InterSystems IRIS databases. It provides:
+
+- **Container Management**: Start/stop IRIS containers with one command
+- **Connection Handling**: DBAPI-first connections with automatic retry
+- **Fixture Loading**: Load .DAT fixtures for reproducible test data
+- **pytest Integration**: Ready-to-use fixtures for test isolation
+
+## Installation
+
+```bash
+# Basic installation (DBAPI support)
+pip install iris-devtester
+
+# With all features (JDBC, fixtures, testing)
+pip install "iris-devtester[all]"
+```
+
+## Quick Start
+
+### CLI Usage (Recommended for CI/CD)
+
+```bash
+# Start an IRIS container (zero-config)
+iris-devtester container up
+
+# Start light edition (85% smaller, ideal for CI/CD)
+iris-devtester container up --edition light
+
+# List running containers
+iris-devtester container list
+
+# Test database connectivity
+iris-devtester test-connection
+
+# View container status
+iris-devtester container status
+
+# Stop and remove when done
+iris-devtester container stop
+iris-devtester container remove
+```
+
+### Python API Usage
+
+```python
+from iris_devtester.containers import IRISContainer
+
+# Start a container with context manager (auto-cleanup)
+with IRISContainer.community() as iris:
+    conn = iris.get_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT $ZVERSION")
+    print(cursor.fetchone()[0])
+```
+
+### pytest Integration
+
+```python
+# conftest.py
+from iris_devtester.testing import iris_db
+
+# Use the fixture in tests
+def test_database_query(iris_db):
+    conn = iris_db.get_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT 1+1")
+    assert cursor.fetchone()[0] == 2
+```
+
+## Container Editions
+
+Choose the right edition for your use case:
+
+| Edition | Size | Use Case | Factory Method |
+|---------|------|----------|----------------|
+| **Community** | ~3.5GB | Full-featured development | `IRISContainer.community()` |
+| **Light** | ~580MB | CI/CD pipelines (6x smaller) | `IRISContainer.light()` |
+| **Enterprise** | ~1GB+ | Licensed production features | `IRISContainer.enterprise(license_key=...)` |
+
+### Light Edition Details
+
+The light edition (`caretdev/iris-community-light`) is optimized for CI/CD:
+
+- **85% smaller** than full community edition
+- **Removes**: Interoperability, Management Portal, DeepSee/BI, CSP/REST
+- **Keeps**: SQL engine, DBAPI, JDBC, ODBC, SQLAlchemy-IRIS
+- **Multi-arch**: Supports both ARM64 (Apple Silicon) and x86
+
+```bash
+# CLI
+iris-devtester container up --edition light
+
+# Python
+with IRISContainer.light() as iris:
+    conn = iris.get_connection()
+```
+
+### Enterprise Edition
+
+For licensed IRIS with enterprise features:
+
+```bash
+# CLI
+iris-devtester container up --edition enterprise --license ~/.iris/iris.key
+
+# Python
+with IRISContainer.enterprise(license_key="/path/to/iris.key") as iris:
+    conn = iris.get_connection()
+```
+
+## CLI Command Reference
+
+### Container Commands
+
+```bash
+iris-devtester container --help
+
+# Available commands:
+  up              Create and start container
+  list            List IRIS containers
+  status          Check container health
+  start           Start existing container
+  stop            Stop container
+  restart         Restart container
+  remove          Remove container
+  logs            View container logs
+  reset-password  Reset IRIS user password
+  enable-callin   Enable CallIn service (for DBAPI)
+  test-connection Test database connectivity
+```
+
+### Common Options
+
+```bash
+# Custom container name
+iris-devtester container up --name my-project-db
+
+# Specify edition
+iris-devtester container up --edition light
+
+# JSON output (for scripting/agents)
+iris-devtester container list --format json
+iris-devtester container status --format json
+```
+
+### Exit Codes
+
+For automation and AI agents:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Not found / Config error |
+| 5 | Timeout |
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export IRIS_HOST=localhost
+export IRIS_PORT=1972
+export IRIS_NAMESPACE=USER
+export IRIS_USERNAME=_SYSTEM
+export IRIS_PASSWORD=SYS
+```
+
+### YAML Configuration
+
+Create `iris-config.yml`:
+
+```yaml
+container_name: my-iris-db
+edition: community
+superserver_port: 1972
+webserver_port: 52773
+namespace: USER
+password: SYS
+```
+
+Then use:
+
+```bash
+iris-devtester container up --config iris-config.yml
+```
+
+## Common Workflows
+
+### Local Development
+
+```bash
+# Start container once
+iris-devtester container up --name dev-iris
+
+# Run your tests
+pytest
+
+# Container persists between test runs
+# Stop when done for the day
+iris-devtester container stop
+```
+
+### CI/CD Pipeline
+
+```yaml
+# GitHub Actions example
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install dependencies
+        run: pip install -e ".[test]"
+      
+      - name: Start IRIS (light edition for speed)
+        run: iris-devtester container up --edition light
+      
+      - name: Run tests
+        run: pytest
+      
+      - name: Cleanup
+        if: always()
+        run: iris-devtester container remove --force
+```
+
+### Fixture-Based Testing
+
+```bash
+# Create fixture from existing data
+iris-devtester fixture create --namespace USER --output ./fixtures/baseline
+
+# Load fixture into test database
+iris-devtester fixture load --fixture ./fixtures/baseline
+```
+
+## Troubleshooting
+
+### "Access Denied" Errors
+
+Usually caused by expired passwords. Fix:
+
+```bash
+iris-devtester container reset-password
+iris-devtester test-connection
+```
+
+### Container Won't Start
+
+Check if port is in use:
+
+```bash
+# List all IRIS containers
+iris-devtester container list --all
+
+# Remove old container
+iris-devtester container remove old-container --force
+```
+
+### DBAPI Connection Fails
+
+Ensure CallIn service is enabled:
+
+```bash
+iris-devtester container enable-callin
+```
+
+## For AI Agents
+
+This CLI is designed to be agent-friendly:
+
+1. **Self-documenting**: `iris-devtester --help` shows all options
+2. **Structured output**: `--format json` for machine-readable data
+3. **Clear exit codes**: 0=success, non-zero=failure
+4. **Idempotent operations**: Safe to run commands multiple times
+
+Example agent workflow:
+
+```bash
+# Check if container exists
+iris-devtester container list --format json
+
+# Start if not running
+iris-devtester container up --edition light
+
+# Verify connectivity
+iris-devtester test-connection
+
+# Run tests
+pytest tests/
+```
+
+## When to Use docker-compose Instead
+
+`iris-devtester` manages **single IRIS containers**. For these scenarios, use `docker-compose` directly:
+
+| Scenario | Why docker-compose |
+|----------|-------------------|
+| **Sharded clusters** | Multiple shards + router require coordinated networking |
+| **Mirrored pairs** | Primary + backup with failover configuration |
+| **ECP configurations** | Application servers + database servers |
+| **Multi-service stacks** | IRIS + web server + cache + queue |
+| **Custom networking** | Specific network topologies or bridges |
+
+### Example: Sharded IRIS Cluster
+
+For a sharded HNSW vector search setup with 8 shards:
+
+```yaml
+# docker-compose.yaml
+services:
+  iris-router:
+    image: intersystemsdc/iris-community:latest
+    ports:
+      - "1972:1972"
+    # Router configuration...
+    
+  iris-shard-1:
+    image: intersystemsdc/iris-community:latest
+    # Shard 1 configuration...
+    
+  iris-shard-2:
+    image: intersystemsdc/iris-community:latest
+    # Shard 2 configuration...
+    
+  # ... more shards
+```
+
+Then use:
+
+```bash
+docker-compose up -d
+# Wait for cluster to be ready
+docker-compose logs -f iris-router
+```
+
+### Custom Images with iris-devtester
+
+For **single containers** with custom images, use the `--image` option:
+
+```bash
+# Custom registry
+iris-devtester container up --image myregistry.io/iris:custom
+
+# Specific IRIS version
+iris-devtester container up --image intersystemsdc/iris-community:2024.1
+
+# IRIS with ZPM pre-installed
+iris-devtester container up --image intersystemsdc/iris-community:2024.1-zpm
+```
+
+## Next Steps
+
+- [README.md](../README.md) - Full package documentation
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions
+- [CONSTITUTION.md](../CONSTITUTION.md) - Design principles
+- [SKILL.md](../SKILL.md) - AI agent skill manifest
+
+---
+
+**Questions?** Open an issue on [GitHub](https://github.com/intersystems-community/iris-devtester/issues)

{iris_devtester-1.10.0 → iris_devtester-1.10.2}/iris_devtester/__init__.py

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

iris_devtester-1.10.2/iris_devtester/cli/__init__.py

@@ -0,0 +1,58 @@
+"""CLI commands for iris-devtester."""
+
+import click
+
+from iris_devtester import __version__
+
+from .connection_commands import test_connection
+from .container import container_group as container
+from .fixture_commands import fixture
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="iris-devtester")
+def main():
+    """
+    iris-devtester - Python testing toolkit for InterSystems IRIS databases.
+
+    \b
+    WHAT THIS TOOL DOES:
+      Manages IRIS database containers, fixtures, and connections for testing.
+      Designed for CI/CD pipelines, local development, and AI agent automation.
+
+    \b
+    CONTAINER EDITIONS:
+      community   Full IRIS Community (~3.5GB) - default, all features
+      light       Minimal for CI/CD (~580MB) - SQL/DBAPI only, 6x smaller
+      enterprise  Licensed IRIS - requires iris.key file
+
+    \b
+    QUICK START:
+      iris-devtester container up                    # Start community
+      iris-devtester container up --edition light    # Start light (CI/CD)
+      iris-devtester container list                  # List containers
+      iris-devtester test-connection                 # Verify connectivity
+      iris-devtester container status                # Check health
+
+    \b
+    COMMON WORKFLOWS:
+      Local dev:    container up → test-connection → (your tests)
+      CI/CD:        container up --edition light → test-connection → pytest
+      Fixtures:     fixture load --fixture ./data → (verify data)
+
+    \b
+    FOR AI AGENTS:
+      All commands support --help for detailed options. Commands return
+      structured exit codes (0=success, 1=error, 2=not found, 5=timeout).
+      Use 'container list --format json' for machine-readable output.
+    """
+    pass
+
+
+# Register subcommands
+main.add_command(fixture)
+main.add_command(container)
+main.add_command(test_connection)
+
+
+__all__ = ["main", "fixture", "container", "test_connection"]

{iris_devtester-1.10.0 → iris_devtester-1.10.2}/iris_devtester/cli/container.py

@@ -21,8 +21,23 @@ def container_group(ctx):
     """
     Container lifecycle management commands.
 
-    Manage IRIS containers from the command line with zero-config support.
-    Supports both Community and Enterprise editions.
+    \b
+    Manage IRIS database containers for testing and development.
+    Supports Community, Enterprise, and Light editions.
+
+    \b
+    EDITIONS:
+      community    Full IRIS Community Edition (~3.5GB, all features)
+      light        Minimal CI/CD image (~580MB, SQL/DBAPI only)
+      enterprise   Licensed IRIS (requires --license iris.key)
+
+    \b
+    QUICK START:
+      up              Create and start a container
+      list            Show running containers
+      status          Check container health
+      test-connection Verify database connectivity
+      stop/remove     Clean up containers
     """
     pass
 
@@ -43,6 +58,12 @@ def container_group(ctx):
     default="community",
     help="IRIS edition: community (default), enterprise (requires license), light (minimal for CI/CD)",
 )
+@click.option(
+    "--image",
+    type=str,
+    default=None,
+    help="Custom Docker image (overrides --edition). Example: myregistry/iris:2024.1",
+)
 @click.option(
     "--license",
     "license_key",
@@ -60,37 +81,31 @@ def container_group(ctx):
 )
 @click.option("--cpf", help="Path to CPF merge file or raw CPF content")
 @click.pass_context
-def up(ctx, config, name, edition, license_key, detach, timeout, cpf):
+def up(ctx, config, name, edition, image, license_key, detach, timeout, cpf):
     """
     Create and start IRIS container from configuration.
 
     Similar to docker-compose up. Creates a new container or starts existing one.
     Supports zero-config mode - works without any configuration file.
 
-    Container Lifecycle (Feature 011):
+    \b
+    Container Lifecycle:
       - Containers persist until explicitly removed with 'container remove'
       - Volume mounts are verified during creation
       - No automatic cleanup when CLI exits
 
     \b
     Examples:
-        # Zero-config (uses Community edition defaults)
         iris-devtester container up
-
-        # Light edition for CI/CD (85% smaller, faster startup)
         iris-devtester container up --edition light
-
-        # Enterprise edition with license
-        iris-devtester container up --edition enterprise --license /path/to/iris.key
-
-        # With custom container name
+        iris-devtester container up --edition enterprise --license ./iris.key
+        iris-devtester container up --image myregistry/iris:2024.1
         iris-devtester container up --name my-test-db
-
-        # With custom configuration including volumes
         iris-devtester container up --config iris-config.yml
 
-        # Foreground mode (see logs)
-        iris-devtester container up --no-detach
+    \b
+    NOTE: For multi-container setups (sharding, mirroring, clusters),
+    use docker-compose instead. This tool manages single containers.
     """
     try:
         # Load configuration
@@ -112,8 +127,12 @@ def up(ctx, config, name, edition, license_key, detach, timeout, cpf):
             container_config.container_name = name
             click.echo(f"  → Container name: {name}")
 
-        # Override edition if provided via --edition
-        if edition:
+        # Override image if provided via --image (takes precedence over --edition)
+        if image:
+            container_config.image = image
+            click.echo(f"  → Image: {image} (custom)")
+        # Override edition if provided via --edition (only if --image not set)
+        elif edition:
             edition_lower = edition.lower()
             container_config.edition = edition_lower