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.
response
property
¶
response: APIResponse
The first page's response (headers, release, unavailable fields).
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.
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"]).