Python client for Basepair

Python bindings for Basepair's API and command line interface (CLI).

CLI

The CLI reads credentials from a JSON config file. Pass it with -c or set BP_CONFIG_FILE:

{
  "api_v3": {
    "host": "app.basepairtech.com",
    "prefix": "/api/v3/",
    "ssl": true,
    "username": "you@example.com",
    "key": "YOUR_API_KEY"
  }
}

Restart an analysis

basepair analysis restart -u <analysis_id> [-c config.json] [--force]

Calls POST /api/v3/analyses/reanalyze/, the same endpoint as the webapp UI's restart.
--force restarts an analysis that is still running (sends force: true).
-u accepts several ids: -u 101 102 103. The command exits with code 1 if any restart fails.
--instance <type> optionally sets the instance type.
basepair analysis reanalyze is an alias with the same flags.

The API enforces a 5-minute cooldown between restarts. Errors from the API are printed as is, for example:

ERROR: Analyses id 139287 is already running.
ERROR: Analyses id 139287 was re-started recently. Please wait 4 minutes 59 seconds before trying again.
ERROR: Analyses with id 99999999 not found.

Note: www/script/start_analysis.py in the webapp repo is an internal/ops-only script and only works on Basepair servers. Use basepair analysis restart instead.

Sentry & custom metrics (optional)

Install with Sentry support:

pip install basepair[sentry]

The library provides shared Sentry init and entity metric constants so consumer apps (Pinda, webapp, ivfapp, kmap) do not duplicate scrubbing, sampling, or metric naming.

Important: basepair-python does not read environment variables for Sentry or metrics. Each app loads its own config and passes explicit parameters.

Sentry init

from basepair.sentry import init_sentry

init_sentry(
    dsn=os.environ.get("SENTRY_DSN"),
    environment=os.environ["MODE"],
    release=os.environ["VERSION"],
    service="pinda-backend",
    traces_sample_rate=float(os.environ["SENTRY_TRACES_SAMPLE_RATE"]),
    profile_sample_rate=float(os.environ["SENTRY_PROFILE_SAMPLE_RATE"]),
    project_name=os.environ.get("PROJECT_NAME"),
    customer_app=os.environ.get("CUSTOMER_APP"),
    debug=os.environ.get("SENTRY_DEBUG") == "true",
    low_value_transactions=("/api/health", "/api/health/"),
)

Empty dsn → no-op (safe for local dev).
Required when dsn is set: environment, release, service, traces_sample_rate, profile_sample_rate.
Optional: project_name, customer_app, debug, low_value_transactions, server_name, enable_logs, enable_metrics.
enable_logs / enable_metrics are passed through to sentry_sdk.init only when set. Omit them for SDK defaults (Sentry Logs off; custom metrics on).

Django apps can use request context helpers:

from basepair.sentry.django import SentryContextMiddleware, set_request_sentry_context

Entity metrics

basepair.metrics is a safe emit helper plus shared metric name constants. The HTTP client does not auto-emit — each app records metrics in its own PIs / workflows, into its own Sentry DSN.

Webapp — METRIC_ANALYSIS_* → webapp.entity.analysis.*
Pinda — METRIC_PINDA_ANALYSIS_* → pinda.analysis.* (use from all Pinda apps / Temporal workflows for consistent names)

from basepair.metrics import (
    METRIC_ANALYSIS_BULK_START,
    METRIC_PINDA_ANALYSIS_BULK_START,
    METRIC_PINDA_ANALYSIS_TERMINAL,
    Outcome,
    emit,
)

# Webapp DSN
emit.incr(METRIC_ANALYSIS_BULK_START, tags={"outcome": Outcome.SUCCESS})

# Pinda DSN (partiseq, revvity, …)
emit.incr(METRIC_PINDA_ANALYSIS_BULK_START, tags={"outcome": Outcome.SUCCESS})
emit.incr(METRIC_PINDA_ANALYSIS_TERMINAL, tags={"terminal_status": "completed"})

Requires sentry-sdk>=2.44.0 for the metrics API. No-op when Sentry is not initialized.

Spec: Confluence — Sentry Custom Metrics

Using MFA

Note: It is advisable to use MFA for increased security and best practices

After you have been added to the list of collaborators, you can verify if MFA has been activated for you by visiting collaboration page

How to build and push to pypi:

Automated publishing of distribution

In the testing stage of the changes, it is advisable to use Test PyPI. We already have github actions to publish on both Test PyPI and PyPI.

Manual way from local

python setup.py sdist bdist_wheel # This will create two files in a newly created dist directory, a source archive and a wheel:
twine upload dist/* # To upload it to Pypi
Uploading distributions to https://upload.pypi.org/legacy/
Enter your username:
Enter your password:

Note: username must be __token__ (not your pypi username) password is the token. You may generate the token -> token creation page.

That is it!

Below is a successful execution sample:

Uploading distributions to https://upload.pypi.org/legacy/
Enter your username: __token__
Enter your password:
Uploading basepair-2.0.7-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 51.0/51.0 kB • 00:00 • 36.3 MB/s
Uploading basepair-2.0.7.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 37.4/37.4 kB • 00:00 • 47.2 MB/s

View at:
https://pypi.org/project/basepair/2.0.7/

Metadata

Release files for basepair 3.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for basepair 3.6.0
File	Size	Uploaded
basepair-3.6.0.tar.gz	87.0 kB	Oct 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for basepair 3.6.0
File	Interpreter	ABI	Platform	Reset
basepair-3.6.0-py3-none-any.whl 118.1 kB Oct 16, 2026	Python 3	none	any	Details

Total release size: 205.1 kB

Release files / basepair-3.6.0.tar.gz

Download URL	basepair-3.6.0.tar.gz
Size	87.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`72a67f148b1b1c6bb68be5686ebef9977bf73c4a5b67427b9adb13566c6d2349`
BLAKE2b-256 checksum How to use checksums	`43d68898eb1801e5f058fa721db767e8171e63fb77e9d4584cade3786358a187`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Release files / basepair-3.6.0-py3-none-any.whl

Download URL	basepair-3.6.0-py3-none-any.whl
Size	118.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`abecab74aa734ace6e27059f44e547f5366df7a5abf877125aa54722898292ea`
BLAKE2b-256 checksum How to use checksums	`a52bcfb9647a8a8bed35cdf778e6cf91d922061f23e3f5458ae6f100d084f8e4`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`