Python SDK API

run

Python SDK helpers for recording Goodomics run context.

This module implements the small Python SDK entry point:

from goodomics import run

with run("my-run") as ctx:
    ctx.log_metric("S1", "pct_mapped", 97.2)

The SDK buffers user calls in memory, then flushes them into the same catalog and analytics storage path used by parser/ingest workflows. SQL stores durable entities and relationships; DuckDB stores metric observations.

JsonMetricValue module-attribute

JsonMetricValue = float | int | str

Metric value accepted by the lightweight SDK logging API.

GoodomicsRun dataclass

In-memory SDK context for recording a Goodomics run.

A GoodomicsRun buffers metrics and files while user code runs. Calling :meth:flush, or exiting a successful with run(...) block, writes the run catalog records to SQL and metric observations to DuckDB.

Field-level docstrings below document constructor arguments and dataclass attributes for API reference pages and editor hover. The class docstring stays focused on lifecycle and storage behavior.

name instance-attribute

name: str

Public run label used as the SDK run ID.

project class-attribute instance-attribute

project: str | None = None

Project ID, slug, display-ish name, or None for the default workspace.

analysis_type_id class-attribute instance-attribute

analysis_type_id: str = GENERIC_ANALYSIS

Controlled analysis type ID for the run.

method_id class-attribute instance-attribute

method_id: str = 'goodomics-sdk'

Stable ID for the script, notebook, tool, or workflow being logged.

method_version class-attribute instance-attribute

method_version: str | None = None

Optional version of the primary analysis method.

method_kind class-attribute instance-attribute

method_kind: str = 'script'

Workflow, tool, algorithm, notebook, benchmark, script, or importer.

database_url class-attribute instance-attribute

database_url: str | None = None

Optional SQL catalog database URL override.

analytics_path class-attribute instance-attribute

analytics_path: Path | None = None

Optional direct DuckDB analytics file override.

analytics_root class-attribute instance-attribute

analytics_root: Path = Path('.goodomics')

Root directory used for project-scoped DuckDB files.

auto_persist class-attribute instance-attribute

auto_persist: bool = True

Whether a successful context-manager exit should automatically flush.

metrics class-attribute instance-attribute

metrics: list[LoggedMetric] = field(default_factory=list)

In-memory metric buffer populated by :meth:log_metric.

files class-attribute instance-attribute

files: list[Path] = field(default_factory=list)

In-memory file path buffer populated by :meth:log_file.

__enter__

__enter__() -> GoodomicsRun

Enter a with block and return the mutable SDK run context.

__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc: BaseException | None,
    traceback: TracebackType | None,
) -> None

Flush buffered data when a context manager exits successfully.

Failed with blocks intentionally leave no partial SDK write behind.

log_metric

log_metric(
    sample_id: str | None,
    name: str,
    value: JsonMetricValue,
    *,
    unit: str | None = None,
) -> None

Buffer a metric for this run.

Parameters:

Name	Type	Description	Default
sample_id	str | None	Stable sample ID for sample-scoped metrics, or None for run-level metrics.	required
name	str	Metric field name, such as "pct_mapped".	required
value	JsonMetricValue	Numeric or string metric value.	required
unit	str | None	Optional unit label.	None

metric

metric(
    name: str,
    value: JsonMetricValue,
    *,
    sample_id: str | None = None,
    unit: str | None = None,
) -> None

Alias for :meth:log_metric with sample_id as a keyword argument.

log_file

log_file(path: str | Path) -> None

Buffer a file path associated with this run.

File persistence is reserved for a later SDK path; this method records the path in memory so the public API shape is already available.

file

file(path: str | Path) -> None

Alias for :meth:log_file.

to_analytics_batch

to_analytics_batch(
    *,
    run_id: str | None = None,
    data_contract_id: str | None = None,
) -> AnalyticsIngestBatch

Convert buffered metrics into an unresolved analytics batch.

The returned rows still contain public labels like run_id and field_id. :meth:flush resolves those labels to SQL-owned integer IDs after it writes the catalog records.

flush

flush() -> None

Persist buffered SDK data to the SQL catalog and DuckDB analytics store.

The method is idempotent for one GoodomicsRun instance: later calls return immediately after a successful flush.

LoggedMetric dataclass

Metric buffered by the SDK before persistence.

Buffered metrics are converted into DuckDB analytical rows during :meth:GoodomicsRun.flush; they are not stored directly in the SQL catalog.

sample_id instance-attribute

sample_id: str | None

Stable sample ID for sample-scoped metrics, or None for run-level metrics.

name instance-attribute

name: str

Metric field name supplied by the SDK caller.

value instance-attribute

value: JsonMetricValue

Metric value before conversion into a typed analytical value column.

unit class-attribute instance-attribute

unit: str | None = None

Optional unit label, such as "percent" or "reads".

run

run(
    name: str,
    *,
    project: str | None = None,
    analysis_type_id: str = GENERIC_ANALYSIS,
    method_id: str = "goodomics-sdk",
    method_version: str | None = None,
    method_kind: str = "script",
    database_url: str | None = None,
    analytics_path: str | Path | None = None,
    auto_persist: bool = True,
) -> GoodomicsRun

Create a Goodomics SDK run context.

Parameters:

Name	Type	Description	Default
name	str	Public run label used as the SDK run ID.	required
project	str | None	Project ID, slug, display-ish name, or None for the default workspace.	None
analysis_type_id	str	Controlled analysis type ID.	GENERIC_ANALYSIS
method_id	str	Stable primary analysis method ID.	'goodomics-sdk'
method_version	str | None	Optional primary method version.	None
method_kind	str	Method catalog kind.	'script'
database_url	str | None	Optional SQL catalog database URL override.	None
analytics_path	str | Path | None	Optional direct DuckDB analytics file override.	None
auto_persist	bool	Whether successful context-manager exit should call :meth:GoodomicsRun.flush.	True

Returns:

Type	Description
GoodomicsRun	A mutable :class:GoodomicsRun context.