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. --forcerestarts an analysis that is still running (sendsforce: true).-uaccepts several ids:-u 101 102 103. The command exits with code1if any restart fails.--instance <type>optionally sets the instance type.basepair analysis reanalyzeis 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.pyin the webapp repo is an internal/ops-only script and only works on Basepair servers. Usebasepair analysis restartinstead.
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--useris passed tocoupon 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 auserfield (you already know it — it's the one you filtered by) or its own issuance timestamp (use the coupon'screated_onfor that).- Add
--jsonto anyget/listcommand 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
dsnis 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_metricsare passed through tosentry_sdk.initonly 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.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| basepair-3.7.2.tar.gz | 94.9 kB | Without provenance | Details for basepair-3.7.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| basepair-3.7.2-py3-none-any.whl | Python 3 | none | any | Details for basepair-3.7.2-py3-none-any.whl |
Total release size: 220.2 kB
Release files / basepair-3.7.2.tar.gz
| Download URL | basepair-3.7.2.tar.gz |
|---|---|
| Size | 94.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e7483baa7c9eeca46e2b18d9125389dfa6b58fbfacdb40b473764713936ccd8c
|
|
BLAKE2b-256 checksum How to use checksums |
fc006da406cb95908ea681a38efadecd18405224c08bd375f7a58126414bb8b9
|
| 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.2-py3-none-any.whl
| Download URL | basepair-3.7.2-py3-none-any.whl |
|---|---|
| Size | 125.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eceb7be5b3f5394e73cdb012604972730614d2abd33a5c2dbdc8ab3a903bacf0
|
|
BLAKE2b-256 checksum How to use checksums |
7b14f932e979b955532fec1300b9fa55c52e9f0627cf424399b4ffab0509b1ac
|
| 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.2
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.