Skip to content

Collections and downloads

Collection

Collection(client: Client, endpoint: Endpoint, model: type[T], *, params: Mapping[str, Any] | None = None, path_params: Mapping[str, Any] | None = None, page_size: int | None = None, limit: int | None = None, max_page_size: int = MAX_PAGE_SIZE)

Bases: Tabular[T]

A lazy, paged list result ({total, items} envelopes).

Nothing is fetched until it is used. Iterating walks the pages in order, one request at a time; all (and everything built on it: records, to_pandas, to_polars, to_fasta) fetches the remaining pages at the largest page size, a few in parallel (Client(max_concurrency=)). len() is the server's total (capped by limit). limit caps how many items are returned, page_size how many each request asks for while iterating.

total property

total: int

How many records match on the server (ignores limit).

release property

release: str | None

The release that answered the first page.

response property

response: APIResponse

The first page's response (headers, release, unavailable fields).

first

first() -> T | None

The first item, or None when nothing matches.

all

all() -> list[T]

Every item (up to limit), fetching the remaining pages in bulk.

to_fasta

to_fasta(path: Any = None) -> str

FASTA text of the items' sequences (>seq_id name); records without one are skipped.

With path, the text is also written there.

to_biopython

to_biopython() -> list[Any]

Bio.SeqRecord.SeqRecord objects (needs plasticdb[bio]).

ResultTable

ResultTable(items: Iterable[T], *, name: str = 'results')

Bases: Tabular[T]

An in-memory list of typed rows (a job's hits, a pathway's steps).

Iterate it, index it, or convert it: rows(), records(), to_pandas(), to_polars().

Downloads

Downloads(client: Client)

Bases: Resource

Files: filtered tables, the whole dataset, and a release's checksummed artefacts.

Every method streams to path (a file, or an existing directory to save the server's file name in) and returns the path written. A pinned client downloads that release's tables as published, and keeps them in cache_dir: a second call is a local copy. Release artefacts are verified against the SHA-256 the release published and are always cacheable.

proteins

proteins(path: PathLike, *, format: Literal['csv', 'json', 'fasta'] = 'csv', **filters: Unpack[ProteinFilters]) -> Path

Proteins (and variants, kind=) as CSV, JSON or FASTA.

A past release answers its published table unfiltered (any filter is UnsupportedFilterError); its CSV/JSON is the wild-type table, variants are protein_variants.

protein_variants

protein_variants(path: PathLike, *, format: TableFormat = 'csv', **filters: Unpack[VariantDownloadFilters]) -> Path

Engineered variants with their parent, mutations and engineering method.

dataset

dataset(path: PathLike, *, format: Literal['zip', 'json'] = 'zip', max_wait: float = 0) -> Path

Every public record: a ZIP of CSVs with a README and licence, or one JSON (live only).

The ZIP is built on demand; while it is being built the server answers 503 with Retry-After (ServiceUnavailableError, .retry_after). max_wait (seconds) keeps waiting that long for it. For a past release, use release_file (or its Figshare archive).

search

search(path: PathLike, q: str, *, format: Literal['json', 'zip'] = 'json') -> Path

Every record matching a search, as JSON or a ZIP of CSVs (live only).

artefacts

artefacts(release: str | None = None) -> list[ReleaseArtefactFile]

The files a release published (release defaults to the pinned or current one).

release_file

release_file(file: str, path: PathLike, *, release: str | None = None) -> Path

One artefact of a release (parquet/proteins.parquet, reference/PlasticDB.dmnd…).

The file is checked against the SHA-256 the release published; a mismatch raises ChecksumError and nothing is kept.

manifest

manifest(release: str | None = None) -> dict[str, Any]

A release's MANIFEST.json: every artefact with its SHA-256, size and licence.

structure

structure(structure_id: int, path: PathLike, *, release: str | None = None) -> Path

One structure's coordinates as published by a release (gzipped PDB).

structure_id is a Structure id. The file is verified against the release manifest. Each file's licence follows its source (manifest()["structures"]).