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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.1
+Version: 1.3.2
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -68,23 +68,25 @@ result = api.create_enrichment_kit(enrichment_kit)
 
 ## Annotate a VCF and download it back
 
-Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the
-cohort-level annotated export (all samples, single-sample VCFs included). The whole flow is a one-liner:
+Upload a VCF, have VariantGrid import + annotate any novel variants, then download the cohort-level annotated
+export (all samples, single-sample VCFs included). Annotation can take a while, so the quickest way in is the
+`vg_api` command line tool: the first call uploads, and running the same command again downloads the result
+once it's ready.
 
-```python
-from variantgrid_api.api_client import VariantGridAPI
-
-api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+```console
+$ export VARIANTGRID_API_TOKEN=YOUR_API_TOKEN
+$ vg_api annotate_vcf input.vcf.gz -o results/
+Uploaded input.vcf.gz (id=13256).
+Annotating input.vcf.gz - run the same command again later to download.
 
-# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
-path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
-print(f"Annotated VCF written to {path}")
+$ vg_api annotate_vcf input.vcf.gz -o results/        # once it's done
+Annotated vcf written to results/input.vcf_annotated_v254_GRCh38.vcf.gz
 ```
 
-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.
+From Python it's `upload_file()` / `poll_upload_status()` / `download_annotated()`, or the blocking
+`annotate_vcf()` one-liner. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki for batches, the
+submit-now/download-later pattern, and all the options.
 
 ## Testing
 

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

@@ -25,23 +25,25 @@ result = api.create_enrichment_kit(enrichment_kit)
 
 ## Annotate a VCF and download it back
 
-Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the
-cohort-level annotated export (all samples, single-sample VCFs included). The whole flow is a one-liner:
-
-```python
-from variantgrid_api.api_client import VariantGridAPI
-
-api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
-
-# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
-path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
-print(f"Annotated VCF written to {path}")
+Upload a VCF, have VariantGrid import + annotate any novel variants, then download the cohort-level annotated
+export (all samples, single-sample VCFs included). Annotation can take a while, so the quickest way in is the
+`vg_api` command line tool: the first call uploads, and running the same command again downloads the result
+once it's ready.
+
+```console
+$ export VARIANTGRID_API_TOKEN=YOUR_API_TOKEN
+$ vg_api annotate_vcf input.vcf.gz -o results/
+Uploaded input.vcf.gz (id=13256).
+Annotating input.vcf.gz - run the same command again later to download.
+
+$ vg_api annotate_vcf input.vcf.gz -o results/        # once it's done
+Annotated vcf written to results/input.vcf_annotated_v254_GRCh38.vcf.gz
 ```
 
-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.
+From Python it's `upload_file()` / `poll_upload_status()` / `download_annotated()`, or the blocking
+`annotate_vcf()` one-liner. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki for batches, the
+submit-now/download-later pattern, and all the options.
 
 ## Testing
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "variantgrid_api"
-version = "1.3.1"
+version = "1.3.2"
 description = "A Python API client for VariantGrid"
 authors = [
     { name = "Dave Lawrence", email = "davmlaw@gmail.com" }

{variantgrid_api-1.3.1 → variantgrid_api-1.3.2}/src/variantgrid_api/cli.py

@@ -46,6 +46,27 @@ def _is_not_found(exc):
     return resp is not None and resp.status_code == 404
 
 
+def _probe_status(api, logger, sha256):
+    """Poll status by content hash. Returns the status dict, or None if the server has never
+    seen this file (404) - a 404 here just means "not uploaded yet", so we silence its logging."""
+    prev_level = logger.level
+    logger.setLevel(logging.CRITICAL)
+    try:
+        return api.poll_upload_status(sha256=sha256)
+    except requests.HTTPError as e:
+        if _is_not_found(e):
+            return None
+        raise
+    finally:
+        logger.setLevel(prev_level)
+
+
+def _download(api, args, sha256):
+    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
+
+
 def annotate_vcf_cmd(args):
     if not os.path.isfile(args.vcf):
         print(f"No such file: {args.vcf}", file=sys.stderr)
@@ -53,38 +74,30 @@ def annotate_vcf_cmd(args):
 
     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)
+    status = _probe_status(api, logger, sha256)
+    if status is None:
+        # We've never uploaded this file - do it now.
+        up = api.upload_file(args.vcf, path=None)
+        print(f"Uploaded {name} (id={up['uploaded_file_id']}).")
 
