Metadata-Version: 2.4
Name: basepair
Version: 3.7.0
Summary: Python client for Basepair's API
Home-page: https://bitbucket.org/basepair/basepair
Download-URL: https://bitbucket.org/basepair/basepair/get/3.7.0.tar.gz
Author: Basepair
Author-email: info@basepairtech.com
Keywords: bioinformatics,ngs analysis,dna-seq,rna-seq,chip-seq,atac-seq
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.txt
Requires-Dist: boto3
Requires-Dist: future
Requires-Dist: requests
Requires-Dist: awscli
Requires-Dist: logbook
Requires-Dist: tabulate
Provides-Extra: sentry
Requires-Dist: sentry-sdk>=2.44.0; extra == "sentry"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

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`:

```json
{
  "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.

### Restart an analysis

```bash
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.

```bash
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:

```python
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:

```bash
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

```python
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:

```python
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)

```python
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](https://basepairtech.atlassian.net/wiki/spaces/BA/pages/342818817/Sentry+Custom+Metrics+-+Pinda+basepair-python+Webapp+Entities)

### 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](https://pypi.org/manage/project/basepair/collaboration/)

### 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](https://test.pypi.org/).
We already have github actions to publish on both Test PyPI and PyPI.
* [Publish Test Packages GitHub Action](https://github.com/basepair/basepair-python/actions/workflows/publish-test-package.yml)
* [Publish Production Package GitHub Action](https://github.com/basepair/basepair-python/actions/workflows/publish-package.yml)

#### Manual way from local
```BASH
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](https://pypi.org/manage/account/token/).

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/
```
