Python API reference

The functions you call to use AutoZyme’s accelerators in your own pipeline. Signatures here are guarded by tests/test_api_signatures.py — they cannot drift from this page without failing PR CI.

import autozyme

The shape of the API — almost everything is one of three moves:

  • On / off — activate(name) turns patches on; deactivate(name) / deactivate_all() turn them off; disabled() turns them off for a single block.
  • Look — status() (what’s on), list_patches() (what’s available), inspect(name) (detail on one).
  • Extras — set_threads() (CPU threads), env_snapshot() (reproducibility record), speedups() (published numbers).

activate(name)

activate(name) -> bool | dict[str, bool]

Activate one or more patches. (Idempotent — re-activating an active patch is a no-op.)

Parameters

  • name — patch name (str), bundle name (str), or a list of patch/bundle names.

Returns

  • True if a single named patch activated successfully.
  • dict[name, bool] if name was a list or bundle. Per-patch False means the patch’s upstream wasn’t importable (warning printed to stderr explains why).

Example

autozyme.activate("scanpy")                                # True
autozyme.activate(["scanpy", "scvelo"])                    # {'scanpy': True, 'scvelo': True}
autozyme.activate("scrna_core")                            # activates the bundle's patches

deactivate(name)

deactivate(name) -> None

Rebind upstream namespace targets to their captured originals. Inverse of activate. The patch stays registered — activate(name) again is cheap.

Parameters

  • name — patch name, bundle name, or list. Same shape as activate.

Raises

  • KeyError if name doesn’t resolve to a registered patch/bundle. Inactive patches are silently skipped.

deactivate_all()

deactivate_all() -> None

Deactivate every currently-active patch. No-op when nothing is active.

disabled()

disabled()

Context manager. Inside the block, every active patch falls through to the captured original. Hard kill switch — works for namespace patches AND class-method patches (which can’t expose zyme=False per-call).

Example

import scanpy as sc
autozyme.activate("scanpy")

with autozyme.disabled():
    sc.tl.pca(adata)        # uses upstream's original

inspect(name)

inspect(name: str) -> dict[str, Any]

Structured view of a patch’s bindings. Use to debug “did this actually patch what I expected?”.

Returns — dict with keys:

  • name — the patch name.
  • status — "active" / "inactive" / "uninstalled".
  • tested_against — the version string the patch declares.
  • installed_versions — dict of {package: version} actually importable now (one entry per upstream).
  • targets — list of dicts: upstream, attr, fast_fn, original, currently_bound_to_fast.

Example

info = autozyme.inspect("scanpy")
for t in info["targets"]:
    print(f"{t['upstream']}::{t['attr']}: bound={t['currently_bound_to_fast']}")

status()

status() -> dict[str, str]

{patch_name: "active" | "inactive"} for every available patch.

list_patches(installed=False)

list_patches(installed: bool = False) -> list[str]

All shipped patches. With installed=True, only those whose upstream is importable. Does NOT trigger any upstream imports — uses importlib.util.find_spec against the UPSTREAMS manifest.

list_subsets()

list_subsets() -> list[str]

All curated bundle names: ["scrna_core", "scrna_spatial", "molecular_dynamics", ...]. Each can be passed to activate().

subset(name)

subset(name: str) -> list[str]

Member patch names of a bundle. subset("scrna_core") → ["scanpy", "sccoda", "scvelo"].

env_snapshot()

env_snapshot() -> dict[str, Any]

Structured environment snapshot for provenance — autozyme version, Python version, platform, and per-patch state (status, installed upstream versions, tested-against versions). Does not include thread counts. Suitable for serializing alongside results.

speedups(name, history=False)

speedups(name: str, history: bool = False) -> list[dict[str, Any]]

Published per-tier rows from the shipped finalized speedup data. With history=True, returns every historical attest run; without, returns only the most recent per (tier, system) pair.

set_threads(n)

set_threads(n: int) -> int

Set the thread count autozyme advertises. Writes the BLAS/OpenMP env vars (OMP_NUM_THREADS, OPENBLAS_NUM_THREADS, MKL_NUM_THREADS, VECLIB_MAXIMUM_THREADS, NUMEXPR_NUM_THREADS) and records the value autozyme uses as its thread default. Returns the value actually set.

Note: numba reads NUMBA_NUM_THREADS at import time. Set it BEFORE import autozyme if you need it to take effect for numba kernels.

__version__

autozyme.__version__   # "0.3.0"

PEP 440 version string. Bumps on every release. Breaking API changes bump the minor version; the API signature snapshot test gates the change.