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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.1
+Version: 1.4.0
 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.4.0}/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.4.0}/pyproject.toml

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

{variantgrid_api-1.3.1 → variantgrid_api-1.4.0}/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.4.0}/src/variantgrid_api/data_models.py

@@ -132,6 +132,14 @@ class VariantCaller:
     run_params: Optional[str] = None
 
 
+@dataclass_json
+@dataclass
+class SequencingSampleLookup:
+    """ Only used as arguments to find existing sequencing sample on server - not enough details to create one """
+    sample_sheet_lookup: SampleSheetLookup = field(metadata=config(field_name="sample_sheet"))
+    sample_name: str
+
+
 @dataclass_json
 @dataclass
 class JointCalledVCF:
@@ -139,6 +147,10 @@ class JointCalledVCF:
     path: str
     sample_sheet_lookup: SampleSheetLookup = field(metadata=config(field_name="sample_sheet"))
     variant_caller: VariantCaller
+    # Set for joint calls that draw samples from more than one sequencing run, eg a family trio.
+    # sample_sheet_lookup stays the owning run - the one the path sits under.
+    sequencing_samples: Optional[List[SequencingSampleLookup]] = \
+        field(default=None, metadata=config(exclude=lambda x: x is None))
 
 
 @dataclass_json
@@ -190,14 +202,6 @@ class SequencingFile:
     vcf_file: SingleSampleVCF
 
 
-@dataclass_json
-@dataclass
-class SequencingSampleLookup:
-    """ Only used as arguments to find existing sequencing sample on server - not enough details to create one """
-    sample_sheet_lookup: SampleSheetLookup = field(metadata=config(field_name="sample_sheet"))
-    sample_name: str
-
-
 @dataclass_json
 @dataclass
 class QC:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.3.1
+Version: 1.4.0
 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.4.0}/tests/test_api_client.py

@@ -97,6 +97,26 @@ def test_create_joint_called_vcf_posts_json(api, server, vg_objects):
         url
     )
     assert body["path"].endswith(".vcf.gz")
+    # A single-run joint call leaves the key off entirely, so the server keeps its existing behaviour
+    assert "sequencing_samples" not in body
+
+
+@responses.activate
+def test_create_joint_called_vcf_posts_cross_run_members(api, server, vg_objects):
+    url = f"{server}/seqauto/api/v1/joint_called_vcf/"
+    body = assert_post(
+        lambda: api.create_joint_called_vcf(
+            vg_objects["cross_run_joint_called_vcf"]
+        ),
+        url
+    )
+    members = body["sequencing_samples"]
+    assert [m["sample_name"] for m in members] == ["fake_sample_1", "fake_sample_mum", "fake_sample_dad"]
+    # Members carry their own sample sheet, so two of them point at the run that sequenced the parents
+    runs = {m["sample_sheet"]["sequencing_run"] for m in members}
+    assert len(runs) == 2
+    # The owning sheet is still the run the path sits under
+    assert body["sample_sheet"]["sequencing_run"] == vg_objects["SEQUENCING_RUN_NAME"]
 
 
 @responses.activate

{variantgrid_api-1.3.1 → variantgrid_api-1.4.0}/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