vws-python 2026.8.14__py3-none-any.whl

vws/async_model_target_service.py

@@ -0,0 +1,381 @@
+"""Async interface to the Vuforia Model Target Web API."""
+
+import asyncio
+import time
+from collections.abc import Sequence  # noqa: TC003
+from http import HTTPMethod
+from typing import Self
+
+from beartype import BeartypeConf, beartype
+
+from vws._model_targets import (
+    JSON_CONTENT_TYPE,
+    OAUTH2_TOKEN_BODY,
+    OAUTH2_TOKEN_PATH,
+    access_token_from_response,
+    dataset_collection_path,
+    dataset_download_path,
+    dataset_path,
+    dataset_request_body,
+    dataset_status_path,
+    dataset_uuid_from_response,
+    oauth2_token_headers,
+    raise_for_error,
+    status_report_from_response,
+)
+from vws.exceptions.model_target_exceptions import (
+    ModelTargetDatasetTimeoutError,
+)
+from vws.model_target_datasets import (  # noqa: TC001
+    ModelTargetDatasetType,
+    ModelTargetModel,
+)
+from vws.reports import (
+    ModelTargetDatasetStatuses,
+    ModelTargetDatasetStatusReport,
+)
+from vws.response import Response  # noqa: TC001
+from vws.transports import AsyncHTTPXTransport, AsyncTransport
+
+_TOKEN_EXPIRY_MARGIN_SECONDS = 60.0
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class AsyncModelTargetService:
+    """An async interface to the Vuforia Model Target Web API."""
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        base_vws_url: str = "https://vws.vuforia.com",
+        request_timeout_seconds: float | tuple[float, float] = 30.0,
+        transport: AsyncTransport | None = None,
+    ) -> None:
+        """
+        Args:
+            client_id: A Model Target Web API OAuth2 client
+                ID.
+            client_secret: A Model Target Web API OAuth2
+                client secret.
+            base_vws_url: The base URL for the VWS API, which
+                also serves the Model Target Web 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 async HTTP transport to use for
+                requests. Defaults to
+                ``AsyncHTTPXTransport()``.
+        """
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._base_vws_url = base_vws_url
+        self._request_timeout_seconds = request_timeout_seconds
+        self._transport = (
+            transport if transport is not None else AsyncHTTPXTransport()
+        )
+        self._access_token: str | None = None
+        self._access_token_expiry_time = 0.0
+
+    async def aclose(self) -> None:
+        """Close the underlying transport if it supports closing."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        """Exit the async context manager and close the transport."""
+        await self.aclose()
+
+    async def get_access_token(self) -> str:
+        """Get an OAuth2 access token for the Model Target Web API.
+
+        A token is requested only when the client has no token which is
+        still valid, so this can be called before each request.
+
+        Returns:
+            A bearer token.
+
+        Raises:
+            ~vws.exceptions.model_target_exceptions.ModelTargetOAuth2Error:
+                Vuforia did not give an access token. For example, the
+                given client ID and client secret may not match a set of
+                Model Target Web API credentials.
+        """
+        request_time = time.monotonic()
+        if (
+            self._access_token is not None
+            and request_time < self._access_token_expiry_time
+        ):
+            return self._access_token
+
+        response = await self._transport(
+            method=HTTPMethod.POST,
+            url=self._base_vws_url.rstrip("/") + OAUTH2_TOKEN_PATH,
+            headers=oauth2_token_headers(
+                client_id=self._client_id,
+                client_secret=self._client_secret,
+            ),
+            data=OAUTH2_TOKEN_BODY,
+            request_timeout=self._request_timeout_seconds,
+        )
+
+        access_token, expires_in_seconds = access_token_from_response(
+            response=response,
+        )
+        self._access_token = access_token
+        self._access_token_expiry_time = (
+            request_time + expires_in_seconds - _TOKEN_EXPIRY_MARGIN_SECONDS
+        )
+        return access_token
+
+    async def make_request(
+        self,
+        *,
+        method: str,
+        data: bytes,
+        request_path: str,
+        extra_headers: dict[str, str] | None = None,
+    ) -> Response:
+        """Make an authenticated request to the Model Target Web API.
+
+        Args:
+            method: The HTTP method which will be used in
+                the request.
+            data: The request body which will be used in the
+                request.
+            request_path: The path to the endpoint which
+                will be used in the request.
+            extra_headers: Additional headers to include in
+                the request.
+
+        Returns:
+            The response to the request.
+
+        Raises:
+            ~vws.exceptions.model_target_exceptions.ModelTargetError:
+                Vuforia returned an error.
+            ~vws.exceptions.custom_exceptions.ServerError:
+                There is an error with Vuforia's servers.
+            ~vws.exceptions.vws_exceptions.TooManyRequestsError:
+                Vuforia is rate limiting access.
+        """
+        access_token = await self.get_access_token()
+        headers = {
+            "Authorization": f"Bearer {access_token}",
+            **(extra_headers or {}),
+        }
+
+        response = await self._transport(
+            method=method,
+            url=self._base_vws_url.rstrip("/") + request_path,
+            headers=headers,
+            data=data,
+            request_timeout=self._request_timeout_seconds,
+        )
+
+        raise_for_error(response=response)
+        return response
+
+    async def create_dataset(
+        self,
+        *,
+        name: str,
+        target_sdk: str,
+        models: Sequence[ModelTargetModel],
+        dataset_type: ModelTargetDatasetType,
+    ) -> str:
+        """Start generating a Model Target dataset.
+
+        Vuforia generates the dataset in the background, so it is not
+        available to download immediately. Use
+        :meth:`wait_for_dataset_generated` to wait for it.
+
+        Args:
+            name: The name of the dataset.
+            target_sdk: The Vuforia Engine version to generate the dataset
+                for.
+            models: The models to generate the dataset from. A standard
+                dataset takes exactly one model.
+            dataset_type: Whether to create a standard or an advanced
+                dataset.
+
+        Returns:
+            The UUID of the new dataset.
+
+        Raises:
+            ~vws.exceptions.model_target_exceptions.ModelTargetAuthenticationError:
+                The request was not authenticated.
+            ~vws.exceptions.model_target_exceptions.ModelTargetValidationError:
+                Vuforia rejected the request. For example, a model may
+                give neither a CAD data URL nor a CAD data blob.
+            ~vws.exceptions.model_target_exceptions.ModelTargetOAuth2Error:
+                Vuforia did not give an access token.
+        """
+        response = await self.make_request(
+            method=HTTPMethod.POST,
+            data=dataset_request_body(
+                name=name,
+                target_sdk=target_sdk,
+                models=models,
+            ),
+            request_path=dataset_collection_path(dataset_type=dataset_type),
+            extra_headers={"Content-Type": JSON_CONTENT_TYPE},
+        )
+
+        return dataset_uuid_from_response(response=response)
+
+    async def get_dataset_status(
+        self,
+        *,
+        dataset_uuid: str,
+        dataset_type: ModelTargetDatasetType,
+    ) -> ModelTargetDatasetStatusReport:
+        """Get the status of a Model Target dataset.
+
+        Args:
+            dataset_uuid: The UUID of the dataset, as given by
+                :meth:`create_dataset`.
+            dataset_type: The kind of dataset to get the status of.
+
+        Returns:
+            The status of the dataset.
+
+        Raises:
+            ~vws.exceptions.model_target_exceptions.ModelTargetAuthenticationError:
+                The request was not authenticated.
+            ~vws.exceptions.model_target_exceptions.UnknownModelTargetDatasetError:
+                No dataset of the given type matches the given UUID.
+            ~vws.exceptions.model_target_exceptions.ModelTargetOAuth2Error:
+                Vuforia did not give an access token.
+        """
+        response = await self.make_request(
+            method=HTTPMethod.GET,
+            data=b"",
+            request_path=dataset_status_path(
+                dataset_type=dataset_type,
+                dataset_uuid=dataset_uuid,
+            ),
+        )
+
+        return status_report_from_response(response=response)
+
+    async def wait_for_dataset_generated(
+        self,
+        *,
+        dataset_uuid: str,
+        dataset_type: ModelTargetDatasetType,
+        seconds_between_requests: float = 0.2,
+        timeout_seconds: float = 60 * 5,
+    ) -> ModelTargetDatasetStatusReport:
+        """Wait for Vuforia to finish generating a Model Target dataset.
+
+        A dataset which failed to generate is also finished, so the
+        returned report may have a
+        :attr:`~.ModelTargetDatasetStatusReport.status` of
+        ``FAILED``.
+
+        Args:
+            dataset_uuid: The UUID of the dataset, as given by
+                :meth:`create_dataset`.
+            dataset_type: The kind of dataset to wait for.
+            seconds_between_requests: The number of seconds to wait between
+                requests made while polling the dataset's status.
+            timeout_seconds: The maximum number of seconds to wait for the
+                dataset to be generated.
+
+        Returns:
+            The status of the dataset once it is no longer processing.
+
+        Raises:
+            ~vws.exceptions.model_target_exceptions.ModelTargetDatasetTimeoutError:
+                The dataset was not generated within ``timeout_seconds``
+                seconds.
+            ~vws.exceptions.model_target_exceptions.UnknownModelTargetDatasetError:
+                No dataset of the given type matches the given UUID.
+        """
+        start_time = time.monotonic()
+        while True:
+            report = await self.get_dataset_status(
+                dataset_uuid=dataset_uuid,
+                dataset_type=dataset_type,
+            )
+            if report.status != ModelTargetDatasetStatuses.PROCESSING:
+                return report
+
+            elapsed_time = time.monotonic() - start_time
+            if elapsed_time > timeout_seconds:
+                raise ModelTargetDatasetTimeoutError
+
+            await asyncio.sleep(delay=seconds_between_requests)
+
+    async def download_dataset(
+        self,
+        *,
+        dataset_uuid: str,
+        dataset_type: ModelTargetDatasetType,
+    ) -> bytes:
+        """Download a generated Model Target dataset.
+
+        Args:
+            dataset_uuid: The UUID of the dataset, as given by
+                :meth:`create_dataset`.
+            dataset_type: The kind of dataset to download.
+
+        Returns:
+            The dataset, as the bytes of a zip file.
+
+        Raises:
+            ~vws.exceptions.model_target_exceptions.ModelTargetAuthenticationError:
+                The request was not authenticated.
+            ~vws.exceptions.model_target_exceptions.UnknownModelTargetDatasetError:
+                No dataset of the given type matches the given UUID.
+            ~vws.exceptions.model_target_exceptions.ModelTargetDatasetNotDoneError:
+                Vuforia has not generated the dataset.
+            ~vws.exceptions.model_target_exceptions.ModelTargetOAuth2Error:
+                Vuforia did not give an access token.
+        """
+        response = await self.make_request(
+            method=HTTPMethod.GET,
+            data=b"",
+            request_path=dataset_download_path(
+                dataset_type=dataset_type,
+                dataset_uuid=dataset_uuid,
+            ),
+        )
+
+        return response.content
+
+    async def delete_dataset(
+        self,
+        *,
+        dataset_uuid: str,
+        dataset_type: ModelTargetDatasetType,
+    ) -> None:
+        """Delete a Model Target dataset.
+
+        Args:
+            dataset_uuid: The UUID of the dataset, as given by
+                :meth:`create_dataset`.
+            dataset_type: The kind of dataset to delete.
+
+        Raises:
+            ~vws.exceptions.model_target_exceptions.ModelTargetAuthenticationError:
+                The request was not authenticated.
+            ~vws.exceptions.model_target_exceptions.UnknownModelTargetDatasetError:
+                No dataset of the given type matches the given UUID.
+            ~vws.exceptions.model_target_exceptions.ModelTargetOAuth2Error:
+                Vuforia did not give an access token.
+        """
+        await self.make_request(
+            method=HTTPMethod.DELETE,
+            data=b"",
+            request_path=dataset_path(
+                dataset_type=dataset_type,
+                dataset_uuid=dataset_uuid,
+            ),
+        )

vws/async_query.py

@@ -0,0 +1,224 @@
+"""Async tools for interacting with the Vuforia Cloud Recognition
+Web APIs.
+"""
+
+import json
+from http import HTTPMethod, HTTPStatus
+from typing import Any, Self
+
+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 AsyncHTTPXTransport, AsyncTransport
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class AsyncCloudRecoService:
+    """An async 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: AsyncTransport | 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 async HTTP transport to use for
+                requests. Defaults to
+                ``AsyncHTTPXTransport()``.
+        """
+        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 AsyncHTTPXTransport()
+        )
+
+    async def aclose(self) -> None:
+        """Close the underlying transport if it supports closing."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        """Exit the async context manager and close the transport."""
+        await self.aclose()
+
+    async 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 = await 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
+        ]