Skip to main content

plasticdb

PyPI DOI

Python client for the PlasticDB API: microorganisms and proteins linked to plastic biodegradation, and the evidence behind them.

Pre-alpha. This release covers the client core, dataset releases, every public data endpoint, the analysis jobs and the plasticdb command-line tool.

Documentation: https://victorgambarini.github.io/plasticdb-py/ (quick start, reproducibility with pinned releases, jobs, CLI reference, Snakemake and Nextflow examples, API reference).

Install

pip install plasticdb
# optional extras
pip install "plasticdb[pandas]"   # or polars, bio, cli, all

Python 3.10 or newer. The core install needs only httpx and pydantic.

Quick start

import plasticdb

client = plasticdb.Client()

# Proteins with positive evidence on PET, as a table and as sequences
pet = client.proteins.list(plastic="PET", kind="wild_type")
print(pet.total)  # 468
df = pet.to_pandas()  # one flat row per protein
pet.to_fasta("pet_enzymes.fasta")  # >PB8CAZ E4 ...
records = pet.to_biopython()  # Bio.SeqRecord list (plasticdb[bio])

# One record (the summary; view="full" embeds interactions, variants, kinetics, properties)
petase = client.proteins.get("PBFCTW")
print(petase.name, len(petase.sequence or ""), petase.source_microorganism.name)

# The evidence spine: interaction -> experiment -> observation
evidence = client.evidence.interactions("PBFCTW")
measurements = evidence.to_pandas(level="observation")  # one row per measured value
# ... or the whole database as flat tables
client.evidence.observations.list(plastic="PET", has_quantitative=True).to_pandas()

# Engineered variants of PETase, with sequences
client.proteins.variants("PBFCTW").to_fasta("petase_variants.fasta")

# Organisms, plastics, papers
client.microorganisms.list(genus="Pseudomonas", plastic="PET").to_polars()
client.microorganisms.get(1547922)  # NCBI tax-id or PB… accession
client.plastics.get(16, protein_limit=10)  # PET, with one page of proteins
client.papers.list(protein="PBFCTW", min_year=2020).all()

# Search, pathways, statistics, the change feed
client.search("cutinase").first()
client.pathways.graph(16).to_networkx()
client.stats.summary()
feed = client.changes(since="2026-11-01T00:00:00Z")
for change in feed:  # status: updated, merged or removed
    ...
next_since = feed.as_of

# Files
client.downloads.proteins("data/", format="csv", plastic="PET")
client.downloads.dataset("data/")  # every public record, ZIP of CSVs

Every list is a lazy Collection: nothing is fetched until you iterate it, and len() is the server's total. all(), rows(), to_pandas(), to_polars() and to_fasta() fetch the remaining pages at 500 records each, up to four at a time (Client(max_concurrency=); it drops to one when the rate-limit allowance runs low, and a 429 waits for Retry-After).

Filters

Keyword arguments are the API's own query parameters, with the same meaning on every resource (the server's conventions): plastic, include_subtypes, microorganism, polarity, include_negative, evidence_method, min_year/max_year, updated_since, sort_by / sort_order and so on. The rank class is spelled class_. An unknown name is a TypeError naming the valid ones; an unknown value is a server 422 (ValidationError). Entity lists default to records with a positive result, as on the website: pass polarity="negative" or include_negative=True for the rest.

Tables

to_pandas() / to_polars() give one flat row per record: nested objects become parent.child columns (source_microorganism.name, paper.doi), lists of plain values stay lists, and per-plastic evidence becomes plastics_positive / plastics_negative / plastics_inconclusive. records() keeps the full JSON nesting. Interactions take level="interaction" | "experiment" | "observation".

Sequences

.to_fasta() and .to_biopython() work on every collection that carries sequences: protein and variant lists, a protein's variants, constructs. Protein list items carry no sequence, so the SDK downloads proteins.fasta once with the same filters and keeps the listed records, in list order. FASTA ids are the accessions (PlasticDB_<id> for the few records without one), as in the server's own files. Single records have .to_fasta() too.

Merged and withdrawn records

