variantgrid-api 1.3.0__tar.gz → 1.3.1__tar.gz

{variantgrid_api-1.3.0/src/variantgrid_api.egg-info → variantgrid_api-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.0
+Version: 1.3.1
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -81,28 +81,10 @@ path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results
 print(f"Annotated VCF written to {path}")
 ```
 
-Or drive each step yourself:
-
-```python
-# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
-upload = api.upload_file("input.vcf", path=None)
-uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
-api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
-path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
-```
-
-`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
-`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
-these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
-stable across machines and useful if you didn't retain the id.
-
-Notes:
-
-- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
-  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
-  ignored on non-SeqAuto deployments).
-- Downloads require the target deployment to have the cohort export analysis templates configured
-  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
+There's also a `vg_api annotate_vcf` command line tool (first call uploads, run it again to download once
+ready), a step-by-step form (`upload_file` → `wait_for_annotation` → `download_annotated`), and a "submit now,
+download later" pattern for long-running jobs. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki.
 
 ## Testing
 

{variantgrid_api-1.3.0 → variantgrid_api-1.3.1}/README.md

@@ -38,28 +38,10 @@ path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results
 print(f"Annotated VCF written to {path}")
 ```
 
-Or drive each step yourself:
-
-```python
-# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
-upload = api.upload_file("input.vcf", path=None)
-uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
-api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
-path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
-```
-
-`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
-`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
-these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
-stable across machines and useful if you didn't retain the id.
-
-Notes:
-
-- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
-  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
-  ignored on non-SeqAuto deployments).
-- Downloads require the target deployment to have the cohort export analysis templates configured
-  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
+There's also a `vg_api annotate_vcf` command line tool (first call uploads, run it again to download once
+ready), a step-by-step form (`upload_file` → `wait_for_annotation` → `download_annotated`), and a "submit now,
+download later" pattern for long-running jobs. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki.
 
 ## Testing
 

