Cover database upload and the remaining engine endpoints in pyvolca - #199
Merged
Conversation
Adds upload_database plus the staged-database lifecycle (get_setup, set_data_path, finalize_database, delete_database) and a shared _upload helper streaming an octet-stream body with the name/description query params. Upload and finalize failures are reported in-band by the engine (HTTP 200 with success=false), so both surface through _require_success.
Wires compute_sensitivity and score_activities through the OpenAPI dispatcher, which gains a body= channel so spec-declared POST operations can carry a JSON payload (until now only substitution bodies could). Also introduces the typed result classes the newly covered endpoints return: SensitivityResult (flattening the engine's success/error entries per perturbation), BatchScores, and the flow/method/mapping detail types consumed by the detail lookups added next.
…il lookups Adds method-collection management (list/load/unload/delete/upload) and the three reference-data families (flow synonyms, compartment mappings, units) behind a validated kind argument, plus the flow-synonym groups and CSV download extras, and the flow/method/mapping-status/stats detail lookups. Uploads reuse the shared _upload helper; management failures surface through _require_success.
Runs gen_api_md.py --write for the newly added client methods and exports the new result dataclasses (BatchScores, FlowDetail, MappingStatus, MethodDetail, MethodFactor, PerturbedResult, ScoredActivity, SensitivityResult, UnmappedFlow) from the package root.
A mistyped kind was only caught at runtime by _ref_kind. Declaring RefDataKind as a Literal lets pyright reject the typo at check time, with the frozenset derived from the same Literal so the two cannot drift. Runtime validation stays for untyped callers, and the alias is exported for user annotations.
_call silently dropped an explicit body when the spec declared the operation as GET or DELETE, so a caller of the public call() escape hatch could believe a payload was sent when it never left the client. Raise VoLCAError before the request instead.
Merged
ccomb
added a commit
that referenced
this pull request
Jul 13, 2026
## Why Cut the pyvolca release for the endpoint-coverage work in #199, which merged with the version bump and CHANGELOG entry deliberately deferred to release time. ## What - `pyproject.toml`: `0.7.2` → `0.8.0` - `CHANGELOG.md`: new `[0.8.0]` section — database upload + staged setup, batch scoring, sensitivity, method collections, reference data, and detail lookups. pyvolca now covers the engine's full HTTP surface. - `README.md`: regenerated compatibility sentinel (now *pyvolca 0.8.0, wire 2, engine ≥ v0.9.1*). Wire format is unchanged (still 2); `REQUIRED_WIRE` and `MIN_ENGINE_HINT` untouched. Tag `pyvolca-v0.8.0` after merge.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
pyvolca could query a running engine but could not feed one: there was no way to upload a database (
POST /api/v1/db/upload), and a wider audit found the Python client covered 25 of the engine's ~60 HTTP endpoints. This closes the gap so a notebook can upload an archive, wire its dependencies, finalize it, and then score against it — end to end, without leaving Python.What this adds
upload_database(streams an octet-stream body with the name/description query params), thenget_setup,set_data_path,finalize_database,delete_database. A shared_uploadhelper backs every upload endpoint.compute_sensitivityandscore_activities, both dispatched through the OpenAPI table (which gained abody=channel for spec-declared POST operations), returning the newSensitivityResult/BatchScorestyped results.kindargument, plus the flow-synonymgroupsand CSVdownloadextras.get_flow,get_flow_activities,get_method,get_method_factors,get_mapping_status,get_stats.Final state
Every management endpoint keeps the existing dict-return convention and surfaces the engine's in-band
{"success": false}through_require_success; analysis reads return typed dataclasses. Wire shapes were verified againstsrc/API/Types.hs. Offline tests mock the session and assert URL / query params / streamed body / typed parsing;pyrightis clean and the API-reference README block is regenerated.Notes
git-clifffrom thesefeat:commits at release time, per the CHANGELOG's own workflow note.WRAPPER_OPERATIONSvs the live OpenAPI spec) gainscompute_sensitivityandscore_activities; it runs where the engine binary is built.