Metadata-Version: 2.4
Name: iris-devtester
Version: 1.16.0
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>
Project-URL: Homepage, https://github.com/intersystems-community/iris-devtester
Project-URL: Documentation, https://github.com/intersystems-community/iris-devtester/blob/main/README.md
Project-URL: Repository, https://github.com/intersystems-community/iris-devtester
Project-URL: Issues, https://github.com/intersystems-community/iris-devtester/issues
Project-URL: Changelog, https://github.com/intersystems-community/iris-devtester/blob/main/CHANGELOG.md
Project-URL: Agent Skills, https://github.com/intersystems-community/iris-devtester/blob/main/SKILL.md
Project-URL: Getting Started, https://github.com/intersystems-community/iris-devtester/blob/main/docs/GETTING_STARTED.md
Project-URL: Troubleshooting, https://github.com/intersystems-community/iris-devtester/blob/main/docs/TROUBLESHOOTING.md
Keywords: intersystems,iris,database,testing,testcontainers,docker,devtools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Database
Classifier: Framework :: Pytest
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: testcontainers>=4.0.0
Requires-Dist: testcontainers-iris>=1.2.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: docker>=6.0.0
Requires-Dist: filelock>=3.13.0
Requires-Dist: click>=8.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dbapi
Requires-Dist: intersystems-irispython>=3.2.0; extra == "dbapi"
Provides-Extra: jdbc
Requires-Dist: jaydebeapi>=1.2.3; extra == "jdbc"
Requires-Dist: JPype1>=1.4.0; extra == "jdbc"
Provides-Extra: all
Requires-Dist: intersystems-irispython>=3.2.0; extra == "all"
Requires-Dist: jaydebeapi>=1.2.3; extra == "all"
Requires-Dist: JPype1>=1.4.0; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=5.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Requires-Dist: pytest-timeout>=2.2.0; extra == "test"
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Dynamic: license-file

# IRIS DevTester

**Battle-tested InterSystems IRIS infrastructure utilities for Python development**

[![PyPI version](https://badge.fury.io/py/iris-devtester.svg)](https://pypi.org/project/iris-devtester)
[![Python Versions](https://img.shields.io/pypi/pyversions/iris-devtester.svg)](https://pypi.org/project/iris-devtester/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Test Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen.svg)](https://github.com/intersystems-community/iris-devtester)

## What is This?

IRIS DevTester is a comprehensive Python package that provides **automatic, reliable, production-tested** infrastructure for InterSystems IRIS development. It handles connectivity, container lifecycles, and test data management, codifying years of experience into a reusable toolkit.

## Problems It Solves

- **Auto-Remediation**: Fixes "Password change required" and expired accounts automatically
- **Port Management**: Eliminates conflicts when running tests in parallel
- **Isolation**: Ensures every test gets a clean, isolated database instance
- **Performance**: DBAPI-first connection pooling is 3x faster than traditional JDBC
- **Data Refresh**: High-speed GOF fixture loading (10-100x faster than SQL inserts)

## Quick Start

### 1. Install
```bash
pip install iris-devtester[all]
```

### 2. SQLite-Level Connectivity (Warm Start)
Use the persistent dev instance for instant connections across projects:

```bash
idt dev up
```

Then in your code:
```python
from iris_devtester.connections import get_connection

# Instant connection to a project-specific namespace
conn = get_connection()
```

### 3. Ephemeral Containers (for CI/CD)
For completely isolated test containers:
```python
from iris_devtester.containers import IRISContainer

def test_connection():
    with IRISContainer.community() as iris:
        conn = iris.get_connection()
        cursor = conn.cursor()
        cursor.execute("SELECT 1")
        assert cursor.fetchone()[0] == 1
```

## Container Editions

Three canonical container editions are available:

| Edition | Size | Use Case | Image |
|---------|------|----------|-------|
| **Community** | ~972MB | Development, testing | `intersystemsdc/iris-community` |
| **Enterprise** | ~1GB+ | Production testing | `containers.intersystems.com/intersystems/iris` |
| **Light** | **~580MB** | CI/CD pipelines | `caretdev/iris-community-light` |

### Python API
```python
from iris_devtester.containers import IRISContainer

# Community Edition (auto-detects ARM64 vs x86)
with IRISContainer.community() as iris:
    conn = iris.get_connection()

# Light Edition (85% smaller, for CI/CD)
with IRISContainer.light() as iris:
    conn = iris.get_connection()

# Enterprise Edition (requires license)
with IRISContainer.enterprise(license_key="/path/to/iris.key") as iris:
    conn = iris.get_connection()

# Specify version
with IRISContainer.community(version="2025.1") as iris:
    conn = iris.get_connection()
```

### CLI Usage
```bash
# Community (default)
iris-devtester container up

# Light edition for CI/CD
iris-devtester container up --edition light

# Enterprise edition with license
iris-devtester container up --edition enterprise --license /path/to/iris.key

# List running IRIS containers
iris-devtester container list
```

### Light Edition Details

The Light edition removes components unnecessary for SQL-only workloads:
- **Removed**: Interoperability/Ensemble, Management Portal, DeepSee/BI, CSP/REST
- **Kept**: SQL engine, DBAPI, JDBC, ODBC, SQLAlchemy-IRIS support

Perfect for microservices, automated testing, and Python/SQL pipelines.

### Builder Methods
```python
# Set a custom container name (for debugging, logs, multiple containers)
iris = IRISContainer.community().with_name("my-test-db")

# Set credentials
iris = IRISContainer.community().with_credentials("_SYSTEM", "MyPassword")

# Pre-configure password (set via IRIS_PASSWORD env var at startup)
iris = IRISContainer.community().with_preconfigured_password("MyPassword")

# Chain multiple options
with IRISContainer.community() \
    .with_name("integration-test-db") \
    .with_credentials("_SYSTEM", "TestPass123") as iris:
    conn = iris.get_connection()
```

### Constructor Parameters
```python
IRISContainer(
    image="intersystemsdc/iris-community:latest",  # Docker image
    username="_SYSTEM",                             # Default username
    password="SYS",                                 # Default password
    namespace="USER",                               # Default namespace
    name="my-container",                            # Container name (alternative to with_name)
)
```

## Key Features

- **🔐 Automatic Password Management**: Remediates security flags using official system APIs.
- **🐳 Container Lifecycle**: CLI and Python API for IRIS container management (`up`, `start`, `stop`).
- **📦 DAT Fixture Management**: Create and load reproducible test fixtures in seconds.
- **⚡ DBAPI-First Performance**: Automatically selects the fastest available driver.
- **📊 Resource Monitoring**: Resource-aware performance tracking.

## AI-Assisted Development

This project is optimized for AI coding assistants:
- **[Agent Skill Manifest](https://github.com/intersystems-community/iris-devtester/blob/main/SKILL.md)** - Hierarchical guidance for Claude, Cursor, and Copilot.
- **[AGENTS.md](https://github.com/intersystems-community/iris-devtester/blob/main/AGENTS.md)** - Common build and test commands.

## Documentation

- **[Getting Started](https://github.com/intersystems-community/iris-devtester/blob/main/docs/GETTING_STARTED.md)**
- **[Troubleshooting Guide](https://github.com/intersystems-community/iris-devtester/blob/main/docs/TROUBLESHOOTING.md)**
- **[Examples](https://github.com/intersystems-community/iris-devtester/tree/main/examples/)**
- **[Codified Learnings](https://github.com/intersystems-community/iris-devtester/tree/main/docs/learnings/)**

## License

MIT License - See [LICENSE](https://github.com/intersystems-community/iris-devtester/blob/main/LICENSE)
