vqflow 0.1.0__py3-none-any.whl

vqflow/__init__.py

@@ -0,0 +1,23 @@
+"""VQFlow's Python interface for versioned dataset exports."""
+
+from .builder import DatasetExportBuilder
+from .client import VQFlow
+from .exceptions import (
+    AmbiguousResourceError, AuthenticationError, ConfigurationError, DownloadError,
+    ExportConflictError, ExportCreationUncertainError, ExportFailedError,
+    ExportTimeoutError, NotFoundError, PermissionDeniedError, ProtocolError,
+    TransportError, VQFlowError,
+)
+from .models import ExportFormat, QAStatus, ReviewStatus
+from .resources import Dataset, Project, Workspace
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "VQFlow", "DatasetExportBuilder", "Workspace", "Project", "Dataset",
+    "ExportFormat", "ReviewStatus", "QAStatus", "VQFlowError", "ConfigurationError",
+    "AuthenticationError", "PermissionDeniedError", "NotFoundError",
+    "AmbiguousResourceError", "ExportConflictError", "ExportFailedError",
+    "ExportTimeoutError", "ExportCreationUncertainError", "TransportError",
+    "ProtocolError", "DownloadError", "__version__",
+]

vqflow/builder.py

@@ -0,0 +1,103 @@
+"""Fluent configuration for dataset ZIP exports."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .client import VQFlow
+from .exceptions import ConfigurationError
+from .models import ExportFormat, QAStatus, ReviewStatus, export_format, qa_status, required_name, review_status
+from .resources import UNSPECIFIED, _Unspecified
+
+
+class DatasetExportBuilder:
+    """Configure an export; only export() and exportCurated() perform work."""
+
+    def __init__(self, client: VQFlow) -> None:
+        if not isinstance(client, VQFlow):
+            raise ConfigurationError("Supply a VQFlow client to DatasetExportBuilder.")
+        self._client = client
+        self._workspace: str | None = None
+        self._project: str | None = None
+        self._dataset: str | None = None
+        self._dataset_version: str | None | _Unspecified = UNSPECIFIED
+        self._format: ExportFormat | None = None
+        self._version: str | None = None
+        self._destination: str | Path | None = None
+        self._review: ReviewStatus | None = None
+        self._qa: QAStatus | None = None
+        self._export_id: int | None = None
+
+    def withWorkspace(self, name: str) -> DatasetExportBuilder:
+        self._workspace = required_name(name, "Workspace name")
+        return self
+
+    def withProject(self, name: str) -> DatasetExportBuilder:
+        self._project = required_name(name, "Project name")
+        return self
+
+    def withDataset(self, name: str) -> DatasetExportBuilder:
+        self._dataset = required_name(name, "Dataset name")
+        return self
+
+    def withDatasetVersion(self, version: str | None) -> DatasetExportBuilder:
+        """Disambiguate the source dataset; None selects its unversioned record."""
+        self._dataset_version = None if version is None else required_name(version, "Dataset version")
+        return self
+
+    def withFormat(self, format: ExportFormat | str) -> DatasetExportBuilder:
+        self._format = export_format(format)
+        return self
+
+    def withVersion(self, version: str) -> DatasetExportBuilder:
+        self._version = required_name(version, "Export version")
+        return self
+
+    def withExportId(self, export_id: int) -> DatasetExportBuilder:
+        """Download one exact stored export, preserving its original selection."""
+        if type(export_id) is not int or export_id <= 0:
+            raise ConfigurationError("Export ID must be a positive integer.")
+        self._export_id = export_id
+        return self
+
+    def withDestination(self, destination: str | Path) -> DatasetExportBuilder:
+        if not isinstance(destination, (str, Path)) or (isinstance(destination, str) and not destination.strip()):
+            raise ConfigurationError("Supply a destination directory.")
+        self._destination = destination
+        return self
+
+    def withReview(self, status: ReviewStatus | str | None) -> DatasetExportBuilder:
+        self._review = review_status(status)
+        return self
+
+    def withQA(self, status: QAStatus | str | None) -> DatasetExportBuilder:
+        self._qa = qa_status(status)
+        return self
+
+    def export(self, *, wait_timeout: float = 7200, poll_interval: float = 5, overwrite: bool = False) -> Path:
+        return self._execute(self._review, self._qa, wait_timeout, poll_interval, overwrite)
+
+    def exportCurated(self, *, wait_timeout: float = 7200, poll_interval: float = 5, overwrite: bool = False) -> Path:
+        """Use APPROVED for both filters without changing the saved builder."""
+        return self._execute(ReviewStatus.APPROVED, QAStatus.APPROVED, wait_timeout, poll_interval, overwrite)
+
+    def _execute(self, review, qa, wait_timeout, poll_interval, overwrite) -> Path:
+        fields = (
+            (self._workspace, "withWorkspace"), (self._project, "withProject"),
+            (self._dataset, "withDataset"), (self._format, "withFormat"),
+            (self._version, "withVersion"), (self._destination, "withDestination"),
+        )
+        missing = [name for value, name in fields if value is None]
+        if missing:
+            raise ConfigurationError("Complete the export configuration: " + ", ".join(missing) + ".")
+        dataset = self._client.workspace(self._workspace).project(self._project).dataset(
+            self._dataset, dataset_version=self._dataset_version,
+        )
+        return dataset.export(
+            self._format, self._version, self._destination, review=review, qa=qa,
+            wait_timeout=wait_timeout, poll_interval=poll_interval, overwrite=overwrite,
+            export_id=self._export_id,
+        )
+
+    def __repr__(self) -> str:
+        return "DatasetExportBuilder()"

vqflow/client.py

@@ -0,0 +1,64 @@
+"""The public VQFlow client."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from .exceptions import ConfigurationError
+from .models import required_name
+from .transport import Transport
+
+if TYPE_CHECKING:
+    from .resources import Workspace
+
+
+class VQFlow:
+    """Connect to VQFlow using a caller-supplied API key.
+
+    Credentials are read only from the argument or VQFLOW_API_KEY. Environment
+    files are never discovered or loaded. The API base URL includes /api/v1.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("VQFLOW_API_KEY")
+        url = base_url if base_url is not None else os.environ.get("VQFLOW_API_URL")
+        if not key:
+            raise ConfigurationError("Supply api_key or set VQFLOW_API_KEY.")
+        if not url:
+            raise ConfigurationError("Supply base_url or set VQFLOW_API_URL to the HTTPS API base URL.")
+        self._transport = Transport(url, key, timeout=timeout, max_retries=max_retries)
+        self._closed = False
+
+    def workspace(self, name: str) -> Workspace:
+        """Select a workspace by its exact name; lookup occurs on export."""
+        from .resources import Workspace
+
+        self._ensure_open()
+        return Workspace(self, required_name(name, "Workspace name"))
+
+    def close(self) -> None:
+        if not self._closed:
+            self._transport.close()
+            self._closed = True
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ConfigurationError("This VQFlow client is closed. Create a new client to continue.")
+
+    def __enter__(self) -> VQFlow:
+        self._ensure_open()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"VQFlow(closed={self._closed})"

vqflow/exceptions.py

@@ -0,0 +1,70 @@
+"""Public errors with intentionally limited, safe diagnostic information."""
+
+from __future__ import annotations
+
+
+class VQFlowError(Exception):
+    """Base class for errors reported by the VQFlow client."""
+
+
+class ConfigurationError(VQFlowError):
+    """The supplied client configuration is invalid."""
+
+
+class AuthenticationError(VQFlowError):
+    """The server did not accept the supplied API key."""
+
+
+class PermissionDeniedError(VQFlowError):
+    """The API key cannot perform the requested operation."""
+
+
+class NotFoundError(VQFlowError):
+    """The requested resource could not be found."""
+
+
+class AmbiguousResourceError(VQFlowError):
+    """More than one resource matches the supplied selection."""
+
+
+class ExportConflictError(VQFlowError):
+    """An existing export conflicts with the requested export."""
+
+
+class TransportError(VQFlowError):
+    """An API request could not be completed."""
+
+
+class ProtocolError(VQFlowError):
+    """The server response does not satisfy the expected contract."""
+
+
+class DownloadError(VQFlowError):
+    """An archive could not be downloaded and safely saved."""
+
+
+class _ExportStateError(VQFlowError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        task_id: int | str | None = None,
+        export_id: int | str | None = None,
+        status: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.task_id = task_id
+        self.export_id = export_id
+        self.status = status
+
+
+class ExportFailedError(_ExportStateError):
+    """The export task finished unsuccessfully."""
+
+
+class ExportTimeoutError(_ExportStateError):
+    """The export did not become available before the wait deadline."""
+
+
+class ExportCreationUncertainError(_ExportStateError, TransportError):
+    """Creation may have succeeded; inspect existing exports before retrying."""

vqflow/exports.py

@@ -0,0 +1,322 @@
+"""Resolve, generate, and download a versioned dataset export."""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from .exceptions import (
+    AmbiguousResourceError,
+    ConfigurationError,
+    ExportConflictError,
+    ExportCreationUncertainError,
+    ExportFailedError,
+    ExportTimeoutError,
+    PermissionDeniedError,
+    ProtocolError,
+    TransportError,
+)
+from .models import ExportFormat, QAStatus, ReviewStatus
+
+
+def _integer(value: Any, *, minimum: int = 0) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value >= minimum
+
+
+def iter_pages(
+    transport: Any, path: str, params: Mapping[str, Any] | None = None
+) -> Iterator[dict[str, Any]]:
+    """Yield records from Core's one-based requests and zero-based page metadata."""
+    query = dict(params or {})
+    query.pop("page", None)
+    size = query.setdefault("size", 100)
+    if not _integer(size, minimum=1):
+        raise ConfigurationError("Page size must be a positive integer.")
+    first_totals: tuple[int, int] | None = None
+    received = 0
+    page = 1
+    while True:
+        response = transport.get(path, params={**query, "page": page})
+        if not isinstance(response, dict):
+            raise ProtocolError("The server returned an invalid page response.")
+        records = response.get("data")
+        links = response.get("links")
+        if not isinstance(records, list) or not isinstance(links, dict):
+            raise ProtocolError("The server returned invalid pagination metadata.")
+        if not all(_integer(links.get(key)) for key in (
+            "totalPages", "totalObjects", "currentPage", "pageSize"
+        )):
+            raise ProtocolError("The server returned invalid pagination metadata.")
+        total_pages, total_objects = links["totalPages"], links["totalObjects"]
+        if links["currentPage"] != page - 1 or links["pageSize"] != size:
+            raise ProtocolError("The server returned an unexpected page.")
+        expected_pages = (total_objects + size - 1) // size
+        if total_pages != expected_pages:
+            raise ProtocolError("The server returned inconsistent pagination totals.")
+        totals = (total_pages, total_objects)
+        if first_totals is not None and totals != first_totals:
+            raise ProtocolError("The result list changed while it was being read. Try again.")
+        first_totals = totals
+        expected_count = min(size, max(total_objects - received, 0))
+        if len(records) != expected_count or not all(isinstance(row, dict) for row in records):
+            raise ProtocolError("The server returned an incomplete or invalid page.")
+        for row in records:
+            yield row
+        received += len(records)
+        if page >= total_pages:
+            return
+        page += 1
+
+
+def _option(value: Any, enum_type: Any, name: str) -> str:
+    try:
+        return enum_type(value).value
+    except (TypeError, ValueError):
+        raise ConfigurationError(f"Choose a supported {name}.") from None
+
+
+def _verify_scope(record: dict[str, Any], dataset: dict[str, Any], version: str) -> None:
+    if not _integer(record.get("id"), minimum=1):
+        raise ProtocolError("The server returned an invalid export identifier.")
+    if not _integer(record.get("datasetId"), minimum=1) or record["datasetId"] != dataset["id"]:
+        raise ProtocolError("The server returned an export for a different dataset.")
+    if "datasetVersion" not in record or record["datasetVersion"] != dataset.get("version"):
+        raise ProtocolError("The server returned an export for a different dataset version.")
+    if record.get("exportVersion") != version:
+        raise ProtocolError("The server returned a different export version.")
+    for field, expected in (
+        ("datasetName", dataset.get("name")),
+        ("workspaceName", dataset.get("workspaceName")),
+        ("projectName", dataset.get("projectName")),
+    ):
+        if expected is not None and record.get(field) != expected:
+            raise ProtocolError("The server returned an export with a different dataset scope.")
+
+
+def _find_export(
+    transport: Any, dataset: dict[str, Any], version: str, format_value: str
+) -> dict[str, Any] | None:
+    records = list(iter_pages(transport, "dataset-exports", {
+        "datasetId": dataset["id"], "exportVersion": version,
+        "sortKey": "id", "sortOrder": "ASCENDING",
+    }))
+    seen: set[int] = set()
+    for record in records:
+        _verify_scope(record, dataset, version)
+        if record["id"] in seen:
+            raise ProtocolError("The server repeated an export record across pages.")
+        seen.add(record["id"])
+    matches = [record for record in records if record.get("exportFormat") == format_value
+               and record.get("resultForm") == "ZIP_ARCHIVE"]
+    if len(matches) > 1:
+        raise AmbiguousResourceError("Several exports match this version and format. Choose a unique export version.")
+    if matches:
+        return matches[0]
+    if records:
+        raise ExportConflictError("This export version exists with a different format or delivery type. Choose another version.")
+    return None
+
+
+def _verify_task(
+    task: Any, dataset: dict[str, Any], version: str, format_value: str,
+    review_value: str | None, qa_value: str | None, *, task_id: int, export_id: int,
+    verify_selection: bool = True,
+) -> dict[str, Any]:
+    if not isinstance(task, dict):
+        raise ProtocolError("The server returned an invalid export task.")
+    _verify_scope(task, dataset, version)
+    if task["id"] != task_id or not _integer(task.get("datasetExportId"), minimum=1) or task["datasetExportId"] != export_id:
+        raise ProtocolError("The server returned an unrelated export task.")
+    if task.get("exportFormat") != format_value or task.get("resultForm") != "ZIP_ARCHIVE":
+        raise ExportConflictError("The export task uses a different format or delivery type.")
+    if verify_selection:
+        _verify_selection(task, review_value, qa_value)
+    if task.get("canAccessArtifact") is False:
+        raise PermissionDeniedError("You do not have permission to download this export.")
+    if task.get("status") not in {"SCHEDULED", "IN_PROGRESS", "COMPLETED", "FAILED", "CANCELLED"}:
+        raise ProtocolError("The server returned an unknown export task status.")
+    return task
+
+
+def _verify_selection(task: dict[str, Any], review_value: str | None, qa_value: str | None) -> None:
+    fields = (
+        "reviewStatus", "checkStatus", "categoryIds", "search", "mediaType",
+        "reviewerAssignmentState", "qaAssignmentState", "selectionMode", "selectedMediaCount",
+    )
+    if any(field not in task for field in fields):
+        raise ExportConflictError("The existing export's selection cannot be verified. Choose another export version.")
+    if (
+        task["reviewStatus"] != review_value or task["checkStatus"] != qa_value
+        or task["categoryIds"] not in (None, [])
+        or task["search"] not in (None, "")
+        or task["mediaType"] is not None
+        or task["reviewerAssignmentState"] is not None
+        or task["qaAssignmentState"] is not None
+        or task["selectionMode"] != "FILTERED_RESULTS"
+        # The backend replaces this count with the prepared total for every mode.
+        or not _integer(task["selectedMediaCount"])
+    ):
+        raise ExportConflictError("This export version uses a different media selection. Choose another version.")
+
+
+def _verify_export(
+    record: Any, dataset: dict[str, Any], version: str, format_value: str,
+    *, export_id: int, task_id: int | None,
+) -> dict[str, Any]:
+    if not isinstance(record, dict):
+        raise ProtocolError("The server returned an invalid export record.")
+    _verify_scope(record, dataset, version)
+    if record["id"] != export_id or record.get("taskId") != task_id:
+        raise ProtocolError("The server returned an unrelated export record.")
+    if task_id is not None and not _integer(record.get("taskId"), minimum=1):
+        raise ProtocolError("The server returned an invalid export task reference.")
+    if record.get("exportFormat") != format_value or record.get("resultForm") != "ZIP_ARCHIVE":
+        raise ExportConflictError("The export uses a different format or delivery type.")
+    if record.get("canAccessArtifact") is False:
+        raise PermissionDeniedError("You do not have permission to download this export.")
+    if record.get("status") not in {"SCHEDULED", "IN_PROGRESS", "READY", "FAILED", "CANCELLED"}:
+        raise ProtocolError("The server returned an unknown export status.")
+    return record
+
+
+def _download_zip(transport: Any, export_id: int, destination: Path, overwrite: bool) -> Path:
+    access = transport.get(f"dataset-exports/{export_id}/access")
+    if not isinstance(access, dict) or not _integer(access.get("id"), minimum=1) or access["id"] != export_id:
+        raise ProtocolError("The server returned download access for a different export.")
+    if access.get("resultForm") != "ZIP_ARCHIVE" or not isinstance(access.get("url"), str) or not access["url"].strip():
+        raise ProtocolError("The server returned invalid ZIP download access.")
+    return transport.download(access["url"], destination,
+                              file_name=f"vqflow-export-{export_id}.zip", overwrite=overwrite)
+
+
+def export_dataset(
+    transport: Any,
+    dataset: dict[str, Any],
+    *,
+    format: ExportFormat,
+    version: str,
+    destination: str | Path,
+    review: ReviewStatus | None = None,
+    qa: QAStatus | None = None,
+    export_id: int | None = None,
+    wait_timeout: float = 7200,
+    poll_interval: float = 5,
+    overwrite: bool = False,
+) -> Path:
+    """Download an exact version, generating its ZIP only when that version is absent.
+
+    A local wait timeout leaves the server task running. The raised exception keeps
+    its task and export identifiers so the same version can be requested again.
+    An explicit export_id downloads that exact artifact with its recorded selection;
+    it never creates an export and cannot be combined with media status filters.
+    """
+    if not isinstance(dataset, dict) or not _integer(dataset.get("id"), minimum=1):
+        raise ConfigurationError("Choose a dataset with a valid identifier.")
+    dataset = dict(dataset)
+    if not isinstance(version, str) or not version.strip() or len(version.strip()) > 255:
+        raise ConfigurationError("Export version must contain between 1 and 255 characters.")
+    version = version.strip()
+    format_value = _option(format, ExportFormat, "export format")
+    review_value = None if review is None else _option(review, ReviewStatus, "review status")
+    qa_value = None if qa is None else _option(qa, QAStatus, "QA status")
+    explicit_id = export_id is not None
+    if explicit_id and not _integer(export_id, minimum=1):
+        raise ConfigurationError("Export ID must be a positive integer.")
+    if explicit_id and (review is not None or qa is not None):
+        raise ConfigurationError("An exact export ID cannot be combined with review or QA filters.")
+    for value, minimum, label in ((wait_timeout, 0, "Wait timeout"), (poll_interval, 0, "Poll interval")):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < minimum or (label == "Poll interval" and value == 0):
+            raise ConfigurationError(f"{label} must be a finite {'positive' if label == 'Poll interval' else 'nonnegative'} number.")
+    if not isinstance(overwrite, bool):
+        raise ConfigurationError("Overwrite must be true or false.")
+    if not isinstance(destination, (str, Path)) or (isinstance(destination, str) and not destination.strip()):
+        raise ConfigurationError("Choose a destination directory.")
+    if "\x00" in str(destination):
+        raise ConfigurationError("Choose a valid destination directory.")
+    destination_path = Path(destination).expanduser()
+    if destination_path.exists() and not destination_path.is_dir():
+        raise ConfigurationError("The destination must be a directory.")
+    deadline = time.monotonic() + wait_timeout
+    if explicit_id:
+        record = transport.get(f"dataset-exports/{export_id}")
+        if not isinstance(record, dict):
+            raise ProtocolError("The server returned an invalid export record.")
+        task_id = record.get("taskId")
+        _verify_export(record, dataset, version, format_value, export_id=export_id, task_id=task_id)
+    else:
+        record = _find_export(transport, dataset, version, format_value)
+    created = record is None
+    if record is None:
+        payload: dict[str, Any] = {
+            "datasetId": dataset["id"], "exportVersion": version,
+            "exportFormat": format_value, "resultForm": "ZIP_ARCHIVE",
+        }
+        if review_value is not None:
+            payload["reviewStatus"] = review_value
+        if qa_value is not None:
+            payload["checkStatus"] = qa_value
+        task = transport.post("datasets/export", payload)
+        if not isinstance(task, dict) or not _integer(task.get("id"), minimum=1) or not _integer(task.get("datasetExportId"), minimum=1):
+            raise ExportCreationUncertainError("The server accepted the export request but its task could not be confirmed. Check existing exports before trying again.")
+        task_id, export_id = task["id"], task["datasetExportId"]
+    else:
+        export_id = record["id"]
+        task_id = record.get("taskId")
+        if explicit_id and record["status"] in {"FAILED", "CANCELLED"}:
+            raise ExportFailedError("The export is not available for download.", task_id=task_id,
+                                    export_id=export_id, status=record["status"])
+        if explicit_id and task_id is None:
+            if record["status"] == "READY":
+                return _download_zip(transport, export_id, destination_path, overwrite)
+            raise ExportConflictError("This export is not ready and has no task to monitor.")
+        if not _integer(task_id, minimum=1):
+            raise ExportConflictError("The existing export's selection cannot be verified. Choose another export version.")
+        _verify_export(record, dataset, version, format_value, export_id=export_id, task_id=task_id)
+        task = transport.get(f"dataset-export-tasks/{task_id}")
+    task = _verify_task(task, dataset, version, format_value, review_value, qa_value,
+                        task_id=task_id, export_id=export_id, verify_selection=not explicit_id)
+    if created:
+        try:
+            confirmed = _find_export(transport, dataset, version, format_value)
+        except TransportError:
+            raise ExportCreationUncertainError(
+                "The export task was created but its version could not be confirmed. Check the same version before trying again.",
+                task_id=task_id, export_id=export_id, status=task["status"],
+            ) from None
+        if confirmed is None:
+            raise ExportCreationUncertainError(
+                "The export task was created but its version could not be confirmed. Check the same version before trying again.",
+                task_id=task_id, export_id=export_id, status=task["status"],
+            )
+        _verify_export(confirmed, dataset, version, format_value, export_id=export_id, task_id=task_id)
+    while task["status"] != "COMPLETED":
+        status = task["status"]
+        if status in {"FAILED", "CANCELLED"}:
+            raise ExportFailedError("The export did not complete. Review its task before trying again.", task_id=task_id, export_id=export_id, status=status)
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise ExportTimeoutError("Waiting for the export timed out. Request the same version to check it again.", task_id=task_id, export_id=export_id, status=status)
+        time.sleep(min(poll_interval, remaining))
+        if time.monotonic() >= deadline:
+            raise ExportTimeoutError("Waiting for the export timed out. Request the same version to check it again.", task_id=task_id, export_id=export_id, status=status)
+        task = _verify_task(transport.get(f"dataset-export-tasks/{task_id}"), dataset, version,
+                            format_value, review_value, qa_value, task_id=task_id,
+                            export_id=export_id, verify_selection=not explicit_id)
+    record = _verify_export(transport.get(f"dataset-exports/{export_id}"), dataset, version,
+                            format_value, export_id=export_id, task_id=task_id)
+    if record["status"] in {"FAILED", "CANCELLED"}:
+        raise ExportFailedError("The export is no longer available for download.", task_id=task_id, export_id=export_id, status=record["status"])
+    if record["status"] != "READY":
+        raise ProtocolError("The completed export is not ready for download. Try again.")
+    if not explicit_id:
+        # A second resolution detects duplicate versions created by concurrent callers.
+        confirmed = _find_export(transport, dataset, version, format_value)
+        if confirmed is None or confirmed["id"] != export_id:
+            raise ExportConflictError("The export version changed before download. Check existing exports before trying again.")
+        _verify_export(confirmed, dataset, version, format_value, export_id=export_id, task_id=task_id)
+        if confirmed["status"] != "READY":
+            raise ExportConflictError("The export changed before download. Check its task before trying again.")
+    return _download_zip(transport, export_id, destination_path, overwrite)

