vws-python 2026.2.15__tar.gz → 2026.2.21__tar.gz

{vws_python-2026.2.15 → vws_python-2026.2.21}/CHANGELOG.rst

@@ -4,6 +4,10 @@ Changelog
 Next
 ----
 
+2026.02.21
+----------
+
+
 2026.02.15
 ----------
 

{vws_python-2026.2.15/src/vws_python.egg-info → vws_python-2026.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vws-python
-Version: 2026.2.15
+Version: 2026.2.21
 Summary: Interact with the Vuforia Web Services (VWS) API.
 Author-email: Adam Dangoor <adamdangoor@gmail.com>
 License-Expression: MIT
@@ -22,24 +22,24 @@ Requires-Dist: requests>=2.32.3
 Requires-Dist: urllib3>=2.2.3
 Requires-Dist: vws-auth-tools>=2024.7.12
 Provides-Extra: dev
-Requires-Dist: actionlint-py==1.7.10.24; extra == "dev"
+Requires-Dist: actionlint-py==1.7.11.24; extra == "dev"
 Requires-Dist: check-manifest==0.51; extra == "dev"
 Requires-Dist: deptry==0.24.0; extra == "dev"
 Requires-Dist: doc8==2.0.0; extra == "dev"
-Requires-Dist: doccmd==2026.1.31.3; extra == "dev"
+Requires-Dist: doccmd==2026.2.15; extra == "dev"
 Requires-Dist: freezegun==1.5.5; extra == "dev"
 Requires-Dist: furo==2025.12.19; extra == "dev"
 Requires-Dist: interrogate==1.7.0; extra == "dev"
 Requires-Dist: mypy[faster-cache]==1.19.1; extra == "dev"
 Requires-Dist: mypy-strict-kwargs==2026.1.12; extra == "dev"
-Requires-Dist: prek==0.3.2; extra == "dev"
+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-per-file-ignores==3.2.0; extra == "dev"
-Requires-Dist: pyproject-fmt==2.16.0; extra == "dev"
-Requires-Dist: pyrefly==0.52.0; extra == "dev"
+Requires-Dist: pyproject-fmt==2.16.1; extra == "dev"
+Requires-Dist: pyrefly==0.53.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"
@@ -55,10 +55,12 @@ Requires-Dist: sphinx-pyproject==0.3.0; extra == "dev"
 Requires-Dist: sphinx-substitution-extensions==2026.1.12; extra == "dev"
 Requires-Dist: sphinxcontrib-spelling==8.0.2; extra == "dev"
 Requires-Dist: sybil==9.3.0; extra == "dev"
-Requires-Dist: ty==0.0.16; 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: types-requests==2.32.4.20260107; extra == "dev"
 Requires-Dist: vulture==2.14; extra == "dev"
-Requires-Dist: vws-python-mock==2026.2.15.4; extra == "dev"
+Requires-Dist: vws-python-mock==2026.2.21; 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.15 → vws_python-2026.2.21}/conftest.py

@@ -9,7 +9,7 @@ from pathlib import Path
 import pytest
 from beartype import beartype
 from mock_vws import MockVWS
