vws-python 2026.8.14__py3-none-any.whl

vws/query.py

@@ -0,0 +1,194 @@
+"""Tools for interacting with the Vuforia Cloud Recognition Web APIs."""
+
+import json
+from http import HTTPMethod, HTTPStatus
+from typing import Any
+
+from beartype import BeartypeConf, beartype
+from urllib3.filepost import encode_multipart_formdata
+from vws_auth_tools import authorization_header, rfc_1123_date
+
+from vws._image_utils import ImageType as _ImageType
+from vws._image_utils import get_image_data as _get_image_data
+from vws.exceptions.base_exceptions import CloudRecoError
+from vws.exceptions.cloud_reco_exceptions import (
+    AuthenticationFailureError,
+    BadImageError,
+    InactiveProjectError,
+    MaxNumResultsOutOfRangeError,
+    RequestTimeTooSkewedError,
+)
+from vws.exceptions.custom_exceptions import (
+    RequestEntityTooLargeError,
+    ServerError,
+)
+from vws.include_target_data import CloudRecoIncludeTargetData
+from vws.reports import QueryResult
+from vws.transports import RequestsTransport, Transport
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class CloudRecoService:
+    """An interface to the Vuforia Cloud Recognition Web APIs."""
+
+    def __init__(
+        self,
+        *,
+        client_access_key: str,
+        client_secret_key: str,
+        base_vwq_url: str = "https://cloudreco.vuforia.com",
+        request_timeout_seconds: float | tuple[float, float] = 30.0,
+        transport: Transport | None = None,
+    ) -> None:
+        """
+        Args:
+            client_access_key: A VWS client access key.
+            client_secret_key: A VWS client secret key.
+            base_vwq_url: The base URL for the VWQ API.
+            request_timeout_seconds: The timeout for each
+                HTTP request. This can be a float to set both
+                the connect and read timeouts, or a
+                (connect, read) tuple.
+            transport: The HTTP transport to use for
+                requests. Defaults to
+                ``RequestsTransport()``.
+        """
+        self._client_access_key = client_access_key
+        self._client_secret_key = client_secret_key
+        self._base_vwq_url = base_vwq_url
+        self._request_timeout_seconds = request_timeout_seconds
+        self._transport = (
+            transport if transport is not None else RequestsTransport()
+        )
+
+    def query(
+        self,
+        *,
+        image: _ImageType,
+        max_num_results: int = 1,
+        include_target_data: CloudRecoIncludeTargetData = (
+            CloudRecoIncludeTargetData.TOP
+        ),
+    ) -> list[QueryResult]:
+        """Use the Vuforia Web Query API to make an Image Recognition
+        Query.
+
+        See
+        https://developer.vuforia.com/library/web-api/vuforia-query-web-api
+        for parameter details.
+
+        Args:
+            image: The image to make a query against.
+            max_num_results: The maximum number of matching targets to be
+                returned.
+            include_target_data: Indicates if target_data records shall be
+                returned for the matched targets. Accepted values are top
+                (default value, only return target_data for top ranked match),
+                none (return no target_data), all (for all matched targets).
+
+        Raises:
+            ~vws.exceptions.cloud_reco_exceptions.AuthenticationFailureError:
+                The client access key pair is not correct.
+            ~vws.exceptions.cloud_reco_exceptions.MaxNumResultsOutOfRangeError:
+                ``max_num_results`` is not within the range (1, 50).
+            ~vws.exceptions.cloud_reco_exceptions.InactiveProjectError: The
+                project is inactive.
+            ~vws.exceptions.cloud_reco_exceptions.RequestTimeTooSkewedError:
+                There is an error with the time sent to Vuforia.
+            ~vws.exceptions.cloud_reco_exceptions.BadImageError: There is a
+                problem with the given image. For example, it must be a JPEG or
+                PNG file in the grayscale or RGB color space.
+            ~vws.exceptions.custom_exceptions.RequestEntityTooLargeError: The
+                given image is too large.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an
+                error with Vuforia's servers.
+            ~vws.exceptions.base_exceptions.CloudRecoError: Vuforia returned
+                a client error without a recognized JSON body.
+            json.JSONDecodeError: Vuforia returned a successful response with
+                an invalid JSON body.
+
+        Returns:
+            An ordered list of target details of matching targets.
+        """
+        image_content = _get_image_data(image=image)
+        body: dict[str, Any] = {
+            "image": ("image.jpeg", image_content, "image/jpeg"),
+            "max_num_results": (None, int(max_num_results), "text/plain"),
+            "include_target_data": (
+                None,
+                include_target_data.value,
+                "text/plain",
+            ),
+        }
+        date = rfc_1123_date()
+        request_path = "/v1/query"
+        content, content_type_header = encode_multipart_formdata(fields=body)
+        method = HTTPMethod.POST
+
+        authorization_string = authorization_header(
+            access_key=self._client_access_key,
+            secret_key=self._client_secret_key,
+            method=method,
+            content=content,
+            # Note that this is not the actual Content-Type header value sent.
+            content_type="multipart/form-data",
+            date=date,
+            request_path=request_path,
+        )
+
+        headers = {
+            "Authorization": authorization_string,
+            "Date": date,
+            "Content-Type": content_type_header,
+        }
+
+        response = self._transport(
+            method=method,
+            url=self._base_vwq_url.rstrip("/") + request_path,
+            headers=headers,
+            data=content,
+            request_timeout=self._request_timeout_seconds,
+        )
+
+        if response.status_code == HTTPStatus.REQUEST_ENTITY_TOO_LARGE:
+            raise RequestEntityTooLargeError(response=response)
+
+        if "Integer out of range" in response.text:
+            raise MaxNumResultsOutOfRangeError(response=response)
+
+        if (
+            response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR
+        ):  # pragma: no cover
+            raise ServerError(response=response)
+
+        content_type = {
+            key.lower(): value for key, value in response.headers.items()
+        }.get("content-type", "")
+        if (
+            response.status_code >= HTTPStatus.BAD_REQUEST
+            and not content_type.lower().startswith("application/json")
+        ):
+            raise CloudRecoError(response=response)
+
+        try:
+            response_body = json.loads(s=response.text)
+        except json.JSONDecodeError as exc:
+            if response.status_code >= HTTPStatus.BAD_REQUEST:
+                raise CloudRecoError(response=response) from exc
+            raise
+
+        result_code = response_body["result_code"]
+        if result_code != "Success":
+            exception = {
+                "AuthenticationFailure": AuthenticationFailureError,
+                "BadImage": BadImageError,
+                "InactiveProject": InactiveProjectError,
+                "RequestTimeTooSkewed": RequestTimeTooSkewedError,
+            }[result_code]
+            raise exception(response=response)
+
+        result_list = list(response_body["results"])
+        return [
+            QueryResult.from_response_dict(response_dict=item)
+            for item in result_list
+        ]

