Skip to main content

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"
  }
}

Credentials are sent as X-Basepair-Username / X-Basepair-Api-Key headers. Set "auth_mode": "query" in the config section to fall back to the legacy ?username=&api_key= querystring, e.g. when talking to a webapp that predates header auth. Either way the wrappers keep self.payload populated with the username / api_key pair, so downstream subclasses that build their own requests from it keep working.

Output and verbosity

The CLI and the SDK print to stderr using the same rules, so a script's stdout stays clean:

Mode Confirmations (created: …, … updated, deleted …, restart/terminate) Progress (upload steps, Downloading …, Copying …, payload echo)
CLI default / basepair.connect(conf) yes CLI: yes · SDK: no
--verbose / basepair.connect(conf, verbose=True) yes yes
--quiet / basepair.connect(conf, verbose=False) no no

INFO: and ERROR: lines are always printed. Return values never depend on the mode. The CLI additionally asks Are you sure you want to delete <id>? before delete; the SDK never prompts.

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.

List and inspect users and coupons

Read-only access to your host's users and coupons, for monitoring without the web UI.

basepair user list [-c config.json]
basepair user get -u <user_id> [-c config.json]

basepair coupon list [-c config.json]
basepair coupon get -u <coupon_id> [-c config.json]

# coupons issued to/activated by a single user, instead of your host's coupon definitions
basepair coupon list --user <user_id> [-c config.json]
  • Calls GET /api/v3/users/, GET /api/v3/coupons/, and (when --user is passed to coupon list) GET /api/v3/users-coupons/. Permissions are enforced server-side: a host manager sees their host's data, a superuser sees everything.
  • coupon list (no --user) lists the coupon definitions themselves (name, code, available samples, owner, status, created on — the latter is effectively the coupon's issuance timestamp) — the same data shown on the webapp's Coupons admin page.
  • coupon list --user <user_id>: /api/v3/users-coupons/ has no host-level scoping of its own (it returns every user-coupon record on the platform if you don't filter it), so — same as the webapp's own billing page — it must always be queried per user. It returns status, remaining samples, and activation timestamp for that user's coupons; it does not return a user field (you already know it — it's the one you filtered by) or its own issuance timestamp (use the coupon's created_on for that).
  • Add --json to any get/list command for the full raw record instead of the summarized table.
  • Equivalent SDK usage:
import basepair
bp = basepair.connect(conf={'api': {...}})

coupons = bp.get_coupons()
users_coupons = bp.get_users_coupons(filters={'user__id': 6075})
users = bp.get_users()

# or via the resource wrappers directly
from basepair import Coupon, User, UsersCoupon

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.7.3

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.7.3
File Size Uploaded Provenance Actions
basepair-3.7.3.tar.gz 95.3 kB Without provenance Details for basepair-3.7.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for basepair 3.7.3
File Interpreter ABI Platform Actions
basepair-3.7.3-py3-none-any.whl Python 3 none any Details for basepair-3.7.3-py3-none-any.whl

Total release size: 221.0 kB

Release files / basepair-3.7.3.tar.gz

Download URL basepair-3.7.3.tar.gz
Size 95.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c194beec38e82a7f86e46c67d32df81c907b258abf495058b7feace1f7d4da8a
BLAKE2b-256 checksum
How to use checksums
629eb9252b86684cef47bf9843c30f93091844fe3892c98166d1bb642d855a70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

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

Download URL basepair-3.7.3-py3-none-any.whl
Size 125.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c91a7d423a835b6b3d588084c531953a8be22bee6f241fbe5da674ab2ca609ce
BLAKE2b-256 checksum
How to use checksums
b5d45dfc789b127c75579758d224d953924d2f17d39aa6e921001426354fda08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Security for basepair 3.7.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.7.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page