vqflow/models.py

@@ -0,0 +1,59 @@
+"""Supported dataset formats and media selection statuses."""
+
+from enum import Enum
+
+from .exceptions import ConfigurationError
+
+
+class ExportFormat(str, Enum):
+    COCO = "COCO"
+    CATEGORY_FOLDERS = "CATEGORY_FOLDERS"
+    VQFLOW_NATIVE = "VQFLOW_NATIVE"
+
+
+class ReviewStatus(str, Enum):
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+    PENDING = "PENDING"
+    NONE = "NONE"
+
+
+class QAStatus(str, Enum):
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+    PENDING = "PENDING"
+    NONE = "NONE"
+
+
+def export_format(value: ExportFormat | str) -> ExportFormat:
+    if isinstance(value, ExportFormat):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().upper().replace("-", "_").replace(" ", "_")
+        if normalized == "NATIVE":
+            normalized = "VQFLOW_NATIVE"
+        if normalized in ExportFormat.__members__:
+            return ExportFormat[normalized]
+    raise ConfigurationError("Choose coco, category_folders, or vqflow_native as the export format.")
+
+
+def review_status(value: ReviewStatus | str | None) -> ReviewStatus | None:
+    if value is None or isinstance(value, ReviewStatus):
+        return value
+    if isinstance(value, str) and value.strip().upper() in ReviewStatus.__members__:
+        return ReviewStatus[value.strip().upper()]
+    raise ConfigurationError("Review status must be APPROVED, REJECTED, PENDING, NONE, or None.")
+
+
+def qa_status(value: QAStatus | str | None) -> QAStatus | None:
+    if value is None or isinstance(value, QAStatus):
+        return value
+    if isinstance(value, str) and value.strip().upper() in QAStatus.__members__:
+        return QAStatus[value.strip().upper()]
+    raise ConfigurationError("QA status must be APPROVED, REJECTED, PENDING, NONE, or None.")
+
+
+def required_name(value: object, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigurationError(f"{field} must be a non-empty string.")
+    return value.strip()