isA Common

Shared async Python client library for the isA platform.

Overview

isa-common provides async Python clients for interacting with isA Cloud infrastructure services. All clients use async with context managers and share a common base class (AsyncBaseClient).

Infrastructure Clients (require running services)

Local-Mode Clients (no external services needed)

Drop-in alternatives for desktop/offline use. Same API surface, backed by local storage:

When to use local clients: Use local-mode clients when running on desktop/ICP without cloud infrastructure, for development/testing without Docker, or when you need offline-capable storage.

Installation

pip install "isa-common[full]"

The base package installs contracts and common utilities. Select drivers explicitly:

pip install "isa-common[contracts,nats]"  # IntegrationEvent contracts and NATS only
pip install "isa-common[redis]"          # Redis client
pip install "isa-common[local]"          # SQLite, files, and DuckDB

Existing consumers that use several infrastructure clients should switch their dependency to isa-common[full]. Public client imports remain lazy and unchanged. A driver must be installed before its client can be imported; installing the base package alone no longer installs every database client. full preserves the previous driver dependency set; observability extras remain separate.

Frappe v15 consumers should select [contracts,nats] so Redis and Boto versions remain governed by Frappe. Do not select [redis], [s3], [falkordb] or [full] inside that Bench environment unless their combined dependency constraints have been verified.

Run bash scripts/test_lean_frappe_install.sh from this package directory to verify a fresh Python 3.12 install against pinned Frappe v15.109.0, including imports and dependency checks.

Quick Start

from isa_common import AsyncRedisClient

async with AsyncRedisClient(host="localhost", port=6379, user_id="my-user") as client:
    health = await client.health_check()
    await client.set("key", "value")
    value = await client.get("key")

Using Local-Mode Clients

from isa_common import AsyncSQLiteClient, AsyncLocalStorageClient

# SQLite instead of PostgreSQL
async with AsyncSQLiteClient(database="app.db", user_id="my-user") as db:
    await db.query("SELECT * FROM users")

# Local filesystem instead of MinIO
async with AsyncLocalStorageClient(base_path="./storage", user_id="my-user") as storage:
    await storage.put_object("my-bucket", "file.txt", b"contents")

Development

Run the default deterministic gate from the repository root. External service tests require one explicit opt-in; endpoint variables configure the target but do not enable a run by themselves:

# From the repository root
make test
ISA_COMMON_RUN_INTEGRATION=1 make test-service s=redis

# Optional Redis endpoint override
ISA_COMMON_RUN_INTEGRATION=1 REDIS_HOST=redis-service REDIS_PORT=6379 \
    make test-service s=redis

Contract Coverage

See tests/contract_coverage.md for the mapping between CDD contract IDs (BR/EC/ER) and test functions.

License

Copyright © 2024 isA Platform