vws-python 2026.2.24__tar.gz → 2026.2.25__tar.gz

{vws_python-2026.2.24 → vws_python-2026.2.25}/CHANGELOG.rst

@@ -4,6 +4,10 @@ Changelog
 Next
 ----
 
+2026.02.25
+----------
+
+
 2026.02.24
 ----------
 

{vws_python-2026.2.24/src/vws_python.egg-info → vws_python-2026.2.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vws-python
-Version: 2026.2.24
+Version: 2026.2.25
 Summary: Interact with the Vuforia Web Services (VWS) API.
 Author-email: Adam Dangoor <adamdangoor@gmail.com>
 License-Expression: MIT
@@ -44,6 +44,7 @@ Requires-Dist: pyrefly==0.54.0; extra == "dev"
 Requires-Dist: pyright==1.1.408; extra == "dev"
 Requires-Dist: pyroma==5.0.1; extra == "dev"
 Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
 Requires-Dist: pytest-cov==7.0.0; extra == "dev"
 Requires-Dist: pyyaml==6.0.3; extra == "dev"
 Requires-Dist: ruff==0.15.2; extra == "dev"

{vws_python-2026.2.24 → vws_python-2026.2.25}/docs/source/api-reference.rst

@@ -5,6 +5,18 @@ API Reference
    :undoc-members:
    :members:
 
+.. automodule:: vws.async_vws
+   :undoc-members:
+   :members:
+
+.. automodule:: vws.async_query
+   :undoc-members:
+   :members:
+
+.. automodule:: vws.async_vumark_service
+   :undoc-members:
+   :members:
+
 .. automodule:: vws.reports
    :undoc-members:
    :members:

{vws_python-2026.2.24 → vws_python-2026.2.25}/pyproject.toml

@@ -60,6 +60,7 @@ optional-dependencies.dev = [
     "pyright==1.1.408",
     "pyroma==5.0.1",
     "pytest==9.0.2",
+    "pytest-asyncio==1.3.0",
     "pytest-cov==7.0.0",
     "pyyaml==6.0.3",
     "ruff==0.15.2",
@@ -359,6 +360,7 @@ ignore_path = [
 # but Vulture does not enable this.
 ignore_names = [
     # Public API classes imported by users from vws.transports
+    "AsyncHTTPXTransport",
     "HTTPXTransport",
     # pytest configuration
     "pytest_collect_file",

{vws_python-2026.2.24 → vws_python-2026.2.25}/spelling_private_dict.txt

@@ -27,6 +27,8 @@ admin
 api
 args
 ascii
+async
+asyncio
 beartype
 bool
 boolean

{vws_python-2026.2.24 → vws_python-2026.2.25}/src/vws/__init__.py

@@ -1,11 +1,17 @@
 """A library for Vuforia Web Services."""
 
+from .async_query import AsyncCloudRecoService
+from .async_vumark_service import AsyncVuMarkService
+from .async_vws import AsyncVWS
 from .query import CloudRecoService
 from .vumark_service import VuMarkService
 from .vws import VWS
 
 __all__ = [
     "VWS",
+    "AsyncCloudRecoService",
+    "AsyncVWS",
+    "AsyncVuMarkService",
     "CloudRecoService",
     "VuMarkService",
 ]

vws_python-2026.2.25/src/vws/_async_vws_request.py

@@ -0,0 +1,77 @@
+"""Internal helper for making authenticated async requests to the
+Vuforia Target API.
+"""
+
+from beartype import BeartypeConf, beartype
+from vws_auth_tools import authorization_header, rfc_1123_date
+
+from vws.response import Response
+from vws.transports import AsyncTransport
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+async def async_target_api_request(
+    *,
+    content_type: str,
+    server_access_key: str,
+    server_secret_key: str,
+    method: str,
+    data: bytes,
+    request_path: str,
+    base_vws_url: str,
+    request_timeout_seconds: float | tuple[float, float],
+    extra_headers: dict[str, str],
+    transport: AsyncTransport,
+) -> Response:
+    """Make an async request to the Vuforia Target API.
+
+    Args:
+        content_type: The content type of the request.
+        server_access_key: A VWS server access key.
+        server_secret_key: A VWS server secret key.
+        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.
+        base_vws_url: The base URL for the VWS API.
+        request_timeout_seconds: The timeout for the request.
+            This can be a float to set both the connect and
+            read timeouts, or a (connect, read) tuple.
+        extra_headers: Additional headers to include in the
+            request.
+        transport: The async HTTP transport to use for the
+            request.
+
+    Returns:
+        The response to the request.
+    """
+    date_string = rfc_1123_date()
+
+    signature_string = authorization_header(
+        access_key=server_access_key,
+        secret_key=server_secret_key,
+        method=method,
+        content=data,
+        content_type=content_type,
+        date=date_string,
+        request_path=request_path,
+    )
+
+    headers = {
+        "Authorization": signature_string,
+        "Date": date_string,
+        "Content-Type": content_type,
+        **extra_headers,
+    }
+
+    url = base_vws_url.rstrip("/") + request_path
+
+    return await transport(
+        method=method,
+        url=url,
+        headers=headers,
+        data=data,
+        request_timeout=request_timeout_seconds,
+    )

vws_python-2026.2.25/src/vws/_image_utils.py

@@ -0,0 +1,18 @@
+"""Image utility functions shared across VWS modules."""
+
+import io
+from typing import BinaryIO
+
+from beartype import beartype
+
+ImageType = io.BytesIO | BinaryIO
+
+
+@beartype
+def get_image_data(image: ImageType) -> bytes:
+    """Get the data of an image file."""
+    original_tell = image.tell()
+    image.seek(0)
+    image_data = image.read()
+    image.seek(original_tell)
+    return image_data

{vws_python-2026.2.24 → vws_python-2026.2.25}/src/vws/_vws_request.py

@@ -72,5 +72,5 @@ def target_api_request(
         url=url,
         headers=headers,
         data=data,
-        timeout=request_timeout_seconds,
+        request_timeout=request_timeout_seconds,
     )

vws_python-2026.2.25/src/vws/async_query.py

@@ -0,0 +1,226 @@
+"""Async tools for interacting with the Vuforia Cloud Recognition
+Web APIs.
+"""
+
+import datetime
+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.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, TargetData
+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 or AsyncHTTPXTransport()
+
+    async def aclose(self) -> None:
+        """Close the underlying transport if it supports closing."""
+        close = getattr(self._transport, "aclose", None)
+        if close is not None:
+            await close()
+
+    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.
+
+        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)
+
+        result_code = json.loads(s=response.text)["result_code"]
+        if result_code != "Success":
+            exception = {
+                "AuthenticationFailure": (AuthenticationFailureError),
+                "BadImage": BadImageError,
+                "InactiveProject": InactiveProjectError,
+                "RequestTimeTooSkewed": (RequestTimeTooSkewedError),
+            }[result_code]
+            raise exception(response=response)
+
+        result: list[QueryResult] = []
+        result_list = list(
+            json.loads(s=response.text)["results"],
+        )
+        for item in result_list:
+            target_data: TargetData | None = None
+            if "target_data" in item:
+                target_data_dict = item["target_data"]
+                metadata = target_data_dict["application_metadata"]
+                timestamp_string = target_data_dict["target_timestamp"]
+                target_timestamp = datetime.datetime.fromtimestamp(
+                    timestamp=timestamp_string,
+                    tz=datetime.UTC,
+                )
+                target_data = TargetData(
+                    name=target_data_dict["name"],
+                    application_metadata=metadata,
+                    target_timestamp=target_timestamp,
+                )
+
+            query_result = QueryResult(
+                target_id=item["target_id"],
+                target_data=target_data,
+            )
+
+            result.append(query_result)
+        return result

vws_python-2026.2.25/src/vws/async_vumark_service.py

@@ -0,0 +1,170 @@
+"""Async interface to the Vuforia VuMark Generation Web API."""
+
+import json
+from http import HTTPMethod, HTTPStatus
+from typing import Self
+
+from beartype import BeartypeConf, beartype
+
+from vws._async_vws_request import async_target_api_request
+from vws.exceptions.custom_exceptions import ServerError
+from vws.exceptions.vws_exceptions import (
+    AuthenticationFailureError,
+    BadRequestError,
+    DateRangeError,
+    FailError,
+    InvalidAcceptHeaderError,
+    InvalidInstanceIdError,
+    InvalidTargetTypeError,
+    RequestTimeTooSkewedError,
+    TargetStatusNotSuccessError,
+    TooManyRequestsError,
+    UnknownTargetError,
+)
+from vws.transports import AsyncHTTPXTransport, AsyncTransport
+from vws.vumark_accept import VuMarkAccept
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class AsyncVuMarkService:
+    """An async interface to the Vuforia VuMark Generation Web
+    API.
+    """
+
+    def __init__(
+        self,
+        *,
+        server_access_key: str,
+        server_secret_key: str,
+        base_vws_url: str = "https://vws.vuforia.com",
+        request_timeout_seconds: float | tuple[float, float] = 30.0,
+        transport: AsyncTransport | None = None,
+    ) -> None:
+        """
+        Args:
+            server_access_key: A VWS server access key.
+            server_secret_key: A VWS server secret key.
+            base_vws_url: The base URL for the VWS 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._server_access_key = server_access_key
+        self._server_secret_key = server_secret_key
+        self._base_vws_url = base_vws_url
+        self._request_timeout_seconds = request_timeout_seconds
+        self._transport = transport or AsyncHTTPXTransport()
+
+    async def aclose(self) -> None:
+        """Close the underlying transport if it supports closing."""
+        close = getattr(self._transport, "aclose", None)
+        if close is not None:
+            await close()
+
+    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 generate_vumark_instance(
+        self,
+        *,
+        target_id: str,
+        instance_id: str,
+        accept: VuMarkAccept,
+    ) -> bytes:
+        """Generate a VuMark instance image.
+
+        See
+        https://developer.vuforia.com/library/vuforia-engine/web-api/vumark-generation-web-api/
+        for parameter details.
+
+        Args:
+            target_id: The ID of the VuMark target.
+            instance_id: The instance ID to encode in the
+                VuMark.
+            accept: The image format to return.
+
+        Returns:
+            The VuMark instance image bytes.
+
+        Raises:
+            ~vws.exceptions.vws_exceptions.AuthenticationFailureError: The
+                secret key is not correct.
+            ~vws.exceptions.vws_exceptions.FailError: There was an error with
+                the request. For example, the given access key does not match a
+                known database.
+            ~vws.exceptions.vws_exceptions.InvalidAcceptHeaderError: The
+                Accept header value is not supported.
+            ~vws.exceptions.vws_exceptions.InvalidInstanceIdError: The
+                instance ID is invalid. For example, it may be empty.
+            ~vws.exceptions.vws_exceptions.InvalidTargetTypeError: The target
+                is not a VuMark template target.
+            ~vws.exceptions.vws_exceptions.RequestTimeTooSkewedError: There is
+                an error with the time sent to Vuforia.
+            ~vws.exceptions.vws_exceptions.TargetStatusNotSuccessError: The
+                target is not in the success state.
+            ~vws.exceptions.vws_exceptions.UnknownTargetError: The given target
+                ID does not match a target in the database.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.vws_exceptions.TooManyRequestsError: Vuforia is
+                rate limiting access.
+        """
+        request_path = f"/targets/{target_id}/instances"
+        content_type = "application/json"
+        request_data = json.dumps(
+            obj={"instance_id": instance_id},
+        ).encode(encoding="utf-8")
+
+        response = await async_target_api_request(
+            content_type=content_type,
+            server_access_key=self._server_access_key,
+            server_secret_key=self._server_secret_key,
+            method=HTTPMethod.POST,
+            data=request_data,
+            request_path=request_path,
+            base_vws_url=self._base_vws_url,
+            request_timeout_seconds=(self._request_timeout_seconds),
+            extra_headers={"Accept": accept},
+            transport=self._transport,
+        )
+
+        if (
+            response.status_code == HTTPStatus.TOO_MANY_REQUESTS
+        ):  # pragma: no cover
+            # The Vuforia API returns a 429 response with no
+            # JSON body.
+            raise TooManyRequestsError(response=response)
+
+        if (
+            response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR
+        ):  # pragma: no cover
+            raise ServerError(response=response)
+
+        if response.status_code == HTTPStatus.OK:
+            return response.content
+
+        result_code = json.loads(s=response.text)["result_code"]
+
+        exception = {
+            "AuthenticationFailure": (AuthenticationFailureError),
+            "BadRequest": BadRequestError,
+            "DateRangeError": DateRangeError,
+            "Fail": FailError,
+            "InvalidAcceptHeader": InvalidAcceptHeaderError,
+            "InvalidInstanceId": InvalidInstanceIdError,
+            "InvalidTargetType": InvalidTargetTypeError,
+            "RequestTimeTooSkewed": RequestTimeTooSkewedError,
+            "TargetStatusNotSuccess": (TargetStatusNotSuccessError),
+            "UnknownTarget": UnknownTargetError,
+        }[result_code]
+
+        raise exception(response=response)