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

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

@@ -4,6 +4,14 @@ Changelog
 Next
 ----
 
+2026.02.25
+----------
+
+
+2026.02.24
+----------
+
+
 2026.02.23
 ----------
 

{vws_python-2026.2.23/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.23
+Version: 2026.2.25
 Summary: Interact with the Vuforia Web Services (VWS) API.
 Author-email: Adam Dangoor <adamdangoor@gmail.com>
 License-Expression: MIT
@@ -18,6 +18,7 @@ Requires-Python: >=3.13
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: beartype>=0.22.9
+Requires-Dist: httpx>=0.28.0
 Requires-Dist: requests>=2.32.3
 Requires-Dist: urllib3>=2.2.3
 Requires-Dist: vws-auth-tools>=2024.7.12
@@ -36,16 +37,17 @@ Requires-Dist: prek==0.3.3; extra == "dev"
 Requires-Dist: pydocstringformatter==0.7.5; extra == "dev"
 Requires-Dist: pydocstyle==6.3; extra == "dev"
 Requires-Dist: pygments==2.19.2; extra == "dev"
-Requires-Dist: pylint[spelling]==4.0.4; extra == "dev"
+Requires-Dist: pylint[spelling]==4.0.5; extra == "dev"
 Requires-Dist: pylint-per-file-ignores==3.2.0; extra == "dev"
-Requires-Dist: pyproject-fmt==2.16.1; extra == "dev"
-Requires-Dist: pyrefly==0.53.0; extra == "dev"
+Requires-Dist: pyproject-fmt==2.16.2; extra == "dev"
+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.1; extra == "dev"
+Requires-Dist: ruff==0.15.2; extra == "dev"
 Requires-Dist: shellcheck-py==0.11.0.1; extra == "dev"
 Requires-Dist: shfmt-py==3.12.0.2; extra == "dev"
 Requires-Dist: sphinx==9.1.0; extra == "dev"
@@ -57,10 +59,10 @@ Requires-Dist: sphinxcontrib-spelling==8.0.2; extra == "dev"
 Requires-Dist: sybil==9.3.0; extra == "dev"
 Requires-Dist: torch>=2.5.1; extra == "dev"
 Requires-Dist: torchvision>=0.20.1; extra == "dev"
-Requires-Dist: ty==0.0.17; extra == "dev"
+Requires-Dist: ty==0.0.18; extra == "dev"
 Requires-Dist: types-requests==2.32.4.20260107; extra == "dev"
 Requires-Dist: vulture==2.14; extra == "dev"
-Requires-Dist: vws-python-mock==2026.2.22.2; extra == "dev"
+Requires-Dist: vws-python-mock==2026.2.22.3; extra == "dev"
 Requires-Dist: vws-test-fixtures==2023.3.5; extra == "dev"
 Requires-Dist: yamlfix==1.19.1; extra == "dev"
 Requires-Dist: zizmor==1.22.0; extra == "dev"

{vws_python-2026.2.23 → vws_python-2026.2.25}/conftest.py

@@ -28,6 +28,7 @@ def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
 
 @pytest.fixture(name="make_image_file")
 def fixture_make_image_file(
+    *,
     high_quality_image: io.BytesIO,
 ) -> Generator[None]:
     """Make an image file available in the test directory.
@@ -43,6 +44,7 @@ def fixture_make_image_file(
 
 @pytest.fixture(name="mock_vws")
 def fixture_mock_vws(
+    *,
     monkeypatch: pytest.MonkeyPatch,
 ) -> Generator[None]:
     """Yield a mock VWS.

{vws_python-2026.2.23 → 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:
@@ -20,3 +32,7 @@ API Reference
 .. automodule:: vws.response
    :undoc-members:
    :members:
+
+.. automodule:: vws.transports
+   :undoc-members:
+   :members:

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

@@ -33,6 +33,7 @@ dynamic = [
 ]
 dependencies = [
     "beartype>=0.22.9",
+    "httpx>=0.28.0",
     "requests>=2.32.3",
     "urllib3>=2.2.3",
     "vws-auth-tools>=2024.7.12",
@@ -52,16 +53,17 @@ optional-dependencies.dev = [
     "pydocstringformatter==0.7.5",
     "pydocstyle==6.3",
     "pygments==2.19.2",
-    "pylint[spelling]==4.0.4",
+    "pylint[spelling]==4.0.5",
     "pylint-per-file-ignores==3.2.0",
-    "pyproject-fmt==2.16.1",
-    "pyrefly==0.53.0",
+    "pyproject-fmt==2.16.2",
+    "pyrefly==0.54.0",
     "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.1",
+    "ruff==0.15.2",
     # We add shellcheck-py not only for shell scripts and shell code blocks,
     # but also because having it installed means that ``actionlint-py`` will
     # use it to lint shell commands in GitHub workflow files.
@@ -79,10 +81,10 @@ optional-dependencies.dev = [
     # See: https://vws-python.github.io/vws-python-mock/installation.html#faster-installation
     "torch>=2.5.1",
     "torchvision>=0.20.1",
-    "ty==0.0.17",
+    "ty==0.0.18",
     "types-requests==2.32.4.20260107",
     "vulture==2.14",
-    "vws-python-mock==2026.2.22.2",
+    "vws-python-mock==2026.2.22.3",
     "vws-test-fixtures==2023.3.5",
     "yamlfix==1.19.1",
     "zizmor==1.22.0",
@@ -357,6 +359,9 @@ ignore_path = [
 # Ideally we would limit the paths to the source code where we want to ignore names,
 # but Vulture does not enable this.
 ignore_names = [
+    # Public API classes imported by users from vws.transports
+    "AsyncHTTPXTransport",
+    "HTTPXTransport",
     # pytest configuration
     "pytest_collect_file",
     "pytest_collection_modifyitems",

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

@@ -27,6 +27,8 @@ admin
 api
 args
 ascii
+async
+asyncio
 beartype
 bool
 boolean
@@ -54,6 +56,7 @@ hmac
 html
 http
 https
+httpx
 iff
 io
 issuecomment

{vws_python-2026.2.23 → 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.23 → vws_python-2026.2.25}/src/vws/_vws_request.py

@@ -2,11 +2,11 @@
 API.
 """
 
-import requests
 from beartype import BeartypeConf, beartype
 from vws_auth_tools import authorization_header, rfc_1123_date
 
 from vws.response import Response
+from vws.transports import Transport
 
 
 @beartype(conf=BeartypeConf(is_pep484_tower=True))
@@ -21,27 +21,30 @@ def target_api_request(
     base_vws_url: str,
     request_timeout_seconds: float | tuple[float, float],
     extra_headers: dict[str, str],
+    transport: Transport,
 ) -> Response:
     """Make a request to the Vuforia Target API.
 
-    This uses `requests` to make a request against https://vws.vuforia.com.
-
     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
+        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, as used by
-            ``requests.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.
+        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 HTTP transport to use for the request.
 
     Returns:
-        The response to the request made by `requests`.
+        The response to the request.
     """
     date_string = rfc_1123_date()
 
@@ -64,20 +67,10 @@ def target_api_request(
 
     url = base_vws_url.rstrip("/") + request_path
 
-    requests_response = requests.request(
+    return transport(
         method=method,
         url=url,
         headers=headers,
         data=data,
-        timeout=request_timeout_seconds,
-    )
-
-    return Response(
-        text=requests_response.text,
-        url=requests_response.url,
-        status_code=requests_response.status_code,
-        headers=dict(requests_response.headers),
-        request_body=requests_response.request.body,
-        tell_position=requests_response.raw.tell(),
-        content=bytes(requests_response.content),
+        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