Records are sometimes merged (two accessions for one molecule). get() on a merged protein, variant or microorganism raises plasticdb.MergedError with .merged_into, the survivor, and .kind (wild_type, engineered or microorganism). Pass follow_merges=True to get the survivor instead, with a plasticdb.MergedRecordWarning. A withdrawn record (also a variant whose parent protein was withdrawn) raises GoneError with .accession and .reason == "withdrawn" (MergedError is a subclass, so except GoneError catches both). An engineered variant's accession given to proteins.get() returns the Variant; the per-protein collections (interactions, kinetics, …) raise EngineeredVariantError (a NotFoundError) for it. A past release never contains merged records, so a pinned get() answers NotFoundError for them. client.changes() lists merges with their survivors.

Jobs

Annotation, genome comparison, pathway analysis, HMM screens and taxonomy trees run on the server as jobs. Jobs need an API key (create one under Profile → API keys on the website; Client(api_key=) or PLASTICDB_API_KEY); without one the call raises AuthenticationError before anything is sent.

client = plasticdb.Client(release="2026.30")  # jobs run against that release's databases

job = client.jobs.annotate_genome("genome.faa.gz", evalue=1e-10)
job.wait()  # polls with backoff; JobFailedError if the job fails
hits = job.results()  # every hit, typed (JobHit), paged from the server; .to_pandas()
job.download("results/")  # the server's TSV, with its provenance header
job.provenance  # release, reference_sha256, tool_versions, full record

genomes = client.jobs.compare_genomes({"K-12": "ecoli.faa", "201-F6": "isak.faa.gz"})
genomes.wait().comparison().to_pandas()  # genome x plastic matrix
genomes.download("compare.zip")  # per-genome hits, matrix, provenance.json

client.jobs.hmm_screen(records, target_polymers=["PET", "PLA"])  # Bio.SeqRecord list
client.jobs.pathway_analysis("proteins.faa", target_plastic="PET").wait().steps()
client.jobs.annotate_list("taxa.csv", genus_column=1, species_column=2, field_separator="comma")
client.jobs.build_tree(plastic="PET", genus="Pseudomonas").wait().tree().newick
client.jobs.annotate_gene(">q\nMNFPRASRLMQAAVLGG...")  # FASTA text, bytes, a file object
client.jobs.search_sequence("MNFPRASRLMQ...")  # synchronous DIAMOND search, no job

link = job.share(expires_in_days=30)  # read-only link; the token is shown once
client.jobs.shared(link.url).results()  # anyone with the link, no key needed
job.shares()
job.unshare(link)
client.jobs.list().to_pandas()  # your jobs; client.jobs.get(id) to resume one
Job type (jobs.submit(name, ...)) Helper Input Results
annotate_gene, annotate_genome annotate_gene(), annotate_genome() protein (or with blast_type="blastx" nucleotide) FASTA hits()
compare_genomes compare_genomes() 2-20 genomes: a list or {label: genome} hits(), comparison(), ZIP download
pathway_analysis pathway_analysis() protein FASTA (target_plastic, default PET) steps()
hmm_screen hmm_screen() protein FASTA hits() (profiles), info.result_metadata["polymer_hits"]
annotate_list annotate_list() a taxa table (path, text or rows); genus/species columns 7 and 8 unless given taxa()
build_tree build_tree(**filters) organism filters or microorganism_ids tree() (Newick + matrix)

Each helper takes the server's own parameter names (evalue, pident, include_variants, min_scov, threshold_mode, min_step_identity, …); an unknown one is a TypeError. A FASTA input is a path (plain or gzip), FASTA text, bytes, a file object, or Bio.SeqRecords. Uploads are named after their contents (.gz exactly when the bytes are gzip), and a genome's label is the name its rows carry in the results. Polling asks for the job without its hits; results() pages every stored hit from the server (job.iter_hits() is the lazy version); the website and download() start from the job's default view (hits covering at least 70 % of the reference), which download(scov=0) or all_hits=True turns off.

A pinned client (or release= on the call) runs the job against that release's archived DIAMOND databases, HMM library or tables; what a release cannot answer raises UnsupportedFilterError (422) and an unknown release UnknownReleaseError. job.wait(timeout=) raises JobTimeoutError but leaves the job running; call wait() again or client.jobs.get(id) later. Submissions are rate-limited (30 an hour): a 429 is retried after Retry-After when that is within max_retry_wait, otherwise it raises RateLimitError.

Every submission (a job, a tree, a share link) is sent with an Idempotency-Key, a new UUID per call unless you pass idempotency_key=, and every retry of it reuses that key. So a submission is retried like a read on a timeout, a dropped connection or a 5xx: if an attempt did reach the server, the server returns the job it already created (job.replayed is True) instead of running a duplicate. When the retries run out the error names the key; submit again with idempotency_key= that key within 24 hours to recover the job. The same key with a different request raises IdempotencyKeyReusedError.