vws/reports.py

@@ -0,0 +1,391 @@
+"""Classes for representing Vuforia reports."""
+
+import csv
+import datetime
+import io
+from collections.abc import Sequence  # noqa: TC003
+from dataclasses import dataclass
+from enum import Enum, unique
+from typing import Any, Self
+
+from beartype import BeartypeConf, beartype
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class DatabaseSummaryReport:
+    """A database summary report.
+
+    See
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.
+    """
+
+    active_images: int
+    current_month_recos: int
+    failed_images: int
+    inactive_images: int
+    name: str
+    previous_month_recos: int
+    processing_images: int
+    reco_threshold: int
+    request_quota: int
+    request_usage: int
+    target_quota: int
+    total_recos: int
+
+    @classmethod
+    def from_response_dict(cls, response_dict: dict[str, Any]) -> Self:
+        """Construct from a VWS API response dict."""
+        return cls(
+            active_images=int(response_dict["active_images"]),
+            current_month_recos=int(response_dict["current_month_recos"]),
+            failed_images=int(response_dict["failed_images"]),
+            inactive_images=int(response_dict["inactive_images"]),
+            name=response_dict["name"],
+            previous_month_recos=int(response_dict["previous_month_recos"]),
+            processing_images=int(response_dict["processing_images"]),
+            reco_threshold=int(response_dict["reco_threshold"]),
+            request_quota=int(response_dict["request_quota"]),
+            request_usage=int(response_dict["request_usage"]),
+            target_quota=int(response_dict["target_quota"]),
+            total_recos=int(response_dict["total_recos"]),
+        )
+
+
+@beartype
+@unique
+class TargetStatuses(Enum):
+    """Constants representing VWS target statuses.
+
+    See the 'status' field in
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record
+    """
+
+    PROCESSING = "processing"
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class TargetSummaryReport:
+    """A target summary report.
+
+    See
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.
+    """
+
+    status: TargetStatuses
+    database_name: str
+    target_name: str
+    upload_date: datetime.date
+    active_flag: bool
+    tracking_rating: int
+    total_recos: int
+    current_month_recos: int
+    previous_month_recos: int
+
+    @classmethod
+    def from_response_dict(cls, response_dict: dict[str, Any]) -> Self:
+        """Construct from a VWS API response dict."""
+        return cls(
+            status=TargetStatuses(value=response_dict["status"]),
+            database_name=response_dict["database_name"],
+            target_name=response_dict["target_name"],
+            upload_date=datetime.date.fromisoformat(
+                response_dict["upload_date"]
+            ),
+            active_flag=bool(response_dict["active_flag"]),
+            tracking_rating=int(response_dict["tracking_rating"]),
+            total_recos=int(response_dict["total_recos"]),
+            current_month_recos=int(response_dict["current_month_recos"]),
+            previous_month_recos=int(response_dict["previous_month_recos"]),
+        )
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+@dataclass(frozen=True, kw_only=True)
+class TargetRecord:
+    """A target record.
+
+    See
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.
+    """
+
+    target_id: str
+    active_flag: bool
+    name: str
+    width: float
+    tracking_rating: int
+    reco_rating: str
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class TargetData:
+    """The target data optionally included with a query match."""
+
+    name: str
+    application_metadata: str | None
+    target_timestamp: datetime.datetime
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class QueryResult:
+    """One query match result.
+
+    See
+    https://developer.vuforia.com/library/web-api/vuforia-query-web-api.
+    """
+
+    target_id: str
+    target_data: TargetData | None
+
+    @classmethod
+    def from_response_dict(cls, response_dict: dict[str, Any]) -> Self:
+        """Construct from a VWS API query result item dict."""
+        target_data: TargetData | None = None
+        if "target_data" in response_dict:
+            target_data_dict = response_dict["target_data"]
+            target_timestamp = datetime.datetime.fromtimestamp(
+                timestamp=target_data_dict["target_timestamp"],
+                tz=datetime.UTC,
+            )
+            target_data = TargetData(
+                name=target_data_dict["name"],
+                application_metadata=target_data_dict["application_metadata"],
+                target_timestamp=target_timestamp,
+            )
+        return cls(
+            target_id=response_dict["target_id"],
+            target_data=target_data,
+        )
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class TargetStatusAndRecord:
+    """The target status and a target record.
+
+    See
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.
+    """
+
+    status: TargetStatuses
+    target_record: TargetRecord
+
+    @classmethod
+    def from_response_dict(cls, response_dict: dict[str, Any]) -> Self:
+        """Construct from a VWS API response dict."""
+        status = TargetStatuses(value=response_dict["status"])
+        target_record_dict = dict(response_dict["target_record"])
+        target_record = TargetRecord(
+            target_id=target_record_dict["target_id"],
+            active_flag=bool(target_record_dict["active_flag"]),
+            name=target_record_dict["name"],
+            width=float(target_record_dict["width"]),
+            tracking_rating=int(target_record_dict["tracking_rating"]),
+            reco_rating=target_record_dict["reco_rating"],
+        )
+        return cls(status=status, target_record=target_record)
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class RecoCountsReportRequest:
+    """A requested database reco counts report.
+
+    See
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api.
+    """
+
+    transaction_id: str
+    presigned_url: str
+    """The URL to download the report from.
+
+    Real Vuforia's URLs expire just under seven days after the report is
+    requested.
+    """
+
+    @classmethod
+    def from_response_dict(cls, response_dict: dict[str, Any]) -> Self:
+        """Construct from a VWS API response dict."""
+        return cls(
+            transaction_id=response_dict["transaction_id"],
+            presigned_url=response_dict["presigned_url"],
+        )
+
+
+@beartype
+@unique
+class ModelTargetDatasetStatuses(Enum):
+    """Constants representing Model Target dataset generation statuses.
+
+    See the 'status' field of the dataset status response at
+    https://developer.vuforia.com/library/vuforia-engine/web-api/model-target-web-api/.
+    """
+
+    PROCESSING = "processing"
+    DONE = "done"
+    FAILED = "failed"
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class ModelTargetGenerationDetail:
+    """One detail of a Model Target dataset generation warning."""
+
+    code: str
+    message: str
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class ModelTargetGenerationError:
+    """The reason a Model Target dataset failed to generate."""
+
+    code: str
+    message: str
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class ModelTargetGenerationWarning:
+    """A warning about a generated Model Target dataset.
+
+    A dataset with a warning is generated, and can be downloaded.
+    """
+
+    code: str
+    message: str
+    target: str
+    details: Sequence[ModelTargetGenerationDetail]
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class ModelTargetDatasetStatusReport:
+    """The status of a Model Target dataset.
+
+    See
+    https://developer.vuforia.com/library/vuforia-engine/web-api/model-target-web-api/.
+    """
+
+    status: ModelTargetDatasetStatuses
+    dataset_uuid: str
+    created_at: datetime.datetime
+    eta: datetime.datetime | None
+    """When Vuforia expects to finish generating the dataset.
+
+    This is given only while the dataset is processing.
+    """
+
+    completed_at: datetime.datetime | None
+    """When Vuforia finished generating the dataset.
+
+    This is given only once the dataset is no longer processing.
+    """
+
+    error: ModelTargetGenerationError | None
+    """Why the dataset failed to generate.
+
+    This is given only for a failed dataset.
+    """
+
+    warning: ModelTargetGenerationWarning | None
+    """A warning about the generated dataset.
+
+    This is given only for a generated dataset which has a warning.
+    """
+
+    @classmethod
+    def from_response_dict(cls, response_dict: dict[str, Any]) -> Self:
+        """Construct from a Model Target Web API response dict."""
+        error: ModelTargetGenerationError | None = None
+        if "error" in response_dict:
+            error_dict = dict(response_dict["error"])
+            error = ModelTargetGenerationError(
+                code=error_dict["code"],
+                message=error_dict["message"],
+            )
+
+        warning: ModelTargetGenerationWarning | None = None
+        if "warning" in response_dict:
+            warning_dict = dict(response_dict["warning"])
+            warning = ModelTargetGenerationWarning(
+                code=warning_dict["code"],
+                message=warning_dict["message"],
+                target=warning_dict["target"],
+                details=[
+                    ModelTargetGenerationDetail(
+                        code=detail["code"],
+                        message=detail["message"],
+                    )
+                    for detail in warning_dict["details"]
+                ],
+            )
+
+        eta: datetime.datetime | None = None
+        if "eta" in response_dict:
+            eta = datetime.datetime.fromisoformat(response_dict["eta"])
+
+        completed_at: datetime.datetime | None = None
+        if "completedAt" in response_dict:
+            completed_at = datetime.datetime.fromisoformat(
+                response_dict["completedAt"],
+            )
+
+        return cls(
+            status=ModelTargetDatasetStatuses(value=response_dict["status"]),
+            dataset_uuid=response_dict["uuid"],
+            created_at=datetime.datetime.fromisoformat(
+                response_dict["createdAt"],
+            ),
+            eta=eta,
+            completed_at=completed_at,
+            error=error,
+            warning=warning,
+        )
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class RecoCount:
+    """The number of recognitions of one target in a reco counts
+    report.
+    """
+
+    target_id: str
+    reco_count: int
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class RecoCountsReport:
+    """A downloaded database reco counts report.
+
+    A report for a month with no recognitions has no ``reco_counts``.
+    """
+
+    reco_counts: Sequence[RecoCount]
+    raw_csv: bytes
+    """The downloaded CSV, before it was parsed.
+
+    Vuforia does not document the format of the report, so it may include
+    columns which ``reco_counts`` does not expose.
+    """
+
+    @classmethod
+    def from_csv(cls, csv_bytes: bytes) -> Self:
+        """Construct from the CSV content of a downloaded report."""
+        text = csv_bytes.decode(encoding="utf-8")
+        reader = csv.DictReader(f=io.StringIO(initial_value=text, newline=""))
+        reco_counts = [
+            RecoCount(
+                target_id=row["target_id"],
+                reco_count=int(row["reco_count"]),
+            )
+            for row in reader
+        ]
+        return cls(reco_counts=reco_counts, raw_csv=csv_bytes)

vws/response.py

@@ -0,0 +1,19 @@
+"""Responses for requests to VWS and VWQ."""
+
+from dataclasses import dataclass
+
+from beartype import beartype
+
+
+@dataclass(frozen=True, kw_only=True)
+@beartype
+class Response:
+    """A response from a request."""
+
+    text: str
+    url: str
+    status_code: int
+    headers: dict[str, str]
+    request_body: bytes | str | None
+    tell_position: int
+    content: bytes