-from mock_vws.database import VuforiaDatabase
+from mock_vws.database import CloudDatabase
 from sybil import Sybil
 from sybil.parsers.rest import (
     ClearNamespaceParser,
@@ -53,7 +53,7 @@ def fixture_mock_vws(
     client_access_key = uuid.uuid4().hex
     client_secret_key = uuid.uuid4().hex
 
-    database = VuforiaDatabase(
+    database = CloudDatabase(
         server_access_key=server_access_key,
         server_secret_key=server_secret_key,
         client_access_key=client_access_key,
@@ -66,7 +66,7 @@ def fixture_mock_vws(
     monkeypatch.setenv(name="VWS_CLIENT_SECRET_KEY", value=client_secret_key)
     # We use a low processing time so that tests run quickly.
     with MockVWS(processing_time_seconds=0.2) as mock:
-        mock.add_database(database=database)
+        mock.add_cloud_database(cloud_database=database)
         yield
 
 

{vws_python-2026.2.15 → vws_python-2026.2.21}/docs/source/api-reference.rst

@@ -13,6 +13,10 @@ API Reference
    :undoc-members:
    :members:
 
+.. automodule:: vws.vumark_accept
+   :undoc-members:
+   :members:
+
 .. automodule:: vws.response
    :undoc-members:
    :members:

{vws_python-2026.2.15 → vws_python-2026.2.21}/docs/source/index.rst

@@ -78,13 +78,13 @@ To write unit tests for code which uses this library, without using your Vuforia
     import pathlib
 
     from mock_vws import MockVWS
-    from mock_vws.database import VuforiaDatabase
+    from mock_vws.database import CloudDatabase
 
     from vws import VWS, CloudRecoService
 
     with MockVWS() as mock:
-        database = VuforiaDatabase()
-        mock.add_database(database=database)
+        database = CloudDatabase()
+        mock.add_cloud_database(cloud_database=database)
         vws_client = VWS(
             server_access_key=database.server_access_key,
             server_secret_key=database.server_secret_key,

{vws_python-2026.2.15 → vws_python-2026.2.21}/pyproject.toml

@@ -38,24 +38,24 @@ dependencies = [
     "vws-auth-tools>=2024.7.12",
 ]
 optional-dependencies.dev = [
-    "actionlint-py==1.7.10.24",
+    "actionlint-py==1.7.11.24",
     "check-manifest==0.51",
     "deptry==0.24.0",
     "doc8==2.0.0",
-    "doccmd==2026.1.31.3",
+    "doccmd==2026.2.15",
     "freezegun==1.5.5",
     "furo==2025.12.19",
     "interrogate==1.7.0",
     "mypy[faster-cache]==1.19.1",
     "mypy-strict-kwargs==2026.1.12",
-    "prek==0.3.2",
+    "prek==0.3.3",
     "pydocstringformatter==0.7.5",
     "pydocstyle==6.3",
     "pygments==2.19.2",
     "pylint[spelling]==4.0.4",
     "pylint-per-file-ignores==3.2.0",
-    "pyproject-fmt==2.16.0",
-    "pyrefly==0.52.0",
+    "pyproject-fmt==2.16.1",
+    "pyrefly==0.53.0",
     "pyright==1.1.408",
     "pyroma==5.0.1",
     "pytest==9.0.2",
@@ -74,10 +74,15 @@ optional-dependencies.dev = [
     "sphinx-substitution-extensions==2026.1.12",
     "sphinxcontrib-spelling==8.0.2",
     "sybil==9.3.0",
-    "ty==0.0.16",
+    # Listed explicitly (despite being transitive via vws-python-mock) so that
+    # [tool.uv.sources] can redirect to the CPU-only PyTorch index.
+    # 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",
     "types-requests==2.32.4.20260107",
     "vulture==2.14",
-    "vws-python-mock==2026.2.15.4",
+    "vws-python-mock==2026.2.21",
     "vws-test-fixtures==2023.3.5",
     "yamlfix==1.19.1",
     "zizmor==1.22.0",
@@ -106,6 +111,11 @@ bdist_wheel.universal = true
 # Code to match this is in ``conf.py``.
 version_scheme = "post-release"
 
+[tool.uv]
+sources.torch = { index = "pytorch-cpu" }
+sources.torchvision = { index = "pytorch-cpu" }
+index = [ { name = "pytorch-cpu", url = "https://download.pytorch.org/whl/cpu", explicit = true } ]
+
 [tool.ruff]
 line-length = 79
 lint.select = [
@@ -277,6 +287,13 @@ pep621_dev_dependency_groups = [
     "dev",
     "release",
 ]
+# torch and torchvision are listed explicitly in dev deps to allow
+# [tool.uv.sources] to redirect them to the CPU-only PyTorch index,
+# but they are not directly imported in the vws-python source code.
+per_rule_ignores.DEP002 = [
+    "torch",
+    "torchvision",
+]
 
 [tool.pyproject-fmt]
 indent = 4
@@ -292,6 +309,7 @@ run.branch = true
 report.exclude_also = [
     "if TYPE_CHECKING:",
 ]
+report.show_missing = true
 
 [tool.mypy]
 strict = true

{vws_python-2026.2.15 → vws_python-2026.2.21}/spelling_private_dict.txt

@@ -42,6 +42,7 @@ decodable
 dev
 dict
 docstring
+enum
 filename
 foo
 formdata
@@ -100,6 +101,7 @@ usefixtures
 validators
 vuforia
 vuforia's
+vumark
 vwq
 vws
 xxx

{vws_python-2026.2.15 → vws_python-2026.2.21}/src/vws/__init__.py

@@ -1,9 +1,11 @@
 """A library for Vuforia Web Services."""
 
 from .query import CloudRecoService
+from .vumark_service import VuMarkService
 from .vws import VWS
 
 __all__ = [
     "VWS",
     "CloudRecoService",
+    "VuMarkService",
 ]

vws_python-2026.2.21/src/vws/_vws_request.py

@@ -0,0 +1,85 @@
+"""Internal helper for making authenticated requests to the Vuforia Target
+API.
+"""
+
+from urllib.parse import urljoin
+
+import requests
+from beartype import BeartypeConf, beartype
+from vws_auth_tools import authorization_header, rfc_1123_date
+
+from vws.response import Response
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def 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],
+) -> 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
+            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.
+
+    Returns:
+        The response to the request made by `requests`.
+    """
+    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 = urljoin(base=base_vws_url, url=request_path)
+
+    requests_response = requests.request(
+        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),
+    )

{vws_python-2026.2.15 → vws_python-2026.2.21}/src/vws/exceptions/vws_exceptions.py

@@ -24,9 +24,10 @@ class UnknownTargetError(VWSError):
     def target_id(self) -> str:
         """The unknown target ID."""
         path = urlparse(url=self.response.url).path
-        # Every HTTP path which can raise this error is in the format
-        # `/something/{target_id}`.
-        return path.split(sep="/", maxsplit=2)[-1]
+        # Every HTTP path which can raise this error has the target ID as the
+        # second path segment, e.g. `/something/{target_id}` or
+        # `/something/{target_id}/more`.
+        return path.split(sep="/")[2]
 
 
 @beartype
@@ -68,9 +69,10 @@ class TargetStatusProcessingError(VWSError):
     def target_id(self) -> str:
         """The processing target ID."""
         path = urlparse(url=self.response.url).path
-        # Every HTTP path which can raise this error is in the format
-        # `/something/{target_id}`.
-        return path.split(sep="/", maxsplit=2)[-1]
+        # Every HTTP path which can raise this error has the target ID as the
+        # second path segment, e.g. `/something/{target_id}` or
+        # `/something/{target_id}/more`.
+        return path.split(sep="/")[2]
 
 
 # This is not simulated by the mock.
@@ -157,9 +159,10 @@ class TargetStatusNotSuccessError(VWSError):
     def target_id(self) -> str:
         """The unknown target ID."""
         path = urlparse(url=self.response.url).path
-        # Every HTTP path which can raise this error is in the format
-        # `/something/{target_id}`.
-        return path.split(sep="/", maxsplit=2)[-1]
+        # Every HTTP path which can raise this error has the target ID as the
+        # second path segment, e.g. `/something/{target_id}` or
+        # `/something/{target_id}/more`.
+        return path.split(sep="/")[2]
 
 
 @beartype
@@ -167,3 +170,35 @@ class TooManyRequestsError(VWSError):  # pragma: no cover
     """Exception raised when Vuforia returns a response with a result code
     'TooManyRequests'.
     """
+
+
+# This is not simulated by client code because the accept parameter uses
+# the VuMarkAccept enum, which only allows valid values.
+@beartype
+class InvalidAcceptHeaderError(VWSError):  # pragma: no cover
+    """Exception raised when Vuforia returns a response with a result code
+    ``InvalidAcceptHeader``.
+    """
+
+
+@beartype
+class InvalidInstanceIdError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    ``InvalidInstanceId``.
+    """
+
+
+# This is not simulated by client code because the request body
+# is always valid JSON when using this client.
+@beartype
+class BadRequestError(VWSError):  # pragma: no cover
+    """Exception raised when Vuforia returns a response with a result code
+    ``BadRequest``.
+    """
+
+
+@beartype
+class InvalidTargetTypeError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    ``InvalidTargetType``.
+    """

{vws_python-2026.2.15 → vws_python-2026.2.21}/src/vws/query.py

@@ -156,6 +156,7 @@ class CloudRecoService:
             headers=dict(requests_response.headers),
             request_body=requests_response.request.body,
             tell_position=requests_response.raw.tell(),
+            content=bytes(requests_response.content),
         )
 
         if response.status_code == HTTPStatus.REQUEST_ENTITY_TOO_LARGE:

{vws_python-2026.2.15 → vws_python-2026.2.21}/src/vws/response.py

@@ -16,3 +16,4 @@ class Response:
     headers: dict[str, str]
     request_body: bytes | str | None
     tell_position: int
+    content: bytes

vws_python-2026.2.21/src/vws/vumark_accept.py

@@ -0,0 +1,18 @@
+"""Tools for managing ``VWS.generate_vumark_instance``'s ``accept``."""
+
+from enum import StrEnum, unique
+
+from beartype import beartype
+
+
+@beartype
+@unique
+class VuMarkAccept(StrEnum):
+    """
+    Options for the ``accept`` parameter of
+    ``VWS.generate_vumark_instance``.
+    """
+
+    PNG = "image/png"
+    SVG = "image/svg+xml"
+    PDF = "application/pdf"

vws_python-2026.2.21/src/vws/vumark_service.py

@@ -0,0 +1,143 @@
+"""Interface to the Vuforia VuMark Generation Web API."""
+
+import json
+from http import HTTPMethod, HTTPStatus
+
+from beartype import BeartypeConf, beartype
+
+from vws._vws_request import 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.vumark_accept import VuMarkAccept
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class VuMarkService:
+    """An 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,
+    ) -> 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, as
+                used by ``requests.request``. This can be a float to set
+                both the connect and read timeouts, or a (connect, read)
+                tuple.
+        """
+        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
+
+    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 = 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},
+        )
+
+        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)