Configuration

Argument Environment variable Default
api_key PLASTICDB_API_KEY none (reads are anonymous; jobs need a key)
release PLASTICDB_RELEASE none (live database)
base_url PLASTICDB_BASE_URL https://v2.plasticdb.org/api/v1
cache_dir none
timeout, max_retries, max_retry_wait 30 s, 3, 60 s
max_concurrency 4 (parallel page requests in a bulk pull)

Rate-limited requests (429) are retried after Retry-After; reads, sequence searches and submissions (which carry an Idempotency-Key) are retried with backoff on 5xx, timeouts and connection errors. A 503 not_mounted and a sequence search's 504 timeout are not retried.

Errors

Every exception subclasses plasticdb.PlasticDBError and carries the server's .reason when it sent one; all are importable from plasticdb:

  • connection: APIConnectionError, APITimeoutError, UnexpectedResponseError
  • requests: BadRequestError (400), AuthenticationError (401), PermissionDenied (403), NotFoundError (404), ConflictError (409), PayloadTooLargeError (413), ValidationError (422, .errors), IdempotencyKeyReusedError (422), RateLimitError (429, .retry_after), ServerError (5xx), ServiceUnavailableError (503, .retry_after)
  • records: GoneError (410, .accession), MergedError (301, .merged_into), EngineeredVariantError, ResultsExpiredError (410, a job's files); MergedRecordWarning
  • releases: ReleaseError, ReleaseNotAvailableError, UnknownReleaseError, ReleaseNoArtefactsError, ReleaseNotMountedError, ReleaseUnsupportedError, LiveOnlyError, UnsupportedFilterError
  • jobs and files: JobError, JobFailedError, JobTimeoutError (with .job), ChecksumError

Errors has the full hierarchy and the HTTP status of each.

Command line

pip install "plasticdb[cli]"

plasticdb proteins list --plastic PET --format fasta > pet.fasta
plasticdb download dataset --release 2026.50 -o data/
plasticdb jobs submit annotate-genome genome.fna --wait -o hits.tsv
plasticdb cite --release 2026.50

plasticdb is a thin layer over the SDK: each command is one Client call.

  • Output. Data goes to stdout; messages, progress and warnings go to stderr. --format picks tsv, csv, json, jsonl or (for sequences) fasta. Lists default to tsv and single records to json. -o FILE writes to a file, and the file's extension picks the format when --format is not given. TSV is one line per record: lists are joined with ;, nested objects are JSON, and tabs and newlines inside values become spaces.
  • No prompts. The tool never asks for anything unless you pass --interactive, and only auth login ever asks.
  • Global options. --release, --api-key, --base-url, --cache-dir, -q/--quiet and -v/--verbose (-vv logs every request and retry) can go before or after the subcommand. The environment variables are PLASTICDB_RELEASE, PLASTICDB_API_KEY, PLASTICDB_BASE_URL, PLASTICDB_CACHE_DIR and PLASTICDB_CONFIG_DIR.
  • Filters. Filter options are the SDK's filter names: --plastic, --include-subtypes, --polarity, --min-year, --class, --sort-by and so on. They are generated from the SDK, so plasticdb proteins list --help lists exactly what client.proteins.list() takes. --limit/-n caps a list.
Command What it does
proteins list|get|fasta|structure|variants|lineage proteins
variants list|get|fasta|structure|of engineered variants
microorganisms list|get|names|taxonomy organisms
plastics list|get|names the plastic vocabulary
papers list|get|footprint|export papers; export writes BibTeX or RIS
evidence interactions|kinetics|properties|binding-assays|constructs|preparations (and the singular binding-assay, construct, preparation) the evidence; interactions --level observation gives one row per measured value
evidence interaction-records|experiments|observations (and the singular interaction, experiment, observation) the flat evidence tables of the whole database, with the evidence filters
search QUERY [--grouped] full-text search
pathways list|get|for-plastic|graph degradation pathways
stats [--view summary|protein-activity|charts|by-country] statistics
changes --since TIME the change feed; the next --since is printed on stderr
releases list|current|get|status dataset releases
download table|dataset|artefact|manifest|structure files (-o is a file or a directory)
jobs submit TYPE INPUT… [--wait] [-o] run an analysis (kebab-case types: annotate-gene, annotate-genome, compare-genomes, annotate-list, pathway-analysis, hmm-screen, build-tree)
jobs status|wait|results|download|share|shares|unshare|list|search-sequence your jobs; JOB is an id or a share link
auth login|logout|status the stored API key
cite [--format text|bibtex|json] how to cite the release and the paper
provenance, version [--server] what answered, and the versions involved

download dataset without a release saves the live database's ZIP. With --release, -o is a directory, and it receives every artefact that release published (Parquet tables, the reference databases, MANIFEST.json). Each file is checked against its SHA-256. jobs submit prints the job id. With --wait it also writes the results: -o hits.tsv saves the server's results file (which carries provenance lines), and --format writes the typed results instead. Each job parameter is an option named after its SDK keyword (--evalue, --target-polymers, --genus-column, --label, …). The build-tree filters are the /microorganisms filters. An input of - is read from stdin.

API key

pbpaste | plasticdb auth login       # or: plasticdb auth login --interactive
plasticdb auth status                # which key, and where it came from
plasticdb auth logout

auth login checks the key with the server, then saves it to $XDG_CONFIG_HOME/plasticdb/config.json (~/.config/plasticdb/; %APPDATA%\plasticdb on Windows; $PLASTICDB_CONFIG_DIR overrides it). The file is mode 0600, in a 0700 directory, and the tool warns if the file becomes readable by others. The key is read from stdin, or from --key (which leaves it in your shell history), and it is never echoed. --api-key wins, then PLASTICDB_API_KEY, then the file.

Exit codes

Code Meaning
0 success
1 any other error
2 bad command line, option or parameter value (also a server 422)
3 no such record, or it was withdrawn or merged (the message names the survivor)
4 no API key, an invalid one, or not allowed
5 rate limited (429) beyond the retry budget
6 release unknown, unavailable, or unable to answer this (live-only endpoint, unsupported filter)
7 the job failed on the server
8 timed out (a request, or --timeout while waiting for a job; the job keeps running)
9 server unreachable or failing (5xx): retry later
130 interrupted (Ctrl-C)

plasticdb --help prints the same table. A closed pipe (| head) is not an error.

Citation and licence

The code is MIT-licensed. The PlasticDB data is licensed CC BY 4.0: cite the dataset release you used, plus the PlasticDB paper:

Gambarini V, Pantos O, Kingsbury JM, Weaver L, Handley KM, Lear G (2022). PlasticDB: a database of microorganisms and proteins linked to plastic biodegradation. Database, 2022:baac008. https://doi.org/10.1093/database/baac008

client.cite() returns both, including the release version and DOI.

To cite this software itself (e.g. in a methods section), use its Zenodo DOI 10.5281/zenodo.24352328 (all versions; each release also has its own DOI on Zenodo) or GitHub's "Cite this repository", which reads CITATION.cff.

Development

uv venv .venv && uv pip install -e . --group dev
.venv/bin/pytest
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy
make contract-refresh   # re-vendor the SDK contract from the live server
make docs               # build the documentation site (needs requirements-docs.txt)

Metadata

Release files for plasticdb 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for plasticdb 0.1.1
File Size Uploaded Provenance Actions
plasticdb-0.1.1.tar.gz 244.7 kB With provenance Details for plasticdb-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for plasticdb 0.1.1
File Interpreter ABI Platform Actions
plasticdb-0.1.1-py3-none-any.whl Python 3 none any Details for plasticdb-0.1.1-py3-none-any.whl

Total release size: 353.7 kB

Release files / plasticdb-0.1.1.tar.gz

Download URL plasticdb-0.1.1.tar.gz
Size 244.7 kB
Tags Source
SHA-256 checksum
How to use checksums
7e68d6afbc50f50fa128366e1fc56fd7bb61162d0434bb61b6ec432fc2a2c1ce
BLAKE2b-256 checksum
How to use checksums
78a6dada6c45e6b4637b1dcbd585c47386f6f637aad23dadedf052cc9674936e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / plasticdb-0.1.1-py3-none-any.whl

Download URL plasticdb-0.1.1-py3-none-any.whl
Size 109.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d7c318978e13d26db9ee94bd4c201505605936ca58a71d0fcef6cd10b5b937ef
BLAKE2b-256 checksum
How to use checksums
81afdb93f9ad131a891f1cfccaf45d5f16831d61ced2a038b2392756602aebb7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for plasticdb 0.1.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for plasticdb-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page