Changelog¶
Unreleased¶
0.1.1 (2026-11-19)¶
Server 2.90.0 (re-vendored SDK contract).
JobHitgainsprofile_accession,domain_score,domain_c_evalue,domain_i_evalue(floats) andhmm_from,hmm_to,env_from,env_to(integers, 1-based inclusive) forhmm_screenhits; they areNoneon DIAMOND hits and on HMM jobs run before 2.90.0. They are also columns ofhits().rows()/to_dataframe().- On HMM hits
pident,length,qcovandscovare alwaysNone, never 0; identity and coverage filters do not apply to them.evalueandbitscoreare the full-sequence values andsubject_seq_idis the profile name. - The HMM TSV download has 8 trailing columns after
calibration_status; parse it by header name. - New fixtures: an HMM hit with the new fields and an old-style row with all of them null.
0.1.0 (2026-11-19)¶
Server 2.88.0 and 2.89.0 (re-vendored SDK contract, fixtures captured live).
- Security hardening: GitHub Actions are pinned to commit SHAs, Dependabot
keeps them and the dependencies current,
SECURITY.mddescribes private vulnerability reporting, and the TestPyPI release path is gone (publishing is only onv*tags). - Behaviour change:
proteins.get()defaults toview="summary", as the server'sGET /proteins/{ref}does since 2.89.0 (the SDK sentfullbefore). The summary leavesinteractions,indirect_interactions,variants,kineticsandpropertiesempty and gives their sizes inProtein.counts(Protein.viewsays which view you have); ask forview="full"to embed them (up to 12.5 MB for a well-studied enzyme), or page them withproteins.interactions(),.variants(),.kinetics(),.properties(). - New flat evidence lists across the whole database (all pinnable):
client.evidence.interactions.list(**filters)/.get(id),client.evidence.experiments.list/getandclient.evidence.observations.list/get, typed asInteractionRecord,ExperimentRecordandObservationRecord, withto_pandas()/to_polars(). Filters:plastic(+include_subtypes),plastic_id,microorganism,protein,evidence_level,paper_id,doi,polarity,evidence_method,substrate_form,measurement_type,has_quantitative; experiments alsointeraction_id, observationsinteraction_idandexperiment_id. The existing per-protein callclient.evidence.interactions("PBFCTW")keeps working unchanged (it is the same object, now callable). CLI:evidence interaction-records|experiments|observationsandevidence interaction|experiment|observation ID. proteins.interactions(evidence_level=)(all,direct,indirect) replaceskind=, which still works but emits aDeprecationWarningand is never sent together withevidence_level. CLI:--evidence-level;--kindis hidden and deprecated.proteins.list(include_sequence=True)(andvariants.list) adds each item'ssequence.to_fasta()/to_biopython()of a protein list use it: one request series instead of a second FASTA download, also on a pinned client (a server that ignores the parameter falls back to the download).POST /tree/buildneeds an API key (2.88.0):jobs.build_tree()always did; the contract no longer lists an anonymous option, and a contract test pins it.- Zenodo DOI (10.5281/zenodo.24352328) in the README, docs and
CITATION.cff. - Fixed:
jobs submit --idempotency-keyon a replay prints only the "already submitted" line, no longer also "Submitted ... job".
0.0.1 (2026-11-19)¶
- Server 2.87.1:
proteins.fasta()is pinnable (served from the release snapshot; a ref not in the pinned release is a plainNotFoundError, no merge redirect). Contract re-vendored; a job download 410 withreason: "expired"isResultsExpiredError, one without (an expired share link) isGoneError. - Server 2.86.0 and 2.87.0 (re-vendored SDK contract, fixtures re-captured live):
- Job submissions, tree builds and share links send an
Idempotency-Key(a new UUID per call, oridempotency_key=/--idempotency-key), the same on every retry, so they are now retried like reads on a timeout, a dropped connection or a 5xx. A replay isjob.replayed; when retries run out the error names the key to resubmit with.IdempotencyKeyReusedError(422) for a key reused with a different request. Without an API key (which the server needs to honour the key) aPOSTis still never resent after it may have reached the server. - Polling and
jobs.get()/jobs.shared()ask for?include=none;Job.hits()/results()pageGET /jobs/{id}/results(and the share link's/results),Job.iter_hits()lazily. A tree job reads its Newick fromGET /jobs/{id};/tree/{id}is no longer called. Job.provenanceandJob.releasefall back to the job read'sX-PlasticDB-Release/-Sourceheaders.pathway_analysis(target_plastic=)(CLI--target-plastic);annotate_listdocuments the server's 7/8/tabdefaults.- Record redirects are told apart by
reason(mergedorengineered_variant), not by comparing accessions;MergedError.kindcan bemicroorganism, somicroorganisms.get(follow_merges=True)follows organism merges. A merged sub-resource raisesMergedErrorwith the survivor's sub-resourcelocation. EngineeredVariantErroris now aNotFoundErrorand carriesmerged_into; it is raised for the server's 404engineered_varianton a variant's per-protein sub-resources.proteins.fasta()/structure()of a variant accession return the variant's.- A withdrawn record (also a variant whose parent was withdrawn, formerly a
404) is a
GoneErrorwith.accessionand.reason == "withdrawn". Every error now carries the server's.reason. ResultsExpiredError(aGoneError,.results_expired_at) for a job's deleted result files, before or from the server's 410expired.variants.get()andvariants.fasta()are pinnable (answered from the release snapshot);variants.structure()stays live only.evidence_scope="enzyme_only"onmicroorganisms.get()andstats.summary()(CLIstats --evidence-scope);proteins.get()takes a numeric id.search_sequence(): a 503 (index_unavailable/binary_unavailable) isServiceUnavailableErrorwith.retry_after; a 504timeoutis aServerErrorthat is not retried (CLI exit 8); it is retried on other 5xx.- Downloads: a cached pinned table is revalidated with its
ETag(If-None-Match; 304 uses the copy, offline too); an artefact is also checked against the server'sX-PlasticDB-SHA256.APIResponse.etag,.sha256,.source_sha256and.replayed. dataset.zip's JSON 503 (archive_unavailable) keeps.retry_after.-
Every public error is exported from
plasticdb(UnknownReleaseError,ReleaseNotMountedError,ReleaseNoArtefactsError,BadRequestError,ConflictError,UnexpectedResponseErrorwere only inplasticdb.errors), and the README and errors page list them all. -
Documentation site (MkDocs Material, mkdocstrings API reference) published to GitHub Pages: quick start, reproducibility with pinned releases, data and jobs guides, a CLI reference generated from the Typer app, errors, Snakemake and Nextflow workflows and an example notebook.
make docsbuilds it;requirements-docs.txtlists its dependencies. - The
plasticdbcommand-line tool (pip install 'plasticdb[cli]'; alsopython -m plasticdb). It is a thin layer over the SDK, with commands for proteins, variants, microorganisms, plastics, papers, evidence, search, pathways, stats, changes, releases, downloads, jobs, auth, cite, provenance and version. - Data goes to stdout as
--format tsv|csv|json|jsonl|fasta, or to-o FILE, where the extension picks the format. Messages go to stderr. - There are no prompts unless
--interactiveis given. --release,--api-key,--base-url,--cache-dir,-qand-vare accepted before or after the subcommand, with matchingPLASTICDB_*environment variables.- Filter and keyword options are generated from the SDK's own filter types and method signatures.
auth login|logout|statuskeeps the key in a 0600 config file. The environment variable wins over the file.download dataset --release V -o DIRfetches and verifies every artefact the release published.jobs submit TYPE INPUT --wait -o FILEtakes kebab-case job types.cite --format bibtex.- Exit codes are documented and stable: 0 ok, 1 error, 2 usage, 3 not found, 4 auth, 5 rate limited, 6 release, 7 job failed, 8 timeout, 9 unavailable, 130 interrupted.
releases.get()on an unknown version raisesUnknownReleaseError, which is still aNotFoundError.-
Downloaded files get the usual permissions (0666 less the umask) instead of
mkstemp's 0600. -
Jobs (
client.jobs):submit(job_type, input, **params)and a typed helper per server job type:annotate_gene,annotate_genome,compare_genomes,annotate_list,pathway_analysis,hmm_screen,build_tree, plus the synchronoussearch_sequence. Jobs need an API key (AuthenticationErrorbefore any request otherwise); a pinned client, orrelease=, runs them against that release's archived databases. Job:refresh(),wait(timeout=, poll_interval=)with backoff andRetry-After,status,results()(hits(),steps(),taxa(),tree(), typed, withto_pandas()/to_polars()),comparison(), streamingdownload(path)(TSV or the compare_genomes ZIP),share()/shares()/unshare(), andprovenance(release, reference SHA-256, tool versions).jobs.get(id),jobs.list(),jobs.shared(link).- Inputs: a path (plain or gzip), FASTA text, bytes, a file object,
Bio.SeqRecords, or table rows; uploads are named after their contents. - Submissions are never resent once they may have reached the server; a 429 is
waited out within
max_retry_wait. - New errors:
PayloadTooLargeError(413),JobError,JobFailedError,JobTimeoutError.plasticdb.ResultTablefor in-memory typed results. -
The contract test covers every job, share, tree and sequence-search operation.
-
Data namespaces on
Client:proteins,variants,microorganisms,plastics,papers,evidence(interactions, kinetics, properties, binding assays, constructs, preparations),search,pathways,stats,downloads, andchanges(since=). Filters are the API's own parameter names; an unknown one is aTypeError. - Typed models for every record and list item (unknown fields kept).
- Collections:
rows(), andto_pandas()/to_polars()with nested objects flattened toparent.childcolumns; interactions atinteraction,experimentorobservationlevel;to_fasta()/to_biopython()on sequence-carrying collections (protein lists via the server's FASTA download). - Bulk pulls (
all()and the conversions) fetch 500-record pages, up tomax_concurrency(default 4) at a time, and go sequential when the rate-limit allowance is low. - Merged records:
get()raisesMergedErrorby default;follow_merges=Truereturns the survivor with aMergedRecordWarning.proteins.get()on a variant accession returns theVariant; sub-collections raiseEngineeredVariantError. - Streaming downloads to a file or directory, following redirects, with
SHA-256 verification of release artefacts (
ChecksumError). Pinned downloads and release artefacts are cached incache_dir.ServiceUnavailableError.retry_after;downloads.dataset(max_wait=). - Live-only endpoints are marked in the registry and checked against the contract's 409s; the contract test also fails on an operation the SDK neither wraps nor lists as deliberately unwrapped.
Foundation¶
- First release:
Clientwith API-key auth, release pinning (?release=), retries honouringRetry-After, a typed exception hierarchy, provenance, citation, an on-disk cache for pinned answers, andclient.releases(current,get,list,status).