{variantgrid_api-1.3.0 → variantgrid_api-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "variantgrid_api"
-version = "1.3.0"
+version = "1.3.1"
 description = "A Python API client for VariantGrid"
 authors = [
     { name = "Dave Lawrence", email = "davmlaw@gmail.com" }
@@ -23,6 +23,9 @@ dependencies = [
     "dataclasses-json",
 ]
 
+[project.scripts]
+vg_api = "variantgrid_api.cli:main"
+
 [project.optional-dependencies]
 test = ["pytest>=8", "pytest-cov>=5", "responses"]
 

variantgrid_api-1.3.1/src/variantgrid_api/cli.py

@@ -0,0 +1,137 @@
+"""Command line interface for the VariantGrid API client.
+
+Currently provides `vg_api annotate_vcf <file>`: a stateless upload/download helper. Because the server
+dedups uploads on the file's SHA-256, the VCF file itself is the receipt - the first call uploads it, and
+running the same command again downloads the annotated result (or reports that it isn't ready yet). No local
+state (upload ids, pending.json, ...) is kept, so you can poll from any machine that has the VCF.
+"""
+import argparse
+import hashlib
+import logging
+import os
+import sys
+
+import requests
+
+from variantgrid_api.api_client import VariantGridAPI, AnnotationError
+
+DEFAULT_SERVER = "https://variantgrid.com"
+
+EXIT_OK = 0        # annotated file downloaded
+EXIT_ERROR = 1     # bad input / auth / server or annotation error
+EXIT_PENDING = 3   # uploaded just now, or still annotating - come back later
+
+
+def _sha256(path):
+    """Content hash the server dedups on - identical to `sha256sum <file>`."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _build_api(args):
+    token = args.token or os.environ.get("VARIANTGRID_API_TOKEN")
+    if not token:
+        raise SystemExit("No API token - pass --token or set VARIANTGRID_API_TOKEN")
+    server = args.server or os.environ.get("VARIANTGRID_API_SERVER") or DEFAULT_SERVER
+    # Own logger so we can silence the expected 404 when a file hasn't been uploaded yet.
+    logger = logging.getLogger("vg_api.cli")
+    return VariantGridAPI(server=server, api_token=token, logger=logger), logger
+
+
+def _is_not_found(exc):
+    resp = getattr(exc, "response", None)
+    return resp is not None and resp.status_code == 404
+
+
+def annotate_vcf_cmd(args):
+    if not os.path.isfile(args.vcf):
+        print(f"No such file: {args.vcf}", file=sys.stderr)
+        return EXIT_ERROR
+
+    api, logger = _build_api(args)
+    name = os.path.basename(args.vcf)
+
+    if args.wait:
+        # Blocking one-shot: upload, wait (can take hours), download.
+        path = api.annotate_vcf(args.vcf, export_type=args.export_type, dest_path=args.dest,
+                                poll_interval=args.poll_interval)
+        print(f"Annotated {args.export_type} written to {path}")
+        return EXIT_OK
+
+    sha256 = _sha256(args.vcf)
+
+    # Probe by content hash. A 404 means we've never uploaded this file - so upload it now.
+    prev_level = logger.level
+    logger.setLevel(logging.CRITICAL)  # the probe 404 is expected; don't scare the user
+    try:
+        status = api.poll_upload_status(sha256=sha256)
+    except requests.HTTPError as e:
+        if _is_not_found(e):
+            up = api.upload_file(args.vcf, path=None)
+            print(f"Uploaded {name} (id={up['uploaded_file_id']}). "
+                  f"Annotating - run the same command again later to download.")
+            return EXIT_PENDING
+        raise
+    finally:
+        logger.setLevel(prev_level)
+
+    if err := status.get("error"):
+        print(f"{name}: annotation error - {err}", file=sys.stderr)
+        return EXIT_ERROR
+    if status.get("annotation_complete"):
+        path = api.download_annotated(sha256=sha256, export_type=args.export_type, dest_path=args.dest)
+        print(f"Annotated {args.export_type} written to {path}")
+        return EXIT_OK
+
+    progress = status.get("progress_percent")
+    suffix = f" (progress {progress}%)" if progress is not None else ""
+    print(f"{name}: not ready yet{suffix} - run the same command again later.")
+    return EXIT_PENDING
+
+
+def build_parser():
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--server",
+                        help="VariantGrid server URL (default: $VARIANTGRID_API_SERVER or "
+                             f"{DEFAULT_SERVER})")
+    common.add_argument("--token", help="API token (default: $VARIANTGRID_API_TOKEN)")
+
+    parser = argparse.ArgumentParser(prog="vg_api", description="VariantGrid API command line tool")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("annotate_vcf", parents=[common],
+                       help="Upload a VCF for annotation; run again to download it once ready",
+                       description="Upload a VCF for annotation. Because uploads are keyed on the file's "
+                                   "SHA-256, running the same command again downloads the annotated result "
+                                   "when ready, or reports that it isn't ready yet - no local state is kept.")
+    p.add_argument("vcf", help="Path to the VCF (.vcf / .vcf.gz) to annotate")
+    p.add_argument("--export-type", choices=("vcf", "csv"), default="vcf",
+                   help="Download format (default: vcf)")
+    p.add_argument("-o", "--dest", default=".",
+                   help="Destination directory or file for the download (default: current directory)")
+    p.add_argument("--wait", action="store_true",
+                   help="Block until annotation finishes, then download (can take hours)")
+    p.add_argument("--poll-interval", type=float, default=10,
+                   help="Seconds between status polls when using --wait (default: 10)")
+    p.set_defaults(func=annotate_vcf_cmd)
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except AnnotationError as e:
+        print(f"Annotation error: {e}", file=sys.stderr)
+        return EXIT_ERROR
+    except requests.HTTPError as e:
+        print(f"HTTP error: {e}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{variantgrid_api-1.3.0 → variantgrid_api-1.3.1/src/variantgrid_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.0
+Version: 1.3.1
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -81,28 +81,10 @@ path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results
 print(f"Annotated VCF written to {path}")
 ```
 
-Or drive each step yourself:
-
-```python
-# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
-upload = api.upload_file("input.vcf", path=None)
-uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
-api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
-path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
-```
-
-`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
-`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
-these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
-stable across machines and useful if you didn't retain the id.
-
-Notes:
-
-- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
-  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
-  ignored on non-SeqAuto deployments).
-- Downloads require the target deployment to have the cohort export analysis templates configured
-  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
+There's also a `vg_api annotate_vcf` command line tool (first call uploads, run it again to download once
+ready), a step-by-step form (`upload_file` → `wait_for_annotation` → `download_annotated`), and a "submit now,
+download later" pattern for long-running jobs. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki.
 
 ## Testing
 

{variantgrid_api-1.3.0 → variantgrid_api-1.3.1}/src/variantgrid_api.egg-info/SOURCES.txt

@@ -2,17 +2,20 @@ LICENSE
 README.md
 pyproject.toml
 src/variantgrid_api/api_client.py
+src/variantgrid_api/cli.py
 src/variantgrid_api/data_models.py
 src/variantgrid_api/mock_variantgrid_api.py
 src/variantgrid_api.egg-info/PKG-INFO
 src/variantgrid_api.egg-info/SOURCES.txt
 src/variantgrid_api.egg-info/dependency_links.txt
+src/variantgrid_api.egg-info/entry_points.txt
 src/variantgrid_api.egg-info/requires.txt
 src/variantgrid_api.egg-info/top_level.txt
 tests/test_api_client.py
 tests/test_api_client_annotation.py
 tests/test_api_client_bulk.py
 tests/test_api_client_validation.py
+tests/test_cli.py
 tests/test_data_models.py
 tests/test_mock_variantgrid_api.py
 tests/test_sequencer_model_from_name.py

variantgrid_api-1.3.1/src/variantgrid_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vg_api = variantgrid_api.cli:main

variantgrid_api-1.3.1/tests/test_cli.py

@@ -0,0 +1,98 @@
+import re
+
+import pytest
+import responses
+
+from variantgrid_api import cli
+
+SERVER = "https://vg.example.org"
+
+STATUS_RE = re.compile(rf"{SERVER}/upload/api/v1/upload_status/sha256/[0-9a-f]+$")
+UPLOAD_URL = f"{SERVER}/upload/api/v1/file_upload"
+DOWNLOAD_RE = re.compile(rf"{SERVER}/upload/api/v1/download/sha256/[0-9a-f]+/(vcf|csv)$")
+
+
+@pytest.fixture
+def vcf(tmp_path):
+    p = tmp_path / "input.vcf"
+    p.write_text("##fileformat=VCFv4.2\n")
+    return str(p)
+
+
+def _argv(vcf, *extra):
+    return ["annotate_vcf", vcf, "--server", SERVER, "--token", "T", *extra]
+
+
+@responses.activate
+def test_first_call_uploads(vcf):
+    """Unknown file (status 404) -> upload it and report pending."""
+    responses.add(responses.GET, STATUS_RE, json={"detail": "not found"}, status=404)
+    responses.add(responses.POST, UPLOAD_URL, json={"uploaded_file_id": 42}, status=200)
+
+    rc = cli.main(_argv(vcf))
+
+    assert rc == cli.EXIT_PENDING
+    assert any(c.request.method == "POST" and c.request.url.startswith(UPLOAD_URL)
+               for c in responses.calls)
+    # Ad-hoc upload must omit the SeqAuto path hint
+    upload_call = next(c for c in responses.calls if c.request.url.startswith(UPLOAD_URL))
+    assert "path=" not in upload_call.request.url
+
+
+@responses.activate
+def test_second_call_downloads_when_ready(vcf, tmp_path):
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"vcfdata", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.vcf.gz"'})
+
+    rc = cli.main(_argv(vcf, "-o", str(tmp_path)))
+
+    assert rc == cli.EXIT_OK
+    assert (tmp_path / "out.vcf.gz").read_bytes() == b"vcfdata"
+    # It must NOT re-upload when the file is already known
+    assert not any(c.request.method == "POST" for c in responses.calls)
+
+
+@responses.activate
+def test_not_ready_reports_pending(vcf):
+    responses.add(responses.GET, STATUS_RE,
+                  json={"annotation_complete": False, "error": None, "progress_percent": 40}, status=200)
+
+    rc = cli.main(_argv(vcf))
+
+    assert rc == cli.EXIT_PENDING
+    assert not any(re.match(DOWNLOAD_RE, c.request.url) for c in responses.calls)
+
+
+@responses.activate
+def test_server_error_status_is_error(vcf):
+    responses.add(responses.GET, STATUS_RE,
+                  json={"annotation_complete": False, "error": "Pipeline failed"}, status=200)
+
+    rc = cli.main(_argv(vcf))
+    assert rc == cli.EXIT_ERROR
+
+
+@responses.activate
+def test_csv_export_type(vcf, tmp_path):
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"zip", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.csv.zip"'})
+
+    rc = cli.main(_argv(vcf, "--export-type", "csv", "-o", str(tmp_path)))
+
+    assert rc == cli.EXIT_OK
+    assert (tmp_path / "out.csv.zip").read_bytes() == b"zip"
+    download_call = next(c for c in responses.calls if re.match(DOWNLOAD_RE, c.request.url))
+    assert download_call.request.url.endswith("/csv")
+
+
+def test_missing_file_is_error(tmp_path):
+    rc = cli.main(_argv(str(tmp_path / "nope.vcf")))
+    assert rc == cli.EXIT_ERROR
+
+
+def test_missing_token_raises(vcf, monkeypatch):
+    monkeypatch.delenv("VARIANTGRID_API_TOKEN", raising=False)
+    with pytest.raises(SystemExit):
+        cli.main(["annotate_vcf", vcf, "--server", SERVER])