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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.4.0
+Version: 1.6.0
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -88,6 +88,53 @@ From Python it's `upload_file()` / `poll_upload_status()` / `download_annotated(
 **[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.
 
+## Patients, specimens and extractions
+
+VariantGrid can record which patient, specimen and extraction a lab's sequencing came from, and specimen-level
+measures such as TMB, MSI and GIS. This needs a server at or after SACGF/variantgrid#1716.
+
+```
+from variantgrid_api.data_models import Patient, Specimen, Extraction, ExternalReference, NucleicAcid
+
+api.create_patient(Patient(patient_code="C0000001"))
+api.create_specimen(Specimen(patient="C0000001", reference_id="2600000001"))
+api.create_extraction(Extraction(specimen="2600000001", reference_id="2600000001C",
+                                 nucleic_acid_source=NucleicAcid.DNA))
+api.upload_file("sample.vcf.gz", path=None,
+                metadata={"extraction": "2600000001C", "genome_build": "GRCh37"})
+```
+
+A bare string names a record by its local reference. Use `ExternalReference(code=..., external_type=...)` to
+name it by a LIMS identifier instead. See `examples/example_tso500.py` for a full run.
+
+## Talking to more than one VariantGrid version
+
+Servers of different ages accept different calls. The client asks the server which features it has
+(`GET api/v1/capabilities`, fetched once on first use), and each call that needs a newer server
+checks that list first: the patient / specimen / extraction calls, specimen measures,
+`link_sequencing_sample_extraction`, the annotate flow (`poll_upload_status`, `wait_for_annotation`,
+`download_annotated`, `annotate_vcf`), and `upload_file` with `metadata` or `file_type`. A server without the
+capabilities endpoint counts as legacy and reports no features.
+
+By default an unsupported call raises `UnsupportedFeatureError`. To run the same code against old and new
+servers, skip those calls instead: they log a warning and return `None`. `upload_file` is the exception: on a
+server without upload metadata it drops the `metadata` and still uploads the file.
+
+```
+from variantgrid_api.api_client import VariantGridAPI, UnsupportedFeaturePolicy
+
+api = VariantGridAPI(server, api_token, unsupported_feature_policy=UnsupportedFeaturePolicy.SKIP)
+api.create_patient(patient)        # skipped on a server without patients
+
+# Uploads only when the server has an importer for this file type
+api.upload_file("sample_CombinedVariantOutput.tsv", path=None,
+                file_type="dragen_tso500_combined_variant_output")
+```
+
+Where the fallback isn't simply "do nothing", branch on `api.supports("feature")` or
+`api.accepts_upload("file_type")`. `api.capabilities.version` is useful for logging which server you reached.
+For tests, `MockVariantGridAPI(capabilities=ServerCapabilities.LEGACY)` behaves like an old server.
+
 ## Testing
 
 ```

variantgrid_api-1.6.0/README.md

@@ -0,0 +1,101 @@
+# variantgrid_api
+
+[![PyPi version](https://img.shields.io/pypi/v/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/) [![Python versions](https://img.shields.io/pypi/pyversions/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/)
+
+Python API client for [VariantGrid](https://github.com/SACGF/variantgrid) Open source Variant database and analysis platform
+
+See [changelog](https://github.com/SACGF/variantgrid_api/blob/main/CHANGELOG.md)
+
+## Install
+
+```
+python3 -m pip install variantgrid_api
+```
+
+## Example
+
+```
+from variantgrid_api.api_client import VariantGridAPI
+from variantgrid_api.data_models import EnrichmentKit
+
+api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+enrichment_kit = EnrichmentKit(name="idt_haem", version=1)
+result = api.create_enrichment_kit(enrichment_kit)
+```
+
+## Annotate a VCF and download it back
+
+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
+```
+
+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.
+
+## Patients, specimens and extractions
+
+VariantGrid can record which patient, specimen and extraction a lab's sequencing came from, and specimen-level
+measures such as TMB, MSI and GIS. This needs a server at or after SACGF/variantgrid#1716.
+
+```
+from variantgrid_api.data_models import Patient, Specimen, Extraction, ExternalReference, NucleicAcid
+
+api.create_patient(Patient(patient_code="C0000001"))
+api.create_specimen(Specimen(patient="C0000001", reference_id="2600000001"))
+api.create_extraction(Extraction(specimen="2600000001", reference_id="2600000001C",
+                                 nucleic_acid_source=NucleicAcid.DNA))
+api.upload_file("sample.vcf.gz", path=None,
+                metadata={"extraction": "2600000001C", "genome_build": "GRCh37"})
+```
+
+A bare string names a record by its local reference. Use `ExternalReference(code=..., external_type=...)` to
+name it by a LIMS identifier instead. See `examples/example_tso500.py` for a full run.
+
+## Talking to more than one VariantGrid version
+
+Servers of different ages accept different calls. The client asks the server which features it has
+(`GET api/v1/capabilities`, fetched once on first use), and each call that needs a newer server
+checks that list first: the patient / specimen / extraction calls, specimen measures,
+`link_sequencing_sample_extraction`, the annotate flow (`poll_upload_status`, `wait_for_annotation`,
+`download_annotated`, `annotate_vcf`), and `upload_file` with `metadata` or `file_type`. A server without the
+capabilities endpoint counts as legacy and reports no features.
+
+By default an unsupported call raises `UnsupportedFeatureError`. To run the same code against old and new
+servers, skip those calls instead: they log a warning and return `None`. `upload_file` is the exception: on a
+server without upload metadata it drops the `metadata` and still uploads the file.
+
+```
+from variantgrid_api.api_client import VariantGridAPI, UnsupportedFeaturePolicy
+
+api = VariantGridAPI(server, api_token, unsupported_feature_policy=UnsupportedFeaturePolicy.SKIP)
+api.create_patient(patient)        # skipped on a server without patients
+
+# Uploads only when the server has an importer for this file type
+api.upload_file("sample_CombinedVariantOutput.tsv", path=None,
+                file_type="dragen_tso500_combined_variant_output")
+```
+
+Where the fallback isn't simply "do nothing", branch on `api.supports("feature")` or
+`api.accepts_upload("file_type")`. `api.capabilities.version` is useful for logging which server you reached.
+For tests, `MockVariantGridAPI(capabilities=ServerCapabilities.LEGACY)` behaves like an old server.
+
+## Testing
+
+```
+# Install required testing packages
+python3 -m pip install -e ".[test]"
+python3 -m pytest --cov=variantgrid_api
+```

{variantgrid_api-1.4.0 → variantgrid_api-1.6.0}/pyproject.toml

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

{variantgrid_api-1.4.0 → variantgrid_api-1.6.0}/src/variantgrid_api/api_client.py

@@ -12,7 +12,9 @@ from typing import List, Optional, Callable, Union
 import requests
 
 from variantgrid_api.data_models import EnrichmentKit, SequencingRun, SampleSheet, JointCalledVCF, \
-    SampleSheetLookup, SequencingFile, QCGeneList, QCExecStats, QCGeneCoverage, SequencerModel, Sequencer
+    SampleSheetLookup, SequencingFile, QCGeneList, QCExecStats, QCGeneCoverage, SequencerModel, Sequencer, \
+    SequencingSampleLookup, Patient, Specimen, Extraction, SpecimenMeasure, ExternalReference, ReferenceLike, \
+    reference_json, ServerCapabilities, ServerFeature, UploadFileType
 
 
 _UNSET = object()
@@ -31,6 +33,20 @@ class EmptyInputPolicy(Enum):
     ERROR = "error"
 
 
+class UnsupportedFeaturePolicy(Enum):
+    """ What a gated call does when the server lacks the feature (see VariantGridAPI.capabilities) """
+    SKIP = "skip"     # log a warning, return None
+    ERROR = "error"   # raise UnsupportedFeatureError
+
+
+class UnsupportedFeatureError(Exception):
+    """ Raised (under UnsupportedFeaturePolicy.ERROR) when a call needs a feature the server doesn't have """
+
+    def __init__(self, message, capabilities: Optional[ServerCapabilities] = None):
+        super().__init__(message)
+        self.capabilities = capabilities
+
+
 class AnnotationError(Exception):
     """Raised when the server reports an error while importing/annotating an uploaded file."""
 
@@ -43,7 +59,8 @@ class VariantGridAPI:
     def __init__(self, server, api_token,
                  empty_input_policy=EmptyInputPolicy.ERROR,
                  logger: Optional[logging.Logger] = None,
-                 log_request=False, log_response=False
+                 log_request=False, log_response=False,
+                 unsupported_feature_policy=UnsupportedFeaturePolicy.ERROR
     ):
         self.server = server
         self.headers = {"Authorization": f"Token {api_token}"}
@@ -53,6 +70,8 @@ class VariantGridAPI:
         self.validation_handler = self._get_validation_handler(empty_input_policy, logger)
         self.log_request = log_request
         self.log_response = log_response
+        self.unsupported_feature_policy = unsupported_feature_policy
+        self._capabilities: Optional[ServerCapabilities] = None
 
     def _get_url(self, url):
         return urllib.parse.urljoin(self.server, url)
@@ -110,10 +129,61 @@ class VariantGridAPI:
         if obj is None:
             self.validation_handler(f"{info}: is None")
 
+    def _validate_reference(self, info: str, reference: Optional[ReferenceLike]):
+        if isinstance(reference, str):
+            self._validate_string(info, reference)
+        else:
+            self._validate_object(info, reference)
+
     def _validate_list(self, info: str, list_obj: List):
         if not list_obj:
             self.validation_handler(f"{info}: empty list")
 
+    ##########################################################
+    ## Server capabilities (SACGF/variantgrid_sapath#443)
+    ## One client talks to servers of different ages. Calls needing a newer server are gated on the
+    ## features it reports, and handled by unsupported_feature_policy when it lacks them
+
+    @property
+    def capabilities(self) -> ServerCapabilities:
+        """ Fetched on first use then cached, so constructing the client and ungated calls do no extra
+            request. A server without the endpoint is ServerCapabilities.LEGACY - it answers 404, or a redirect
+            to its login page when its login middleware doesn't exempt /api/ (so redirects aren't followed) """
+        if self._capabilities is None:
+            url = self._get_url("api/v1/capabilities")
+            response = requests.get(url, headers=self.headers, allow_redirects=False)
+            if response.status_code == 404 or response.is_redirect:
+                self.logger.info("Server has no capabilities endpoint (HTTP %s) - treating as legacy",
+                                 response.status_code)
+                self._capabilities = ServerCapabilities.LEGACY
+            else:
+                data = self._handle_json_response(response, f"{url=}")
+                self._capabilities = ServerCapabilities.from_json(data)
+        return self._capabilities
+
+    def supports(self, feature: Union[ServerFeature, str]) -> bool:
+        return feature in self.capabilities.features
+
+    def accepts_upload(self, file_type: Union[UploadFileType, str]) -> bool:
+        """ file_type is an UploadFileType, or the server's UploadedFileTypes name in lower case """
+        return file_type in self.capabilities.upload_file_types
+
+    def _unsupported(self, message: str) -> bool:
+        """ Applies unsupported_feature_policy - returns False (caller skips) or raises """
+        capabilities = self.capabilities
+        message = f"{message} (server version '{capabilities.version}')"
+        if self.unsupported_feature_policy == UnsupportedFeaturePolicy.SKIP:
+            self.logger.warning("Skipping: %s", message)
+            return False
+        raise UnsupportedFeatureError(message, capabilities)
+
+    def _require(self, feature: Union[ServerFeature, str]) -> bool:
+        """ True if the server supports feature, otherwise applies unsupported_feature_policy """
+        return self.supports(feature) or self._unsupported(f"server doesn't support feature '{feature}'")
+
+    def _require_upload(self, file_type: Union[UploadFileType, str]) -> bool:
+        return self.accepts_upload(file_type) or self._unsupported(f"server doesn't accept upload file type '{file_type}'")
+
     def create_experiment(self, experiment: str):
         self._validate_string("experiment", experiment)
         json_data = {
@@ -171,14 +241,21 @@ class VariantGridAPI:
         self._validate_list("sequencing_files", sequencing_files)
         records = []
         for sf in sequencing_files:
+            # The server requires both paths - catch it here, naming the record, rather than a 400 for the batch
+            self._validate_string(f"SequencingFile '{sf.sample_name}' bam_file.path", sf.bam_file and sf.bam_file.path)
+            self._validate_string(f"SequencingFile '{sf.sample_name}' vcf_file.path", sf.vcf_file and sf.vcf_file.path)
             data = sf.to_dict()
             # put into hierarchial JSON DRF expects
-            fastq_r1 = data.pop("fastq_r1")
-            fastq_r2 = data.pop("fastq_r2")
-            data["unaligned_reads"] = {
-                "fastq_r1": {"path": fastq_r1},
-                "fastq_r2": {"path": fastq_r2}
-            }
+            fastq_r1 = data.pop("fastq_r1", None)
+            fastq_r2 = data.pop("fastq_r2", None)
+            if fastq_r1:
+                unaligned_reads = {"fastq_r1": {"path": fastq_r1}}
+                if fastq_r2:
+                    unaligned_reads["fastq_r2"] = {"path": fastq_r2}
+                data["unaligned_reads"] = unaligned_reads
+            elif fastq_r2:
+                raise ValueError(f"SequencingFile '{sf.sample_name}' has fastq_r2 without fastq_r1")
+            # No FastQs (BAM-first run) - server resolves the sample from sample_name
             records.append(data)
 
         json_data = {
@@ -231,7 +308,73 @@ class VariantGridAPI:
         return self._post("seqauto/api/v1/qc_gene_coverage/bulk_create",
                           json_data)
 
-    def upload_file(self, filename: str, path=_UNSET):
+    ##########################################################
+    ## Patient -> Specimen -> Extraction (SACGF/variantgrid#1707)
+    ## Creates are upserts keyed on the identifiers sent, so re-posting returns the same rows
+
+    def create_patient(self, patient: Patient):
+        if not self._require(ServerFeature.PATIENTS):
+            return None
+        self._validate_object("patient", patient)
+        return self._post("patients/api/v1/patient/", patient.to_dict())
+
+    def create_specimen(self, specimen: Specimen):
+        """ The specimen's patient must already exist on the server, otherwise this is a 400 """
+        if not self._require(ServerFeature.PATIENTS):
+            return None
+        self._validate_object("specimen", specimen)
+        return self._post("patients/api/v1/specimen/", specimen.to_dict())
+
+    def create_extraction(self, extraction: Extraction):
+        """ The extraction's specimen must already exist on the server, otherwise this is a 400 """
+        if not self._require(ServerFeature.PATIENTS):
+            return None
+        self._validate_object("extraction", extraction)
+        return self._post("patients/api/v1/extraction/", extraction.to_dict())
+
+    def create_specimen_measure(self, specimen_reference: ReferenceLike, measure: SpecimenMeasure):
+        """ An unknown specimen is a 400. Replaces any existing measure of the same type for the specimen """
+        if not self._require(ServerFeature.SPECIMEN_MEASURES):
+            return None
+        self._validate_reference("specimen_reference", specimen_reference)
+        self._validate_object("measure", measure)
+        json_data = {"specimen": reference_json(specimen_reference), **measure.to_dict()}
+        return self._post("patients/api/v1/specimen_measure/", json_data)
+
+    def create_specimen_measures(self, specimen_reference: ReferenceLike, measures: List[SpecimenMeasure]):
+        """ A run's measures (TMB, MSI, GIS etc) against one specimen in one call """
+        if not self._require(ServerFeature.SPECIMEN_MEASURES):
+            return None
+        self._validate_reference("specimen_reference", specimen_reference)
+        self._validate_list("measures", measures)
+        json_data = {
+            "specimen": reference_json(specimen_reference),
+            "measures": [measure.to_dict() for measure in measures],
+        }
+        return self._post("patients/api/v1/specimen_measure/bulk_create", json_data)
+
+    def link_sequencing_sample_extraction(self, sequencing_sample_lookup: SequencingSampleLookup,
+                                          extraction_reference: ReferenceLike) -> Optional[dict]:
+        """ Name the extraction a sequencing sample was made from. One call per sequencing sample is
+            enough - the server carries it to every Sample made from that sample's VCFs, and on to the
+            new rows if the sample sheet is re-sent.
+
+            Returns {"sequencing_sample", "match_status", "match_error", "extraction"}. An unknown
+            sequencing sample is a 400, but an extraction the server doesn't have yet is not an error:
+            the response is a 202 with match_status 'Pending', and the link attaches itself once the
+            extraction is created - there's no need to re-send. """
+        if not self._require(ServerFeature.LINK_EXTRACTION):
+            return None
+        self._validate_object("sequencing_sample_lookup", sequencing_sample_lookup)
+        self._validate_reference("extraction_reference", extraction_reference)
+        json_data = {
+            "sequencing_sample": sequencing_sample_lookup.to_dict(),
+            "extraction": reference_json(extraction_reference),
+        }
+        return self._post("seqauto/api/v1/sequencing_sample/link_extraction", json_data)
+
+    def upload_file(self, filename: str, path=_UNSET, metadata: Optional[dict] = None,
+                    file_type: Optional[Union[UploadFileType, str]] = None):
         """ Upload a file via multipart POST to upload/api/v1/file_upload.
 
             Returns {"uploaded_file_id": <id>, "sha256_hash": <hash>, ...}; identify the upload by
@@ -241,16 +384,53 @@ class VariantGridAPI:
                   (JointCalledVCF / SingleSampleVCF) by path. Defaults to `filename` for backwards
                   compatibility. Pass path=None to omit the query param entirely - required for ad-hoc
                   uploads such as the annotate/download flow, where sending a client-side path makes
-                  SeqAuto deployments try (and fail) to match it to a registered VCF. """
+                  SeqAuto deployments try (and fail) to match it to a registered VCF.
+
+            metadata: facts about the file it doesn't carry itself, sent as extra query params. A VCF accepts:
+                  'genome_build' - the build's own name ('GRCh37'), not an alias ('hg19')
+                  'source' - the caller/software, eg 'DRAGEN TSO500 SmallVariant'
+                  'extraction' - reference (str or ExternalReference) for every sample in the file
+                  'sample_extractions' - {vcf_sample_name: reference} for a multi-sample VCF
+                  Send 'extraction' or 'sample_extractions', not both. An unknown key is a 400. An extraction
+                  the server doesn't have yet is not - it attaches once the extraction is created.
+                  Needs the server feature 'upload_metadata'. Without it, SKIP uploads the file without the
+                  metadata (as older clients did) rather than not at all, and ERROR raises
+
+            file_type: the server's name for what this file is, eg UploadFileType.DRAGEN_TSO500_COMBINED_VARIANT_OUTPUT.
+                  Not sent (the server decides from the filename) - if given, the upload only happens when
+                  accepts_upload(file_type), so an older server doesn't mis-import it as something else """
+        if metadata and not self.supports(ServerFeature.UPLOAD_METADATA):
+            self._unsupported(f"upload metadata for '{filename}' (server doesn't support feature 'upload_metadata')")
+            metadata = None
+        if file_type and not self._require_upload(file_type):
+            return None
         url = self._get_url("upload/api/v1/file_upload")
         if path is _UNSET:
             path = filename
         params = {"path": path} if path is not None else {}
+        if metadata:
+            params.update(self._upload_metadata_params(metadata))
         with open(filename, "rb") as f:
             response = requests.post(url, headers=self.headers, files={"file": f}, params=params)
             extra_error_message = f"{filename=}"
             return self._handle_json_response(response, extra_error_message)
 
+    @staticmethod
+    def _upload_metadata_params(metadata: dict) -> dict:
+        """ Query params are strings - references and objects go as JSON, which the server parses """
+        if reserved := {"path", "force"} & set(metadata):
+            raise ValueError(f"Upload metadata can't use reserved query param(s): {', '.join(sorted(reserved))}")
+        params = {}
+        for key, value in metadata.items():
+            if isinstance(value, ExternalReference):
+                value = reference_json(value)
+            elif isinstance(value, dict):
+                value = {k: reference_json(v) for k, v in value.items()}
+            if isinstance(value, (dict, list)):
+                value = json.dumps(value)
+            params[key] = value
+        return params
+
     ###############
     ## Get methods
 
@@ -291,17 +471,19 @@ class VariantGridAPI:
             return f"sha256/{sha256}"
         raise ValueError("Must provide one of 'uploaded_file_id' or 'sha256'")
 
-    def poll_upload_status(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None) -> dict:
+    def poll_upload_status(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None) -> Optional[dict]:
         """ Single GET of an uploaded file's import/annotation status.
 
             Keyed by uploaded_file_id (returned from upload_file) or the SHA-256 of the uploaded file.
-            See wait_for_annotation to block until annotation is complete. """
+            See wait_for_annotation to block until annotation is complete. Needs server feature 'upload_status' """
+        if not self._require(ServerFeature.UPLOAD_STATUS):
+            return None
         segment = self._upload_key_segment(uploaded_file_id, sha256)
         return self._get(f"upload/api/v1/upload_status/{segment}")
 
     def wait_for_annotation(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None,
                             timeout: float = 3600, poll_interval: float = 10, sleep: Callable = time.sleep,
-                            max_transient_errors: int = 5) -> dict:
+                            max_transient_errors: int = 5) -> Optional[dict]:
         """ Poll poll_upload_status until 'annotation_complete' is true, then return the final status dict.
 
             Raises AnnotationError if the server reports an 'error', or TimeoutError if 'timeout' seconds elapse.
@@ -310,7 +492,9 @@ class VariantGridAPI:
             Transient server hiccups (5xx / connection / timeout - e.g. a brief 500 right after upload while the
             server is still creating the upload record) are tolerated: up to 'max_transient_errors' *consecutive*
             failures are retried before giving up. A 4xx response is treated as a real error and raised immediately.
-            The success counter resets whenever a poll succeeds. """
+            The success counter resets whenever a poll succeeds. Needs server feature 'upload_status' """
+        if not self._require(ServerFeature.UPLOAD_STATUS):
+            return None
         deadline = time.monotonic() + timeout
         transient_errors = 0
         while True:
@@ -349,7 +533,7 @@ class VariantGridAPI:
     def download_annotated(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None,
                            export_type: str = "vcf", dest_path: Optional[Union[str, Path]] = None,
                            timeout: float = 3600, poll_interval: float = 10,
-                           sleep: Callable = time.sleep) -> Path:
+                           sleep: Callable = time.sleep) -> Optional[Path]:
         """ Download the cohort-level annotated export of an uploaded VCF, saving it to disk.
 
             export_type is 'vcf' (gzipped *.vcf.gz) or 'csv' (zipped *.csv.zip). The export covers all samples
@@ -360,7 +544,9 @@ class VariantGridAPI:
             in the current directory; if it is an existing directory the attachment filename is placed inside it;
             otherwise it is treated as the full destination path. Returns the Path written.
 
-            Raises TimeoutError if the file isn't ready within 'timeout' seconds. """
+            Raises TimeoutError if the file isn't ready within 'timeout' seconds. Needs server feature 'upload_status' """
+        if not self._require(ServerFeature.UPLOAD_STATUS):
+            return None
         if export_type not in ("vcf", "csv"):
             raise ValueError(f"export_type must be 'vcf' or 'csv', got {export_type!r}")
         segment = self._upload_key_segment(uploaded_file_id, sha256)
@@ -402,10 +588,13 @@ class VariantGridAPI:
             return None
 
     def annotate_vcf(self, filename: str, export_type: str = "vcf", dest_path: Optional[Union[str, Path]] = None,
-                     timeout: float = 3600, poll_interval: float = 10, sleep: Callable = time.sleep) -> Path:
+                     timeout: float = 3600, poll_interval: float = 10, sleep: Callable = time.sleep) -> Optional[Path]:
         """ Convenience one-liner: upload a VCF, wait for annotation to finish, download the annotated export.
 
-            Chains upload_file -> wait_for_annotation -> download_annotated and returns the Path written. """
+            Chains upload_file -> wait_for_annotation -> download_annotated and returns the Path written.
+            Needs server feature 'upload_status' - checked before uploading """
+        if not self._require(ServerFeature.UPLOAD_STATUS):
+            return None
         # path is SeqAuto-only and makes ad-hoc uploads fail the import - omit it for the annotate flow
         upload = self.upload_file(filename, path=None)
         uploaded_file_id = upload["uploaded_file_id"]

{variantgrid_api-1.4.0 → variantgrid_api-1.6.0}/src/variantgrid_api/cli.py

@@ -13,7 +13,7 @@ import sys
 
 import requests
 
-from variantgrid_api.api_client import VariantGridAPI, AnnotationError
+from variantgrid_api.api_client import VariantGridAPI, AnnotationError, UnsupportedFeatureError
 
 DEFAULT_SERVER = "https://variantgrid.com"
 
@@ -147,6 +147,9 @@ def main(argv=None):
     except requests.HTTPError as e:
         print(f"HTTP error: {e}", file=sys.stderr)
         return EXIT_ERROR
+    except UnsupportedFeatureError as e:
+        print(f"This VariantGrid server can't annotate uploaded VCFs via the API: {e}", file=sys.stderr)
+        return EXIT_ERROR
 
 
 if __name__ == "__main__":