Python client

Drive the normal research window from Python. Keep native numbers exact and review project changes before they run.

ClonoLoom 0.9.0. Use Python 3.10 or later and the matching host with API 2, catalog 4 and permission policy 1. Package/application version is 0.9.0.

Install from the checkout

uv add /absolute/path/to/clonoloom/clients/python
# Optional pandas helper:
uv add '/absolute/path/to/clonoloom/clients/python[pandas]'

clonoloom --remote-control --allow edits,compute,files

Start the host separately and keep its window open. Without explicit grants, remote access is read-only. The client neither starts a host nor changes permissions. Edits require a person to accept the proposal in the window; accepted changes use named History and normal Undo/Redo. Read Automation permissions.

Query the current repertoire

from decimal import Decimal
import clonoloom

cl = clonoloom.connect(client='Research notebook')
print(cl.permissions())
# Open a dataset in ClonoLoom first.
result = cl.query_clonotypes(
    where={'field': 'total', 'op': 'gte', 'value': Decimal('2')},
    limit=10,
)
evidence = result.native()
rows = result.records()
print(evidence['count'], evidence['matched'], evidence['definitionId'])
frame = result.frame()  # optional pandas; exact object columns

Generated methods share the host's action catalog and map Python snake_case arguments to the original API names. Query filtering changes membership and displayed rank, retaining current definition, QC, source units and the full-table frequency denominator. It is not statistical inference.

Keep numbers and missing values exact

Integer tokens become Python int; fractional/exponent tokens become Decimal. Original response bytes remain in result.raw_json, and native query text remains in result.data['resultJSON']. native() decodes that text without converting through float. Finite Decimal arguments are sent as numbers, not quoted strings.

UNSET omits an optional argument. None sends JSON null, which the host may refuse. Lists remain arrays, including empty lists; dictionaries remain objects. Non-finite numbers, tuples, sets and non-string object keys are refused. Host numeric bounds still apply.

Optional pandas frames use object columns, preserving int/Decimal/None values instead of inferring float columns. Missing dictionary keys become None only in that convenience view. Keep records/raw JSON when that distinction matters. Later arithmetic, dtype conversion and plotting are the caller's choices; the client adds no scientific engine or plot.

Connect to the intended host

connect(data_dir=...) reads that library's remote.json. An explicit URL uses only an explicitly supplied token; it never borrows a token from another library. Environment URL/token and default-library discovery follow documented precedence. Only local loopback HTTP is accepted, and proxies and redirects are disabled.

Every action checks the live API/catalog/policy versions before submission. Incompatible hosts fail without sending the action. Typed errors retain the host code, HTTP status and action; the client never retries an edit or accepts a proposal.

Bounds and scientific limits

Requests are bounded to 1 MiB and responses to 16 MiB. Oversized or malformed responses are explicit failures, not partial successes. A timeout or disconnected caller can leave completed file effects; inspect state before resubmitting. Original certificates and their exact replay limits remain authoritative. Client objects and DataFrames do not replace original evidence bytes or establish biological validity.

The complete Python guide covers connection precedence, typed errors, timeouts and precision limits. The query example is runnable with uv. Methods and tests follow the sister applications' generated-client pattern; MCP shares the same action policy.