Skip to content

Client

Client

Client(api_key: str | None = None, *, release: str | None = None, base_url: str | None = None, cache_dir: str | PathLike[str] | None = None, timeout: float | Timeout = DEFAULT_TIMEOUT, max_retries: int = DEFAULT_MAX_RETRIES, max_retry_wait: float = DEFAULT_MAX_RETRY_WAIT, backoff_factor: float = 0.5, max_concurrency: int = DEFAULT_MAX_CONCURRENCY)

A synchronous client for the PlasticDB API.

api_key defaults to $PLASTICDB_API_KEY; reads need none. release (default $PLASTICDB_RELEASE) pins every read to a dataset release, sent as ?release=. With cache_dir, answers from a past release's snapshot are kept on disk; live answers never are. max_concurrency caps the parallel page requests of a bulk pull (Collection.all()); 1 disables it.

release property

release: str | None

The pinned release, or None for the live database.

base_url property

base_url: str

has_api_key property

has_api_key: bool

last_response property

last_response: APIResponse | None

The most recent answer, with its release and source.

changes

changes(since: datetime | str, *, entity_type: Literal['protein', 'protein_variant', 'microorganism', 'plastic', 'paper'] | None = None, page_size: int | None = None, limit: int | None = None) -> ChangeCollection[Change]

Records updated, merged or removed at or after since (live only).

To keep a local copy in sync, store feed.as_of and pass it as the next since. A merge names its survivor in merged_into.

provenance

provenance() -> Provenance

The release, its source, the server and this SDK's versions.

Makes a request when nothing has been asked yet, so the release is known.

server_version

server_version() -> str | None

The server's application version (/health), or None if unavailable.

cite

cite() -> Citation

How to cite the data this client reads, with the CC BY 4.0 licence.

A pinned client cites its release; an unpinned one the current release. If the server cannot be reached the citation still names the paper.

close

close() -> None

Provenance dataclass

Provenance(release: str | None, release_source: str | None, pinned: bool, base_url: str, sdk_version: str, server_version: str | None, data_license: str = DATA_LICENSE)

Where an analysis' data came from: record this alongside results.

Citation dataclass

Citation(dataset: str, release: str | None, doi: str | None, paper: str = PAPER_CITATION, paper_doi: str = PAPER_DOI, license: str = DATA_LICENSE, license_url: str = DATA_LICENSE_URL)

How to cite the data. str(citation) is the full text to paste.

APIResponse dataclass

APIResponse(status_code: int, data: Any, headers: Headers, url: str, release: str | None, release_source: str | None, unavailable_fields: tuple[str, ...] = (), from_cache: bool = False)

One decoded answer from the API, with the release that produced it.

pinned property

pinned: bool

True when a past release's snapshot answered (not the live database).

etag property

etag: str | None

The ETag (weak on a pinned download, the file's SHA-256 on an artefact).

sha256 property

sha256: str | None

A release artefact's own SHA-256 (X-PlasticDB-SHA256).

source_sha256 property

source_sha256: tuple[str, ...]

A pinned download's source: the SHA-256 of each release Parquet artefact it was rendered from, as in the release's MANIFEST.json (X-PlasticDB-Source-SHA256; FASTA: proteins, then protein_variants).

replayed property

replayed: bool

True when an Idempotency-Key submission returned what an earlier one created.