plasticdb 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- plasticdb-0.0.1/.gitignore +13 -0
- plasticdb-0.0.1/CHANGELOG.md +141 -0
- plasticdb-0.0.1/CITATION.cff +32 -0
- plasticdb-0.0.1/LICENSE +21 -0
- plasticdb-0.0.1/PKG-INFO +390 -0
- plasticdb-0.0.1/README.md +346 -0
- plasticdb-0.0.1/pyproject.toml +95 -0
- plasticdb-0.0.1/src/plasticdb/__init__.py +97 -0
- plasticdb-0.0.1/src/plasticdb/__main__.py +5 -0
- plasticdb-0.0.1/src/plasticdb/_cache.py +176 -0
- plasticdb-0.0.1/src/plasticdb/_client.py +642 -0
- plasticdb-0.0.1/src/plasticdb/_download.py +195 -0
- plasticdb-0.0.1/src/plasticdb/_endpoints.py +67 -0
- plasticdb-0.0.1/src/plasticdb/_fasta.py +53 -0
- plasticdb-0.0.1/src/plasticdb/_inputs.py +229 -0
- plasticdb-0.0.1/src/plasticdb/_pagination.py +437 -0
- plasticdb-0.0.1/src/plasticdb/_response.py +244 -0
- plasticdb-0.0.1/src/plasticdb/_version.py +1 -0
- plasticdb-0.0.1/src/plasticdb/cli/__init__.py +40 -0
- plasticdb-0.0.1/src/plasticdb/cli/_app.py +1330 -0
- plasticdb-0.0.1/src/plasticdb/cli/_config.py +113 -0
- plasticdb-0.0.1/src/plasticdb/cli/_core.py +686 -0
- plasticdb-0.0.1/src/plasticdb/cli/_output.py +250 -0
- plasticdb-0.0.1/src/plasticdb/errors.py +335 -0
- plasticdb-0.0.1/src/plasticdb/models/__init__.py +151 -0
- plasticdb-0.0.1/src/plasticdb/models/_base.py +51 -0
- plasticdb-0.0.1/src/plasticdb/models/catalogue.py +405 -0
- plasticdb-0.0.1/src/plasticdb/models/common.py +302 -0
- plasticdb-0.0.1/src/plasticdb/models/jobs.py +339 -0
- plasticdb-0.0.1/src/plasticdb/models/other.py +292 -0
- plasticdb-0.0.1/src/plasticdb/models/releases.py +84 -0
- plasticdb-0.0.1/src/plasticdb/py.typed +0 -0
- plasticdb-0.0.1/src/plasticdb/resources/__init__.py +25 -0
- plasticdb-0.0.1/src/plasticdb/resources/_base.py +13 -0
- plasticdb-0.0.1/src/plasticdb/resources/_filters.py +227 -0
- plasticdb-0.0.1/src/plasticdb/resources/catalogue.py +277 -0
- plasticdb-0.0.1/src/plasticdb/resources/downloads.py +251 -0
- plasticdb-0.0.1/src/plasticdb/resources/evidence.py +272 -0
- plasticdb-0.0.1/src/plasticdb/resources/jobs.py +932 -0
- plasticdb-0.0.1/src/plasticdb/resources/proteins.py +318 -0
- plasticdb-0.0.1/src/plasticdb/resources/releases.py +51 -0
- plasticdb-0.0.1/tests/__init__.py +0 -0
- plasticdb-0.0.1/tests/conftest.py +68 -0
- plasticdb-0.0.1/tests/contract/sdk-v1.json +35156 -0
- plasticdb-0.0.1/tests/fixtures/autocomplete.json +35 -0
- plasticdb-0.0.1/tests/fixtures/bad_param.json +23 -0
- plasticdb-0.0.1/tests/fixtures/binding_assays.json +13 -0
- plasticdb-0.0.1/tests/fixtures/changes.json +39 -0
- plasticdb-0.0.1/tests/fixtures/constructs.json +89 -0
- plasticdb-0.0.1/tests/fixtures/engineering.json +44 -0
- plasticdb-0.0.1/tests/fixtures/fasta_one.json +9 -0
- plasticdb-0.0.1/tests/fixtures/job_annotate_list.json +100 -0
- plasticdb-0.0.1/tests/fixtures/job_compare.json +151 -0
- plasticdb-0.0.1/tests/fixtures/job_compare_results.json +131 -0
- plasticdb-0.0.1/tests/fixtures/job_done.json +92 -0
- plasticdb-0.0.1/tests/fixtures/job_done_results.json +131 -0
- plasticdb-0.0.1/tests/fixtures/job_error.json +64 -0
- plasticdb-0.0.1/tests/fixtures/job_hmm.json +98 -0
- plasticdb-0.0.1/tests/fixtures/job_hmm_results.json +32 -0
- plasticdb-0.0.1/tests/fixtures/job_pathway.json +154 -0
- plasticdb-0.0.1/tests/fixtures/job_release_unsupported.json +21 -0
- plasticdb-0.0.1/tests/fixtures/job_running.json +64 -0
- plasticdb-0.0.1/tests/fixtures/job_submitted.json +62 -0
- plasticdb-0.0.1/tests/fixtures/jobs_list.json +147 -0
- plasticdb-0.0.1/tests/fixtures/microorganism.json +354 -0
- plasticdb-0.0.1/tests/fixtures/microorganisms.json +161 -0
- plasticdb-0.0.1/tests/fixtures/not_found.json +10 -0
- plasticdb-0.0.1/tests/fixtures/paper.json +41 -0
- plasticdb-0.0.1/tests/fixtures/papers.json +36 -0
- plasticdb-0.0.1/tests/fixtures/pathway.json +88 -0
- plasticdb-0.0.1/tests/fixtures/pathway_graph.json +67 -0
- plasticdb-0.0.1/tests/fixtures/pathways.json +19 -0
- plasticdb-0.0.1/tests/fixtures/pathways_by_plastic.json +90 -0
- plasticdb-0.0.1/tests/fixtures/plastic.json +241 -0
- plasticdb-0.0.1/tests/fixtures/plastics.json +46 -0
- plasticdb-0.0.1/tests/fixtures/plastics_names.json +21 -0
- plasticdb-0.0.1/tests/fixtures/preparations.json +101 -0
- plasticdb-0.0.1/tests/fixtures/protein.json +1340 -0
- plasticdb-0.0.1/tests/fixtures/protein_interactions.json +226 -0
- plasticdb-0.0.1/tests/fixtures/protein_kinetics.json +148 -0
- plasticdb-0.0.1/tests/fixtures/protein_merged.json +15 -0
- plasticdb-0.0.1/tests/fixtures/protein_merged_kinetics.json +15 -0
- plasticdb-0.0.1/tests/fixtures/protein_properties.json +78 -0
- plasticdb-0.0.1/tests/fixtures/protein_variant_redirect.json +14 -0
- plasticdb-0.0.1/tests/fixtures/protein_variant_subresource.json +15 -0
- plasticdb-0.0.1/tests/fixtures/protein_variants.json +337 -0
- plasticdb-0.0.1/tests/fixtures/proteins.json +156 -0
- plasticdb-0.0.1/tests/fixtures/release_unknown.json +12 -0
- plasticdb-0.0.1/tests/fixtures/search.json +32 -0
- plasticdb-0.0.1/tests/fixtures/search_grouped.json +77 -0
- plasticdb-0.0.1/tests/fixtures/search_sequence.json +42 -0
- plasticdb-0.0.1/tests/fixtures/share_created.json +15 -0
- plasticdb-0.0.1/tests/fixtures/shares.json +22 -0
- plasticdb-0.0.1/tests/fixtures/stats.json +19 -0
- plasticdb-0.0.1/tests/fixtures/stats_activity.json +33 -0
- plasticdb-0.0.1/tests/fixtures/taxonomy.json +60 -0
- plasticdb-0.0.1/tests/fixtures/tree_detail.json +68 -0
- plasticdb-0.0.1/tests/fixtures/tree_done.json +66 -0
- plasticdb-0.0.1/tests/fixtures/unknown_release.json +12 -0
- plasticdb-0.0.1/tests/fixtures/variant.json +498 -0
- plasticdb-0.0.1/tests/fixtures/variant_merged.json +15 -0
- plasticdb-0.0.1/tests/fixtures/variant_removed.json +12 -0
- plasticdb-0.0.1/tests/fixtures/variants_list.json +156 -0
- plasticdb-0.0.1/tests/test_cache.py +99 -0
- plasticdb-0.0.1/tests/test_catalogue.py +470 -0
- plasticdb-0.0.1/tests/test_cli.py +672 -0
- plasticdb-0.0.1/tests/test_client.py +135 -0
- plasticdb-0.0.1/tests/test_collections.py +385 -0
- plasticdb-0.0.1/tests/test_contract.py +186 -0
- plasticdb-0.0.1/tests/test_downloads.py +407 -0
- plasticdb-0.0.1/tests/test_errors.py +255 -0
- plasticdb-0.0.1/tests/test_job_inputs.py +151 -0
- plasticdb-0.0.1/tests/test_jobs.py +987 -0
- plasticdb-0.0.1/tests/test_pagination.py +151 -0
- plasticdb-0.0.1/tests/test_pinned_data.py +216 -0
- plasticdb-0.0.1/tests/test_provenance.py +132 -0
- plasticdb-0.0.1/tests/test_releases.py +78 -0
- plasticdb-0.0.1/tests/test_retries.py +155 -0
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.0.1 (2026-11-19)
|
|
4
|
+
|
|
5
|
+
- Server 2.87.1: `proteins.fasta()` is pinnable (served from the release snapshot;
|
|
6
|
+
a ref not in the pinned release is a plain `NotFoundError`, no merge
|
|
7
|
+
redirect). Contract re-vendored; a job download 410 with `reason: "expired"`
|
|
8
|
+
is `ResultsExpiredError`, one without (an expired share link) is `GoneError`.
|
|
9
|
+
- Server 2.86.0 and 2.87.0 (re-vendored SDK contract, fixtures re-captured live):
|
|
10
|
+
- Job submissions, tree builds and share links send an `Idempotency-Key` (a
|
|
11
|
+
new UUID per call, or `idempotency_key=` / `--idempotency-key`), the same on
|
|
12
|
+
every retry, so they are now retried like reads on a timeout, a dropped
|
|
13
|
+
connection or a 5xx. A replay is `job.replayed`; when retries run out the
|
|
14
|
+
error names the key to resubmit with. `IdempotencyKeyReusedError` (422) for
|
|
15
|
+
a key reused with a different request. Without an API key (which the server
|
|
16
|
+
needs to honour the key) a `POST` is still never resent after it may have
|
|
17
|
+
reached the server.
|
|
18
|
+
- Polling and `jobs.get()` / `jobs.shared()` ask for `?include=none`;
|
|
19
|
+
`Job.hits()` / `results()` page `GET /jobs/{id}/results` (and the share
|
|
20
|
+
link's `/results`), `Job.iter_hits()` lazily. A tree job reads its Newick
|
|
21
|
+
from `GET /jobs/{id}`; `/tree/{id}` is no longer called.
|
|
22
|
+
- `Job.provenance` and `Job.release` fall back to the job read's
|
|
23
|
+
`X-PlasticDB-Release` / `-Source` headers.
|
|
24
|
+
- `pathway_analysis(target_plastic=)` (CLI `--target-plastic`);
|
|
25
|
+
`annotate_list` documents the server's 7/8/`tab` defaults.
|
|
26
|
+
- Record redirects are told apart by `reason` (`merged` or
|
|
27
|
+
`engineered_variant`), not by comparing accessions; `MergedError.kind` can
|
|
28
|
+
be `microorganism`, so `microorganisms.get(follow_merges=True)` follows
|
|
29
|
+
organism merges. A merged sub-resource raises `MergedError` with the
|
|
30
|
+
survivor's sub-resource `location`.
|
|
31
|
+
- `EngineeredVariantError` is now a `NotFoundError` and carries
|
|
32
|
+
`merged_into`; it is raised for the server's 404 `engineered_variant` on a
|
|
33
|
+
variant's per-protein sub-resources. `proteins.fasta()` / `structure()` of a
|
|
34
|
+
variant accession return the variant's.
|
|
35
|
+
- A withdrawn record (also a variant whose parent was withdrawn, formerly a
|
|
36
|
+
404) is a `GoneError` with `.accession` and `.reason == "withdrawn"`.
|
|
37
|
+
Every error now carries the server's `.reason`.
|
|
38
|
+
- `ResultsExpiredError` (a `GoneError`, `.results_expired_at`) for a job's
|
|
39
|
+
deleted result files, before or from the server's 410 `expired`.
|
|
40
|
+
- `variants.get()` and `variants.fasta()` are pinnable (answered from the
|
|
41
|
+
release snapshot); `variants.structure()` stays live only.
|
|
42
|
+
- `evidence_scope="enzyme_only"` on `microorganisms.get()` and
|
|
43
|
+
`stats.summary()` (CLI `stats --evidence-scope`); `proteins.get()` takes a
|
|
44
|
+
numeric id.
|
|
45
|
+
- `search_sequence()`: a 503 (`index_unavailable` / `binary_unavailable`) is
|
|
46
|
+
`ServiceUnavailableError` with `.retry_after`; a 504 `timeout` is a
|
|
47
|
+
`ServerError` that is not retried (CLI exit 8); it is retried on other 5xx.
|
|
48
|
+
- Downloads: a cached pinned table is revalidated with its `ETag`
|
|
49
|
+
(`If-None-Match`; 304 uses the copy, offline too); an artefact is also
|
|
50
|
+
checked against the server's `X-PlasticDB-SHA256`. `APIResponse.etag`,
|
|
51
|
+
`.sha256`, `.source_sha256` and `.replayed`.
|
|
52
|
+
- `dataset.zip`'s JSON 503 (`archive_unavailable`) keeps `.retry_after`.
|
|
53
|
+
- Every public error is exported from `plasticdb` (`UnknownReleaseError`,
|
|
54
|
+
`ReleaseNotMountedError`, `ReleaseNoArtefactsError`, `BadRequestError`,
|
|
55
|
+
`ConflictError`, `UnexpectedResponseError` were only in `plasticdb.errors`),
|
|
56
|
+
and the README and errors page list them all.
|
|
57
|
+
|
|
58
|
+
- Documentation site (MkDocs Material, mkdocstrings API reference) published to
|
|
59
|
+
GitHub Pages: quick start, reproducibility with pinned releases, data and jobs
|
|
60
|
+
guides, a CLI reference generated from the Typer app, errors, Snakemake and
|
|
61
|
+
Nextflow workflows and an example notebook. `make docs` builds it;
|
|
62
|
+
`requirements-docs.txt` lists its dependencies.
|
|
63
|
+
- The `plasticdb` command-line tool (`pip install 'plasticdb[cli]'`; also
|
|
64
|
+
`python -m plasticdb`). It is a thin layer over the SDK, with commands for
|
|
65
|
+
proteins, variants, microorganisms, plastics, papers, evidence, search,
|
|
66
|
+
pathways, stats, changes, releases, downloads, jobs, auth, cite, provenance
|
|
67
|
+
and version.
|
|
68
|
+
- Data goes to stdout as `--format tsv|csv|json|jsonl|fasta`, or to
|
|
69
|
+
`-o FILE`, where the extension picks the format. Messages go to stderr.
|
|
70
|
+
- There are no prompts unless `--interactive` is given.
|
|
71
|
+
- `--release`, `--api-key`, `--base-url`, `--cache-dir`, `-q` and `-v` are
|
|
72
|
+
accepted before or after the subcommand, with matching `PLASTICDB_*`
|
|
73
|
+
environment variables.
|
|
74
|
+
- Filter and keyword options are generated from the SDK's own filter types
|
|
75
|
+
and method signatures.
|
|
76
|
+
- `auth login|logout|status` keeps the key in a 0600 config file. The
|
|
77
|
+
environment variable wins over the file.
|
|
78
|
+
- `download dataset --release V -o DIR` fetches and verifies every artefact
|
|
79
|
+
the release published.
|
|
80
|
+
- `jobs submit TYPE INPUT --wait -o FILE` takes kebab-case job types.
|
|
81
|
+
- `cite --format bibtex`.
|
|
82
|
+
- Exit codes are documented and stable: 0 ok, 1 error, 2 usage, 3 not found,
|
|
83
|
+
4 auth, 5 rate limited, 6 release, 7 job failed, 8 timeout,
|
|
84
|
+
9 unavailable, 130 interrupted.
|
|
85
|
+
- `releases.get()` on an unknown version raises `UnknownReleaseError`, which is
|
|
86
|
+
still a `NotFoundError`.
|
|
87
|
+
- Downloaded files get the usual permissions (0666 less the umask) instead of
|
|
88
|
+
`mkstemp`'s 0600.
|
|
89
|
+
|
|
90
|
+
- Jobs (`client.jobs`): `submit(job_type, input, **params)` and a typed helper
|
|
91
|
+
per server job type: `annotate_gene`, `annotate_genome`, `compare_genomes`,
|
|
92
|
+
`annotate_list`, `pathway_analysis`, `hmm_screen`, `build_tree`, plus the
|
|
93
|
+
synchronous `search_sequence`. Jobs need an API key (`AuthenticationError`
|
|
94
|
+
before any request otherwise); a pinned client, or `release=`, runs them
|
|
95
|
+
against that release's archived databases.
|
|
96
|
+
- `Job`: `refresh()`, `wait(timeout=, poll_interval=)` with backoff and
|
|
97
|
+
`Retry-After`, `status`, `results()` (`hits()`, `steps()`, `taxa()`,
|
|
98
|
+
`tree()`, typed, with `to_pandas()` / `to_polars()`), `comparison()`,
|
|
99
|
+
streaming `download(path)` (TSV or the compare_genomes ZIP),
|
|
100
|
+
`share()` / `shares()` / `unshare()`, and `provenance` (release,
|
|
101
|
+
reference SHA-256, tool versions). `jobs.get(id)`, `jobs.list()`,
|
|
102
|
+
`jobs.shared(link)`.
|
|
103
|
+
- Inputs: a path (plain or gzip), FASTA text, bytes, a file object,
|
|
104
|
+
`Bio.SeqRecord`s, or table rows; uploads are named after their contents.
|
|
105
|
+
- Submissions are never resent once they may have reached the server; a 429 is
|
|
106
|
+
waited out within `max_retry_wait`.
|
|
107
|
+
- New errors: `PayloadTooLargeError` (413), `JobError`, `JobFailedError`,
|
|
108
|
+
`JobTimeoutError`. `plasticdb.ResultTable` for in-memory typed results.
|
|
109
|
+
- The contract test covers every job, share, tree and sequence-search operation.
|
|
110
|
+
|
|
111
|
+
- Data namespaces on `Client`: `proteins`, `variants`, `microorganisms`,
|
|
112
|
+
`plastics`, `papers`, `evidence` (interactions, kinetics, properties, binding
|
|
113
|
+
assays, constructs, preparations), `search`, `pathways`, `stats`,
|
|
114
|
+
`downloads`, and `changes(since=)`. Filters are the API's own parameter
|
|
115
|
+
names; an unknown one is a `TypeError`.
|
|
116
|
+
- Typed models for every record and list item (unknown fields kept).
|
|
117
|
+
- Collections: `rows()`, and `to_pandas()` / `to_polars()` with nested objects
|
|
118
|
+
flattened to `parent.child` columns; interactions at `interaction`,
|
|
119
|
+
`experiment` or `observation` level; `to_fasta()` / `to_biopython()` on
|
|
120
|
+
sequence-carrying collections (protein lists via the server's FASTA download).
|
|
121
|
+
- Bulk pulls (`all()` and the conversions) fetch 500-record pages, up to
|
|
122
|
+
`max_concurrency` (default 4) at a time, and go sequential when the
|
|
123
|
+
rate-limit allowance is low.
|
|
124
|
+
- Merged records: `get()` raises `MergedError` by default; `follow_merges=True`
|
|
125
|
+
returns the survivor with a `MergedRecordWarning`. `proteins.get()` on a
|
|
126
|
+
variant accession returns the `Variant`; sub-collections raise
|
|
127
|
+
`EngineeredVariantError`.
|
|
128
|
+
- Streaming downloads to a file or directory, following redirects, with
|
|
129
|
+
SHA-256 verification of release artefacts (`ChecksumError`). Pinned
|
|
130
|
+
downloads and release artefacts are cached in `cache_dir`.
|
|
131
|
+
`ServiceUnavailableError.retry_after`; `downloads.dataset(max_wait=)`.
|
|
132
|
+
- Live-only endpoints are marked in the registry and checked against the
|
|
133
|
+
contract's 409s; the contract test also fails on an operation the SDK
|
|
134
|
+
neither wraps nor lists as deliberately unwrapped.
|
|
135
|
+
|
|
136
|
+
### Foundation
|
|
137
|
+
|
|
138
|
+
- First release: `Client` with API-key auth, release pinning (`?release=`),
|
|
139
|
+
retries honouring `Retry-After`, a typed exception hierarchy, provenance,
|
|
140
|
+
citation, an on-disk cache for pinned answers, and `client.releases`
|
|
141
|
+
(`current`, `get`, `list`, `status`).
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use this software, please cite it. Cite the PlasticDB dataset release and paper for the data (CC BY 4.0)."
|
|
3
|
+
title: "plasticdb: Python client for the PlasticDB API"
|
|
4
|
+
type: software
|
|
5
|
+
authors:
|
|
6
|
+
- family-names: Gambarini
|
|
7
|
+
given-names: Victor
|
|
8
|
+
license: MIT
|
|
9
|
+
version: 0.0.1
|
|
10
|
+
repository-code: "https://github.com/VictorGambarini/plasticdb-py"
|
|
11
|
+
url: "https://v2.plasticdb.org"
|
|
12
|
+
preferred-citation:
|
|
13
|
+
type: article
|
|
14
|
+
title: "PlasticDB: a database of microorganisms and proteins linked to plastic biodegradation"
|
|
15
|
+
authors:
|
|
16
|
+
- family-names: Gambarini
|
|
17
|
+
given-names: Victor
|
|
18
|
+
- family-names: Pantos
|
|
19
|
+
given-names: Olga
|
|
20
|
+
- family-names: Kingsbury
|
|
21
|
+
given-names: Joanne M.
|
|
22
|
+
- family-names: Weaver
|
|
23
|
+
given-names: Louise
|
|
24
|
+
- family-names: Handley
|
|
25
|
+
given-names: Kim M.
|
|
26
|
+
- family-names: Lear
|
|
27
|
+
given-names: Gavin
|
|
28
|
+
journal: Database
|
|
29
|
+
year: 2022
|
|
30
|
+
volume: 2022
|
|
31
|
+
start: baac008
|
|
32
|
+
doi: 10.1093/database/baac008
|
plasticdb-0.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Victor Gambarini
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
plasticdb-0.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: plasticdb
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Python client for the PlasticDB API: plastic-degrading microorganisms, proteins and the evidence behind them.
|
|
5
|
+
Project-URL: Homepage, https://v2.plasticdb.org
|
|
6
|
+
Project-URL: Documentation, https://victorgambarini.github.io/plasticdb-py/
|
|
7
|
+
Project-URL: Source, https://github.com/VictorGambarini/plasticdb-py
|
|
8
|
+
Project-URL: Issues, https://github.com/VictorGambarini/plasticdb-py/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/VictorGambarini/plasticdb-py/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: API reference, https://v2.plasticdb.org/api/v1/docs
|
|
11
|
+
Author: Victor Gambarini
|
|
12
|
+
License-Expression: MIT
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Keywords: api-client,biodegradation,bioinformatics,database,enzymes,plastic
|
|
15
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
16
|
+
Classifier: Intended Audience :: Science/Research
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Requires-Dist: httpx<1,>=0.25
|
|
28
|
+
Requires-Dist: pydantic<3,>=2.5
|
|
29
|
+
Requires-Dist: typing-extensions>=4.6
|
|
30
|
+
Provides-Extra: all
|
|
31
|
+
Requires-Dist: biopython>=1.81; extra == 'all'
|
|
32
|
+
Requires-Dist: pandas>=1.5; extra == 'all'
|
|
33
|
+
Requires-Dist: polars>=0.20; extra == 'all'
|
|
34
|
+
Requires-Dist: typer>=0.12; extra == 'all'
|
|
35
|
+
Provides-Extra: bio
|
|
36
|
+
Requires-Dist: biopython>=1.81; extra == 'bio'
|
|
37
|
+
Provides-Extra: cli
|
|
38
|
+
Requires-Dist: typer>=0.12; extra == 'cli'
|
|
39
|
+
Provides-Extra: pandas
|
|
40
|
+
Requires-Dist: pandas>=1.5; extra == 'pandas'
|
|
41
|
+
Provides-Extra: polars
|
|
42
|
+
Requires-Dist: polars>=0.20; extra == 'polars'
|
|
43
|
+
Description-Content-Type: text/markdown
|
|
44
|
+
|
|
45
|
+
# plasticdb
|
|
46
|
+
|
|
47
|
+
Python client for the [PlasticDB](https://v2.plasticdb.org) API: microorganisms
|
|
48
|
+
and proteins linked to plastic biodegradation, and the evidence behind them.
|
|
49
|
+
|
|
50
|
+
> **Pre-alpha.** This release covers the client core, dataset releases, every
|
|
51
|
+
> public data endpoint, the analysis jobs and the `plasticdb` command-line tool.
|
|
52
|
+
|
|
53
|
+
**Documentation: <https://victorgambarini.github.io/plasticdb-py/>** (quick start,
|
|
54
|
+
reproducibility with pinned releases, jobs, CLI reference, Snakemake and Nextflow
|
|
55
|
+
examples, API reference).
|
|
56
|
+
|
|
57
|
+
## Install
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pip install plasticdb
|
|
61
|
+
# optional extras
|
|
62
|
+
pip install "plasticdb[pandas]" # or polars, bio, cli, all
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Python 3.10 or newer. The core install needs only `httpx` and `pydantic`.
|
|
66
|
+
|
|
67
|
+
## Quick start
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
import plasticdb
|
|
71
|
+
|
|
72
|
+
client = plasticdb.Client()
|
|
73
|
+
|
|
74
|
+
# Proteins with positive evidence on PET, as a table and as sequences
|
|
75
|
+
pet = client.proteins.list(plastic="PET", kind="wild_type")
|
|
76
|
+
print(pet.total) # 468
|
|
77
|
+
df = pet.to_pandas() # one flat row per protein
|
|
78
|
+
pet.to_fasta("pet_enzymes.fasta") # >PB8CAZ E4 ...
|
|
79
|
+
records = pet.to_biopython() # Bio.SeqRecord list (plasticdb[bio])
|
|
80
|
+
|
|
81
|
+
# One record, with its evidence
|
|
82
|
+
petase = client.proteins.get("PBFCTW")
|
|
83
|
+
print(petase.name, len(petase.sequence or ""), petase.source_microorganism.name)
|
|
84
|
+
|
|
85
|
+
# The evidence spine: interaction -> experiment -> observation
|
|
86
|
+
evidence = client.evidence.interactions("PBFCTW")
|
|
87
|
+
measurements = evidence.to_pandas(level="observation") # one row per measured value
|
|
88
|
+
|
|
89
|
+
# Engineered variants of PETase, with sequences
|
|
90
|
+
client.proteins.variants("PBFCTW").to_fasta("petase_variants.fasta")
|
|
91
|
+
|
|
92
|
+
# Organisms, plastics, papers
|
|
93
|
+
client.microorganisms.list(genus="Pseudomonas", plastic="PET").to_polars()
|
|
94
|
+
client.microorganisms.get(1547922) # NCBI tax-id or PB… accession
|
|
95
|
+
client.plastics.get(16, protein_limit=10) # PET, with one page of proteins
|
|
96
|
+
client.papers.list(protein="PBFCTW", min_year=2020).all()
|
|
97
|
+
|
|
98
|
+
# Search, pathways, statistics, the change feed
|
|
99
|
+
client.search("cutinase").first()
|
|
100
|
+
client.pathways.graph(16).to_networkx()
|
|
101
|
+
client.stats.summary()
|
|
102
|
+
feed = client.changes(since="2026-11-01T00:00:00Z")
|
|
103
|
+
for change in feed: # status: updated, merged or removed
|
|
104
|
+
...
|
|
105
|
+
next_since = feed.as_of
|
|
106
|
+
|
|
107
|
+
# Files
|
|
108
|
+
client.downloads.proteins("data/", format="csv", plastic="PET")
|
|
109
|
+
client.downloads.dataset("data/") # every public record, ZIP of CSVs
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Every list is a lazy `Collection`: nothing is fetched until you iterate it, and
|
|
113
|
+
`len()` is the server's total. `all()`, `rows()`, `to_pandas()`, `to_polars()`
|
|
114
|
+
and `to_fasta()` fetch the remaining pages at 500 records each, up to four at
|
|
115
|
+
a time (`Client(max_concurrency=)`; it drops to one when the rate-limit
|
|
116
|
+
allowance runs low, and a 429 waits for `Retry-After`).
|
|
117
|
+
|
|
118
|
+
### Filters
|
|
119
|
+
|
|
120
|
+
Keyword arguments are the API's own query parameters, with the same meaning on
|
|
121
|
+
every resource (the server's
|
|
122
|
+
[conventions](https://v2.plasticdb.org/api/v1/docs)): `plastic`,
|
|
123
|
+
`include_subtypes`, `microorganism`, `polarity`, `include_negative`,
|
|
124
|
+
`evidence_method`, `min_year`/`max_year`, `updated_since`, `sort_by` /
|
|
125
|
+
`sort_order` and so on. The rank `class` is spelled `class_`. An unknown name
|
|
126
|
+
is a `TypeError` naming the valid ones; an unknown value is a server 422
|
|
127
|
+
(`ValidationError`). Entity lists default to records with a **positive** result,
|
|
128
|
+
as on the website: pass `polarity="negative"` or `include_negative=True` for the
|
|
129
|
+
rest.
|
|
130
|
+
|
|
131
|
+
### Tables
|
|
132
|
+
|
|
133
|
+
`to_pandas()` / `to_polars()` give one flat row per record: nested objects
|
|
134
|
+
become `parent.child` columns (`source_microorganism.name`, `paper.doi`), lists
|
|
135
|
+
of plain values stay lists, and per-plastic evidence becomes `plastics_positive`
|
|
136
|
+
/ `plastics_negative` / `plastics_inconclusive`. `records()` keeps the full JSON
|
|
137
|
+
nesting. Interactions take `level="interaction" | "experiment" | "observation"`.
|
|
138
|
+
|
|
139
|
+
### Sequences
|
|
140
|
+
|
|
141
|
+
`.to_fasta()` and `.to_biopython()` work on every collection that carries
|
|
142
|
+
sequences: protein and variant lists, a protein's variants, constructs. Protein
|
|
143
|
+
list items carry no sequence, so the SDK downloads `proteins.fasta` once with the
|
|
144
|
+
same filters and keeps the listed records, in list order. FASTA ids are the
|
|
145
|
+
accessions (`PlasticDB_<id>` for the few records without one), as in the
|
|
146
|
+
server's own files. Single records have `.to_fasta()` too.
|
|
147
|
+
|
|
148
|
+
### Merged and withdrawn records
|
|
149
|
+
|
|
150
|
+
Records are sometimes merged (two accessions for one molecule). `get()` on a
|
|
151
|
+
merged protein, variant or microorganism raises `plasticdb.MergedError` with
|
|
152
|
+
`.merged_into`, the survivor, and `.kind` (`wild_type`, `engineered` or
|
|
153
|
+
`microorganism`). Pass `follow_merges=True` to get the survivor instead, with a
|
|
154
|
+
`plasticdb.MergedRecordWarning`. A withdrawn record (also a variant whose parent
|
|
155
|
+
protein was withdrawn) raises `GoneError` with `.accession` and
|
|
156
|
+
`.reason == "withdrawn"` (`MergedError` is a subclass, so `except GoneError`
|
|
157
|
+
catches both). An engineered variant's accession given to `proteins.get()`
|
|
158
|
+
returns the `Variant`; the per-protein collections (`interactions`, `kinetics`,
|
|
159
|
+
…) raise `EngineeredVariantError` (a `NotFoundError`) for it. A past release
|
|
160
|
+
never contains merged records, so a pinned `get()` answers `NotFoundError` for
|
|
161
|
+
them. `client.changes()` lists merges with their survivors.
|
|
162
|
+
|
|
163
|
+
### Jobs
|
|
164
|
+
|
|
165
|
+
Annotation, genome comparison, pathway analysis, HMM screens and taxonomy trees
|
|
166
|
+
run on the server as jobs. Jobs need an API key (create one under *Profile → API
|
|
167
|
+
keys* on the website; `Client(api_key=)` or `PLASTICDB_API_KEY`); without one
|
|
168
|
+
the call raises `AuthenticationError` before anything is sent.
|
|
169
|
+
|
|
170
|
+
```python
|
|
171
|
+
client = plasticdb.Client(release="2026.30") # jobs run against that release's databases
|
|
172
|
+
|
|
173
|
+
job = client.jobs.annotate_genome("genome.faa.gz", evalue=1e-10)
|
|
174
|
+
job.wait() # polls with backoff; JobFailedError if the job fails
|
|
175
|
+
hits = job.results() # every hit, typed (JobHit), paged from the server; .to_pandas()
|
|
176
|
+
job.download("results/") # the server's TSV, with its provenance header
|
|
177
|
+
job.provenance # release, reference_sha256, tool_versions, full record
|
|
178
|
+
|
|
179
|
+
genomes = client.jobs.compare_genomes({"K-12": "ecoli.faa", "201-F6": "isak.faa.gz"})
|
|
180
|
+
genomes.wait().comparison().to_pandas() # genome x plastic matrix
|
|
181
|
+
genomes.download("compare.zip") # per-genome hits, matrix, provenance.json
|
|
182
|
+
|
|
183
|
+
client.jobs.hmm_screen(records, target_polymers=["PET", "PLA"]) # Bio.SeqRecord list
|
|
184
|
+
client.jobs.pathway_analysis("proteins.faa", target_plastic="PET").wait().steps()
|
|
185
|
+
client.jobs.annotate_list("taxa.csv", genus_column=1, species_column=2, field_separator="comma")
|
|
186
|
+
client.jobs.build_tree(plastic="PET", genus="Pseudomonas").wait().tree().newick
|
|
187
|
+
client.jobs.annotate_gene(">q\nMNFPRASRLMQAAVLGG...") # FASTA text, bytes, a file object
|
|
188
|
+
client.jobs.search_sequence("MNFPRASRLMQ...") # synchronous DIAMOND search, no job
|
|
189
|
+
|
|
190
|
+
link = job.share(expires_in_days=30) # read-only link; the token is shown once
|
|
191
|
+
client.jobs.shared(link.url).results() # anyone with the link, no key needed
|
|
192
|
+
job.shares()
|
|
193
|
+
job.unshare(link)
|
|
194
|
+
client.jobs.list().to_pandas() # your jobs; client.jobs.get(id) to resume one
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| Job type (`jobs.submit(name, ...)`) | Helper | Input | Results |
|
|
198
|
+
|---|---|---|---|
|
|
199
|
+
| `annotate_gene`, `annotate_genome` | `annotate_gene()`, `annotate_genome()` | protein (or with `blast_type="blastx"` nucleotide) FASTA | `hits()` |
|
|
200
|
+
| `compare_genomes` | `compare_genomes()` | 2-20 genomes: a list or `{label: genome}` | `hits()`, `comparison()`, ZIP download |
|
|
201
|
+
| `pathway_analysis` | `pathway_analysis()` | protein FASTA (`target_plastic`, default `PET`) | `steps()` |
|
|
202
|
+
| `hmm_screen` | `hmm_screen()` | protein FASTA | `hits()` (profiles), `info.result_metadata["polymer_hits"]` |
|
|
203
|
+
| `annotate_list` | `annotate_list()` | a taxa table (path, text or rows); genus/species columns 7 and 8 unless given | `taxa()` |
|
|
204
|
+
| `build_tree` | `build_tree(**filters)` | organism filters or `microorganism_ids` | `tree()` (Newick + matrix) |
|
|
205
|
+
|
|
206
|
+
Each helper takes the server's own parameter names (`evalue`, `pident`,
|
|
207
|
+
`include_variants`, `min_scov`, `threshold_mode`, `min_step_identity`, …); an
|
|
208
|
+
unknown one is a `TypeError`. A FASTA input is a path (plain or gzip), FASTA
|
|
209
|
+
text, bytes, a file object, or `Bio.SeqRecord`s. Uploads are named after their
|
|
210
|
+
contents (`.gz` exactly when the bytes are gzip), and a genome's label is the
|
|
211
|
+
name its rows carry in the results. Polling asks for the job without its hits;
|
|
212
|
+
`results()` pages every stored hit from the server (`job.iter_hits()` is the
|
|
213
|
+
lazy version); the
|
|
214
|
+
website and `download()` start from the job's default view (hits covering at
|
|
215
|
+
least 70 % of the reference), which `download(scov=0)` or `all_hits=True` turns off.
|
|
216
|
+
|
|
217
|
+
A pinned client (or `release=` on the call) runs the job against that release's
|
|
218
|
+
archived DIAMOND databases, HMM library or tables; what a release cannot answer
|
|
219
|
+
raises `UnsupportedFilterError` (422) and an unknown release
|
|
220
|
+
`UnknownReleaseError`. `job.wait(timeout=)` raises `JobTimeoutError` but leaves
|
|
221
|
+
the job running; call `wait()` again or `client.jobs.get(id)` later.
|
|
222
|
+
Submissions are rate-limited (30 an hour): a 429 is retried after `Retry-After`
|
|
223
|
+
when that is within `max_retry_wait`, otherwise it raises `RateLimitError`.
|
|
224
|
+
|
|
225
|
+
Every submission (a job, a tree, a share link) is sent with an
|
|
226
|
+
`Idempotency-Key`, a new UUID per call unless you pass `idempotency_key=`, and
|
|
227
|
+
every retry of it reuses that key. So a submission is retried like a read on a
|
|
228
|
+
timeout, a dropped connection or a 5xx: if an attempt did reach the server, the
|
|
229
|
+
server returns the job it already created (`job.replayed` is `True`) instead of
|
|
230
|
+
running a duplicate. When the retries run out the error names the key; submit
|
|
231
|
+
again with `idempotency_key=` that key within 24 hours to recover the job. The
|
|
232
|
+
same key with a different request raises `IdempotencyKeyReusedError`.
|
|
233
|
+
|
|
234
|
+
### Configuration
|
|
235
|
+
|
|
236
|
+
| Argument | Environment variable | Default |
|
|
237
|
+
|---|---|---|
|
|
238
|
+
| `api_key` | `PLASTICDB_API_KEY` | none (reads are anonymous; jobs need a key) |
|
|
239
|
+
| `release` | `PLASTICDB_RELEASE` | none (live database) |
|
|
240
|
+
| `base_url` | `PLASTICDB_BASE_URL` | `https://v2.plasticdb.org/api/v1` |
|
|
241
|
+
| `cache_dir` | | none |
|
|
242
|
+
| `timeout`, `max_retries`, `max_retry_wait` | | 30 s, 3, 60 s |
|
|
243
|
+
| `max_concurrency` | | 4 (parallel page requests in a bulk pull) |
|
|
244
|
+
|
|
245
|
+
Rate-limited requests (429) are retried after `Retry-After`; reads, sequence
|
|
246
|
+
searches and submissions (which carry an `Idempotency-Key`) are retried with
|
|
247
|
+
backoff on 5xx, timeouts and connection errors. A 503 `not_mounted` and a
|
|
248
|
+
sequence search's 504 `timeout` are not retried.
|
|
249
|
+
|
|
250
|
+
### Errors
|
|
251
|
+
|
|
252
|
+
Every exception subclasses `plasticdb.PlasticDBError` and carries the server's
|
|
253
|
+
`.reason` when it sent one; all are importable from `plasticdb`:
|
|
254
|
+
|
|
255
|
+
- connection: `APIConnectionError`, `APITimeoutError`, `UnexpectedResponseError`
|
|
256
|
+
- requests: `BadRequestError` (400), `AuthenticationError` (401),
|
|
257
|
+
`PermissionDenied` (403), `NotFoundError` (404), `ConflictError` (409),
|
|
258
|
+
`PayloadTooLargeError` (413), `ValidationError` (422, `.errors`),
|
|
259
|
+
`IdempotencyKeyReusedError` (422), `RateLimitError` (429, `.retry_after`),
|
|
260
|
+
`ServerError` (5xx), `ServiceUnavailableError` (503, `.retry_after`)
|
|
261
|
+
- records: `GoneError` (410, `.accession`), `MergedError` (301, `.merged_into`),
|
|
262
|
+
`EngineeredVariantError`, `ResultsExpiredError` (410, a job's files);
|
|
263
|
+
`MergedRecordWarning`
|
|
264
|
+
- releases: `ReleaseError`, `ReleaseNotAvailableError`, `UnknownReleaseError`,
|
|
265
|
+
`ReleaseNoArtefactsError`, `ReleaseNotMountedError`, `ReleaseUnsupportedError`,
|
|
266
|
+
`LiveOnlyError`, `UnsupportedFilterError`
|
|
267
|
+
- jobs and files: `JobError`, `JobFailedError`, `JobTimeoutError` (with `.job`),
|
|
268
|
+
`ChecksumError`
|
|
269
|
+
|
|
270
|
+
[Errors](https://victorgambarini.github.io/plasticdb-py/errors/) has the full
|
|
271
|
+
hierarchy and the HTTP status of each.
|
|
272
|
+
|
|
273
|
+
## Command line
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
pip install "plasticdb[cli]"
|
|
277
|
+
|
|
278
|
+
plasticdb proteins list --plastic PET --format fasta > pet.fasta
|
|
279
|
+
plasticdb download dataset --release 2026.50 -o data/
|
|
280
|
+
plasticdb jobs submit annotate-genome genome.fna --wait -o hits.tsv
|
|
281
|
+
plasticdb cite --release 2026.50
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
`plasticdb` is a thin layer over the SDK: each command is one `Client` call.
|
|
285
|
+
|
|
286
|
+
- **Output.** Data goes to stdout; messages, progress and warnings go to stderr.
|
|
287
|
+
`--format` picks `tsv`, `csv`, `json`, `jsonl` or (for sequences) `fasta`.
|
|
288
|
+
Lists default to `tsv` and single records to `json`. `-o FILE` writes to a
|
|
289
|
+
file, and the file's extension picks the format when `--format` is not given.
|
|
290
|
+
TSV is one line per record: lists are joined with `;`, nested objects are
|
|
291
|
+
JSON, and tabs and newlines inside values become spaces.
|
|
292
|
+
- **No prompts.** The tool never asks for anything unless you pass
|
|
293
|
+
`--interactive`, and only `auth login` ever asks.
|
|
294
|
+
- **Global options.** `--release`, `--api-key`, `--base-url`, `--cache-dir`,
|
|
295
|
+
`-q/--quiet` and `-v/--verbose` (`-vv` logs every request and retry) can go
|
|
296
|
+
before or after the subcommand. The environment variables are
|
|
297
|
+
`PLASTICDB_RELEASE`, `PLASTICDB_API_KEY`, `PLASTICDB_BASE_URL`,
|
|
298
|
+
`PLASTICDB_CACHE_DIR` and `PLASTICDB_CONFIG_DIR`.
|
|
299
|
+
- **Filters.** Filter options are the SDK's filter names: `--plastic`,
|
|
300
|
+
`--include-subtypes`, `--polarity`, `--min-year`, `--class`, `--sort-by` and
|
|
301
|
+
so on. They are generated from the SDK, so `plasticdb proteins list --help`
|
|
302
|
+
lists exactly what `client.proteins.list()` takes. `--limit/-n` caps a list.
|
|
303
|
+
|
|
304
|
+
| Command | What it does |
|
|
305
|
+
|---|---|
|
|
306
|
+
| `proteins list\|get\|fasta\|structure\|variants\|lineage` | proteins |
|
|
307
|
+
| `variants list\|get\|fasta\|structure\|of` | engineered variants |
|
|
308
|
+
| `microorganisms list\|get\|names\|taxonomy` | organisms |
|
|
309
|
+
| `plastics list\|get\|names` | the plastic vocabulary |
|
|
310
|
+
| `papers list\|get\|footprint\|export` | papers; `export` writes BibTeX or RIS |
|
|
311
|
+
| `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 |
|
|
312
|
+
| `search QUERY [--grouped]` | full-text search |
|
|
313
|
+
| `pathways list\|get\|for-plastic\|graph` | degradation pathways |
|
|
314
|
+
| `stats [--view summary\|protein-activity\|charts\|by-country]` | statistics |
|
|
315
|
+
| `changes --since TIME` | the change feed; the next `--since` is printed on stderr |
|
|
316
|
+
| `releases list\|current\|get\|status` | dataset releases |
|
|
317
|
+
| `download table\|dataset\|artefact\|manifest\|structure` | files (`-o` is a file or a directory) |
|
|
318
|
+
| `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`) |
|
|
319
|
+
| `jobs status\|wait\|results\|download\|share\|shares\|unshare\|list\|search-sequence` | your jobs; `JOB` is an id or a share link |
|
|
320
|
+
| `auth login\|logout\|status` | the stored API key |
|
|
321
|
+
| `cite [--format text\|bibtex\|json]` | how to cite the release and the paper |
|
|
322
|
+
| `provenance`, `version [--server]` | what answered, and the versions involved |
|
|
323
|
+
|
|
324
|
+
`download dataset` without a release saves the live database's ZIP. With
|
|
325
|
+
`--release`, `-o` is a directory, and it receives every artefact that release
|
|
326
|
+
published (Parquet tables, the reference databases, `MANIFEST.json`). Each file
|
|
327
|
+
is checked against its SHA-256. `jobs submit` prints the job id. With `--wait`
|
|
328
|
+
it also writes the results: `-o hits.tsv` saves the server's results file
|
|
329
|
+
(which carries provenance lines), and `--format` writes the typed results
|
|
330
|
+
instead. Each job parameter is an option named after its SDK keyword
|
|
331
|
+
(`--evalue`, `--target-polymers`, `--genus-column`, `--label`, …). The
|
|
332
|
+
`build-tree` filters are the `/microorganisms` filters. An input of `-` is
|
|
333
|
+
read from stdin.
|
|
334
|
+
|
|
335
|
+
### API key
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
pbpaste | plasticdb auth login # or: plasticdb auth login --interactive
|
|
339
|
+
plasticdb auth status # which key, and where it came from
|
|
340
|
+
plasticdb auth logout
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
`auth login` checks the key with the server, then saves it to
|
|
344
|
+
`$XDG_CONFIG_HOME/plasticdb/config.json` (`~/.config/plasticdb/`;
|
|
345
|
+
`%APPDATA%\plasticdb` on Windows; `$PLASTICDB_CONFIG_DIR` overrides it). The
|
|
346
|
+
file is mode 0600, in a 0700 directory, and the tool warns if the file becomes
|
|
347
|
+
readable by others. The key is read from stdin, or from `--key` (which leaves it
|
|
348
|
+
in your shell history), and it is never echoed. `--api-key` wins, then
|
|
349
|
+
`PLASTICDB_API_KEY`, then the file.
|
|
350
|
+
|
|
351
|
+
### Exit codes
|
|
352
|
+
|
|
353
|
+
| Code | Meaning |
|
|
354
|
+
|---|---|
|
|
355
|
+
| 0 | success |
|
|
356
|
+
| 1 | any other error |
|
|
357
|
+
| 2 | bad command line, option or parameter value (also a server 422) |
|
|
358
|
+
| 3 | no such record, or it was withdrawn or merged (the message names the survivor) |
|
|
359
|
+
| 4 | no API key, an invalid one, or not allowed |
|
|
360
|
+
| 5 | rate limited (429) beyond the retry budget |
|
|
361
|
+
| 6 | release unknown, unavailable, or unable to answer this (live-only endpoint, unsupported filter) |
|
|
362
|
+
| 7 | the job failed on the server |
|
|
363
|
+
| 8 | timed out (a request, or `--timeout` while waiting for a job; the job keeps running) |
|
|
364
|
+
| 9 | server unreachable or failing (5xx): retry later |
|
|
365
|
+
| 130 | interrupted (Ctrl-C) |
|
|
366
|
+
|
|
367
|
+
`plasticdb --help` prints the same table. A closed pipe (`| head`) is not an
|
|
368
|
+
error.
|
|
369
|
+
|
|
370
|
+
## Citation and licence
|
|
371
|
+
|
|
372
|
+
The code is MIT-licensed. **The PlasticDB data is licensed
|
|
373
|
+
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)**: cite the dataset
|
|
374
|
+
release you used, plus the PlasticDB paper:
|
|
375
|
+
|
|
376
|
+
> Gambarini V, Pantos O, Kingsbury JM, Weaver L, Handley KM, Lear G (2022).
|
|
377
|
+
> PlasticDB: a database of microorganisms and proteins linked to plastic
|
|
378
|
+
> biodegradation. *Database*, 2022:baac008. https://doi.org/10.1093/database/baac008
|
|
379
|
+
|
|
380
|
+
`client.cite()` returns both, including the release version and DOI.
|
|
381
|
+
|
|
382
|
+
## Development
|
|
383
|
+
|
|
384
|
+
```bash
|
|
385
|
+
uv venv .venv && uv pip install -e . --group dev
|
|
386
|
+
.venv/bin/pytest
|
|
387
|
+
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy
|
|
388
|
+
make contract-refresh # re-vendor the SDK contract from the live server
|
|
389
|
+
make docs # build the documentation site (needs requirements-docs.txt)
|
|
390
|
+
```
|