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.
Files changed (118) hide show
  1. plasticdb-0.0.1/.gitignore +13 -0
  2. plasticdb-0.0.1/CHANGELOG.md +141 -0
  3. plasticdb-0.0.1/CITATION.cff +32 -0
  4. plasticdb-0.0.1/LICENSE +21 -0
  5. plasticdb-0.0.1/PKG-INFO +390 -0
  6. plasticdb-0.0.1/README.md +346 -0
  7. plasticdb-0.0.1/pyproject.toml +95 -0
  8. plasticdb-0.0.1/src/plasticdb/__init__.py +97 -0
  9. plasticdb-0.0.1/src/plasticdb/__main__.py +5 -0
  10. plasticdb-0.0.1/src/plasticdb/_cache.py +176 -0
  11. plasticdb-0.0.1/src/plasticdb/_client.py +642 -0
  12. plasticdb-0.0.1/src/plasticdb/_download.py +195 -0
  13. plasticdb-0.0.1/src/plasticdb/_endpoints.py +67 -0
  14. plasticdb-0.0.1/src/plasticdb/_fasta.py +53 -0
  15. plasticdb-0.0.1/src/plasticdb/_inputs.py +229 -0
  16. plasticdb-0.0.1/src/plasticdb/_pagination.py +437 -0
  17. plasticdb-0.0.1/src/plasticdb/_response.py +244 -0
  18. plasticdb-0.0.1/src/plasticdb/_version.py +1 -0
  19. plasticdb-0.0.1/src/plasticdb/cli/__init__.py +40 -0
  20. plasticdb-0.0.1/src/plasticdb/cli/_app.py +1330 -0
  21. plasticdb-0.0.1/src/plasticdb/cli/_config.py +113 -0
  22. plasticdb-0.0.1/src/plasticdb/cli/_core.py +686 -0
  23. plasticdb-0.0.1/src/plasticdb/cli/_output.py +250 -0
  24. plasticdb-0.0.1/src/plasticdb/errors.py +335 -0
  25. plasticdb-0.0.1/src/plasticdb/models/__init__.py +151 -0
  26. plasticdb-0.0.1/src/plasticdb/models/_base.py +51 -0
  27. plasticdb-0.0.1/src/plasticdb/models/catalogue.py +405 -0
  28. plasticdb-0.0.1/src/plasticdb/models/common.py +302 -0
  29. plasticdb-0.0.1/src/plasticdb/models/jobs.py +339 -0
  30. plasticdb-0.0.1/src/plasticdb/models/other.py +292 -0
  31. plasticdb-0.0.1/src/plasticdb/models/releases.py +84 -0
  32. plasticdb-0.0.1/src/plasticdb/py.typed +0 -0
  33. plasticdb-0.0.1/src/plasticdb/resources/__init__.py +25 -0
  34. plasticdb-0.0.1/src/plasticdb/resources/_base.py +13 -0
  35. plasticdb-0.0.1/src/plasticdb/resources/_filters.py +227 -0
  36. plasticdb-0.0.1/src/plasticdb/resources/catalogue.py +277 -0
  37. plasticdb-0.0.1/src/plasticdb/resources/downloads.py +251 -0
  38. plasticdb-0.0.1/src/plasticdb/resources/evidence.py +272 -0
  39. plasticdb-0.0.1/src/plasticdb/resources/jobs.py +932 -0
  40. plasticdb-0.0.1/src/plasticdb/resources/proteins.py +318 -0
  41. plasticdb-0.0.1/src/plasticdb/resources/releases.py +51 -0
  42. plasticdb-0.0.1/tests/__init__.py +0 -0
  43. plasticdb-0.0.1/tests/conftest.py +68 -0
  44. plasticdb-0.0.1/tests/contract/sdk-v1.json +35156 -0
  45. plasticdb-0.0.1/tests/fixtures/autocomplete.json +35 -0
  46. plasticdb-0.0.1/tests/fixtures/bad_param.json +23 -0
  47. plasticdb-0.0.1/tests/fixtures/binding_assays.json +13 -0
  48. plasticdb-0.0.1/tests/fixtures/changes.json +39 -0
  49. plasticdb-0.0.1/tests/fixtures/constructs.json +89 -0
  50. plasticdb-0.0.1/tests/fixtures/engineering.json +44 -0
  51. plasticdb-0.0.1/tests/fixtures/fasta_one.json +9 -0
  52. plasticdb-0.0.1/tests/fixtures/job_annotate_list.json +100 -0
  53. plasticdb-0.0.1/tests/fixtures/job_compare.json +151 -0
  54. plasticdb-0.0.1/tests/fixtures/job_compare_results.json +131 -0
  55. plasticdb-0.0.1/tests/fixtures/job_done.json +92 -0
  56. plasticdb-0.0.1/tests/fixtures/job_done_results.json +131 -0
  57. plasticdb-0.0.1/tests/fixtures/job_error.json +64 -0
  58. plasticdb-0.0.1/tests/fixtures/job_hmm.json +98 -0
  59. plasticdb-0.0.1/tests/fixtures/job_hmm_results.json +32 -0
  60. plasticdb-0.0.1/tests/fixtures/job_pathway.json +154 -0
  61. plasticdb-0.0.1/tests/fixtures/job_release_unsupported.json +21 -0
  62. plasticdb-0.0.1/tests/fixtures/job_running.json +64 -0
  63. plasticdb-0.0.1/tests/fixtures/job_submitted.json +62 -0
  64. plasticdb-0.0.1/tests/fixtures/jobs_list.json +147 -0
  65. plasticdb-0.0.1/tests/fixtures/microorganism.json +354 -0
  66. plasticdb-0.0.1/tests/fixtures/microorganisms.json +161 -0
  67. plasticdb-0.0.1/tests/fixtures/not_found.json +10 -0
  68. plasticdb-0.0.1/tests/fixtures/paper.json +41 -0
  69. plasticdb-0.0.1/tests/fixtures/papers.json +36 -0
  70. plasticdb-0.0.1/tests/fixtures/pathway.json +88 -0
  71. plasticdb-0.0.1/tests/fixtures/pathway_graph.json +67 -0
  72. plasticdb-0.0.1/tests/fixtures/pathways.json +19 -0
  73. plasticdb-0.0.1/tests/fixtures/pathways_by_plastic.json +90 -0
  74. plasticdb-0.0.1/tests/fixtures/plastic.json +241 -0
  75. plasticdb-0.0.1/tests/fixtures/plastics.json +46 -0
  76. plasticdb-0.0.1/tests/fixtures/plastics_names.json +21 -0
  77. plasticdb-0.0.1/tests/fixtures/preparations.json +101 -0
  78. plasticdb-0.0.1/tests/fixtures/protein.json +1340 -0
  79. plasticdb-0.0.1/tests/fixtures/protein_interactions.json +226 -0
  80. plasticdb-0.0.1/tests/fixtures/protein_kinetics.json +148 -0
  81. plasticdb-0.0.1/tests/fixtures/protein_merged.json +15 -0
  82. plasticdb-0.0.1/tests/fixtures/protein_merged_kinetics.json +15 -0
  83. plasticdb-0.0.1/tests/fixtures/protein_properties.json +78 -0
  84. plasticdb-0.0.1/tests/fixtures/protein_variant_redirect.json +14 -0
  85. plasticdb-0.0.1/tests/fixtures/protein_variant_subresource.json +15 -0
  86. plasticdb-0.0.1/tests/fixtures/protein_variants.json +337 -0
  87. plasticdb-0.0.1/tests/fixtures/proteins.json +156 -0
  88. plasticdb-0.0.1/tests/fixtures/release_unknown.json +12 -0
  89. plasticdb-0.0.1/tests/fixtures/search.json +32 -0
  90. plasticdb-0.0.1/tests/fixtures/search_grouped.json +77 -0
  91. plasticdb-0.0.1/tests/fixtures/search_sequence.json +42 -0
  92. plasticdb-0.0.1/tests/fixtures/share_created.json +15 -0
  93. plasticdb-0.0.1/tests/fixtures/shares.json +22 -0
  94. plasticdb-0.0.1/tests/fixtures/stats.json +19 -0
  95. plasticdb-0.0.1/tests/fixtures/stats_activity.json +33 -0
  96. plasticdb-0.0.1/tests/fixtures/taxonomy.json +60 -0
  97. plasticdb-0.0.1/tests/fixtures/tree_detail.json +68 -0
  98. plasticdb-0.0.1/tests/fixtures/tree_done.json +66 -0
  99. plasticdb-0.0.1/tests/fixtures/unknown_release.json +12 -0
  100. plasticdb-0.0.1/tests/fixtures/variant.json +498 -0
  101. plasticdb-0.0.1/tests/fixtures/variant_merged.json +15 -0
  102. plasticdb-0.0.1/tests/fixtures/variant_removed.json +12 -0
  103. plasticdb-0.0.1/tests/fixtures/variants_list.json +156 -0
  104. plasticdb-0.0.1/tests/test_cache.py +99 -0
  105. plasticdb-0.0.1/tests/test_catalogue.py +470 -0
  106. plasticdb-0.0.1/tests/test_cli.py +672 -0
  107. plasticdb-0.0.1/tests/test_client.py +135 -0
  108. plasticdb-0.0.1/tests/test_collections.py +385 -0
  109. plasticdb-0.0.1/tests/test_contract.py +186 -0
  110. plasticdb-0.0.1/tests/test_downloads.py +407 -0
  111. plasticdb-0.0.1/tests/test_errors.py +255 -0
  112. plasticdb-0.0.1/tests/test_job_inputs.py +151 -0
  113. plasticdb-0.0.1/tests/test_jobs.py +987 -0
  114. plasticdb-0.0.1/tests/test_pagination.py +151 -0
  115. plasticdb-0.0.1/tests/test_pinned_data.py +216 -0
  116. plasticdb-0.0.1/tests/test_provenance.py +132 -0
  117. plasticdb-0.0.1/tests/test_releases.py +78 -0
  118. plasticdb-0.0.1/tests/test_retries.py +155 -0
@@ -0,0 +1,13 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .pytest_cache/
8
+ .mypy_cache/
9
+ .ruff_cache/
10
+ .coverage
11
+ htmlcov/
12
+ site/
13
+ .cache/
@@ -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
@@ -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.
@@ -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
+ ```