+    if args.wait:
+        # Poll the server ourselves until annotation finishes (can take hours), then download.
+        if status is None or not status.get("annotation_complete"):
+            print("Waiting for annotation to finish - this can take a while...")
+            api.wait_for_annotation(sha256=sha256, timeout=args.timeout, poll_interval=args.poll_interval)
+        return _download(api, args, sha256)
+
+    # Single-shot: report where it's at, download only if it's ready.
+    if status is None:
+        print(f"Annotating {name} - run the same command again later to download.")
+        return EXIT_PENDING
     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
+        return _download(api, args, sha256)
 
     progress = status.get("progress_percent")
     suffix = f" (progress {progress}%)" if progress is not None else ""
@@ -113,9 +126,12 @@ def build_parser():
     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)")
+                   help="Poll until annotation finishes and download it, instead of returning immediately "
+                        "(can take hours)")
     p.add_argument("--poll-interval", type=float, default=10,
                    help="Seconds between status polls when using --wait (default: 10)")
+    p.add_argument("--timeout", type=float, default=86400,
+                   help="Give up after this many seconds when using --wait (default: 86400 = 24h)")
     p.set_defaults(func=annotate_vcf_cmd)
     return parser
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.1
+Version: 1.3.2
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -68,23 +68,25 @@ result = api.create_enrichment_kit(enrichment_kit)
 
 ## Annotate a VCF and download it back
 
-Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the
-cohort-level annotated export (all samples, single-sample VCFs included). The whole flow is a one-liner:
+Upload a VCF, have VariantGrid import + annotate any novel variants, then download the cohort-level annotated
+export (all samples, single-sample VCFs included). Annotation can take a while, so the quickest way in is the
+`vg_api` command line tool: the first call uploads, and running the same command again downloads the result
+once it's ready.
 
-```python
-from variantgrid_api.api_client import VariantGridAPI
-
-api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+```console
+$ export VARIANTGRID_API_TOKEN=YOUR_API_TOKEN
+$ vg_api annotate_vcf input.vcf.gz -o results/
+Uploaded input.vcf.gz (id=13256).
+Annotating input.vcf.gz - run the same command again later to download.
 
-# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
-path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
-print(f"Annotated VCF written to {path}")
+$ vg_api annotate_vcf input.vcf.gz -o results/        # once it's done
+Annotated vcf written to results/input.vcf_annotated_v254_GRCh38.vcf.gz
 ```
 
-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.
+From Python it's `upload_file()` / `poll_upload_status()` / `download_annotated()`, or the blocking
+`annotate_vcf()` one-liner. See
+**[Annotate a VCF](https://github.com/SACGF/variantgrid_api/wiki/Annotate-a-VCF)** on the wiki for batches, the
+submit-now/download-later pattern, and all the options.
 
 ## Testing
 

{variantgrid_api-1.3.1 → variantgrid_api-1.3.2}/tests/test_cli.py

@@ -87,6 +87,35 @@ def test_csv_export_type(vcf, tmp_path):
     assert download_call.request.url.endswith("/csv")
 
 
+@responses.activate
+def test_wait_uploads_polls_then_downloads(vcf, tmp_path):
+    """--wait on a new file: upload, poll until complete, then download - no external loop."""
+    responses.add(responses.GET, STATUS_RE, json={"detail": "not found"}, status=404)  # probe
+    responses.add(responses.POST, UPLOAD_URL, json={"uploaded_file_id": 7}, status=200)
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": False, "error": None}, status=200)
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"data", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.vcf.gz"'})
+
+    rc = cli.main(_argv(vcf, "--wait", "-o", str(tmp_path), "--poll-interval", "0"))
+
+    assert rc == cli.EXIT_OK
+    assert (tmp_path / "out.vcf.gz").read_bytes() == b"data"
+
+
+@responses.activate
+def test_wait_downloads_without_reupload_when_already_known(vcf, tmp_path):
+    """--wait on an already-uploaded, already-complete file must not re-upload."""
+    responses.add(responses.GET, STATUS_RE, json={"annotation_complete": True, "error": None}, status=200)
+    responses.add(responses.GET, DOWNLOAD_RE, body=b"data", status=200,
+                  headers={"Content-Disposition": 'attachment; filename="out.vcf.gz"'})
+
+    rc = cli.main(_argv(vcf, "--wait", "-o", str(tmp_path), "--poll-interval", "0"))
+
+    assert rc == cli.EXIT_OK
+    assert not any(c.request.method == "POST" for c in responses.calls)
+
+
 def test_missing_file_is_error(tmp_path):
     rc = cli.main(_argv(str(tmp_path / "nope.vcf")))
     assert rc == cli.EXIT_ERROR