vws-python 2026.8.14__py3-none-any.whl

vws/transports.py

@@ -0,0 +1,315 @@
+"""HTTP transport implementations for VWS clients."""
+
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+import httpx
+import requests
+from beartype import BeartypeConf, beartype
+
+from vws.response import Response
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Protocol for HTTP transports used by VWS clients.
+
+    A transport is a callable that makes an HTTP request and
+    returns a ``Response``.
+    """
+
+    def close(self) -> None:
+        """Close the transport and release resources."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    def __call__(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        data: bytes,
+        request_timeout: float | tuple[float, float],
+    ) -> Response:
+        """Make an HTTP request.
+
+        Args:
+            method: The HTTP method (e.g. "GET", "POST").
+            url: The full URL to request.
+            headers: Headers to send with the request.
+            data: The request body as bytes.
+            request_timeout: The timeout for the request. A float
+                sets both the connect and read timeouts. A
+                (connect, read) tuple sets them individually.
+
+        Returns:
+            A Response populated from the HTTP response.
+        """
+        ...  # pylint: disable=unnecessary-ellipsis
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class RequestsTransport:
+    """HTTP transport using the ``requests`` library.
+
+    This is the default transport.
+    """
+
+    def close(self) -> None:
+        """Close the transport.
+
+        This is a no-op for ``RequestsTransport`` as it does not
+        hold persistent connections.
+        """
+
+    def __call__(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        data: bytes,
+        request_timeout: float | tuple[float, float],
+    ) -> Response:
+        """Make an HTTP request using ``requests``.
+
+        Args:
+            method: The HTTP method.
+            url: The full URL.
+            headers: Request headers.
+            data: The request body.
+            request_timeout: The request timeout.
+
+        Returns:
+            A Response populated from the requests response.
+        """
+        requests_response = requests.request(
+            method=method,
+            url=url,
+            headers=headers,
+            data=data,
+            timeout=request_timeout,
+        )
+
+        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),
+        )
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class HTTPXTransport:
+    """HTTP transport using the ``httpx`` library.
+
+    Use this transport for environments where ``httpx`` is
+    preferred over ``requests``.
+    A single ``httpx.Client`` is reused across requests
+    for connection pooling.
+    """
+
+    def __init__(self) -> None:
+        """Create an ``HTTPXTransport``."""
+        self._client = httpx.Client()
+
+    def close(self) -> None:
+        """Close the underlying ``httpx.Client``."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        """Exit the context manager and close the client."""
+        self.close()
+
+    def __call__(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        data: bytes,
+        request_timeout: float | tuple[float, float],
+    ) -> Response:
+        """Make an HTTP request using ``httpx``.
+
+        Args:
+            method: The HTTP method.
+            url: The full URL.
+            headers: Request headers.
+            data: The request body.
+            request_timeout: The request timeout.
+
+        Returns:
+            A Response populated from the httpx response.
+        """
+        match request_timeout:
+            case tuple() as timeout:
+                connect_timeout, read_timeout = timeout
+                httpx_timeout = httpx.Timeout(
+                    connect=connect_timeout,
+                    read=read_timeout,
+                    write=None,
+                    pool=None,
+                )
+            case timeout:
+                httpx_timeout = httpx.Timeout(
+                    connect=timeout,
+                    read=timeout,
+                    write=None,
+                    pool=None,
+                )
+
+        httpx_response = self._client.request(
+            method=method,
+            url=url,
+            headers=headers,
+            content=data,
+            timeout=httpx_timeout,
+            follow_redirects=True,
+        )
+
+        content = bytes(httpx_response.content)
+        request_content = httpx_response.request.content
+
+        return Response(
+            text=httpx_response.text,
+            url=str(object=httpx_response.url),
+            status_code=httpx_response.status_code,
+            headers=dict(httpx_response.headers),
+            request_body=bytes(request_content) or None,
+            tell_position=len(content),
+            content=content,
+        )
+
+
+@runtime_checkable
+class AsyncTransport(Protocol):
+    """Protocol for async HTTP transports used by VWS clients.
+
+    An async transport is a callable that makes an HTTP request
+    and returns a ``Response``.
+    """
+
+    async def aclose(self) -> None:
+        """Close the transport and release resources."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    def __call__(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        data: bytes,
+        request_timeout: float | tuple[float, float],
+    ) -> Awaitable[Response]:
+        """Make an async HTTP request.
+
+        Args:
+            method: The HTTP method (e.g. "GET", "POST").
+            url: The full URL to request.
+            headers: Headers to send with the request.
+            data: The request body as bytes.
+            request_timeout: The timeout for the request. A float
+                sets both the connect and read timeouts. A
+                (connect, read) tuple sets them individually.
+
+        Returns:
+            A Response populated from the HTTP response.
+        """
+        ...  # pylint: disable=unnecessary-ellipsis
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class AsyncHTTPXTransport:
+    """Async HTTP transport using the ``httpx`` library.
+
+    This is the default transport for async VWS clients.
+    A single ``httpx.AsyncClient`` is reused across requests
+    for connection pooling.
+    """
+
+    def __init__(self) -> None:
+        """Create an ``AsyncHTTPXTransport``."""
+        self._client = httpx.AsyncClient()
+
+    async def aclose(self) -> None:
+        """Close the underlying ``httpx.AsyncClient``."""
+        await self._client.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 client."""
+        await self.aclose()
+
+    async def __call__(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        data: bytes,
+        request_timeout: float | tuple[float, float],
+    ) -> Response:
+        """Make an async HTTP request using ``httpx``.
+
+        Args:
+            method: The HTTP method.
+            url: The full URL.
+            headers: Request headers.
+            data: The request body.
+            request_timeout: The request timeout.
+
+        Returns:
+            A Response populated from the httpx response.
+        """
+        match request_timeout:
+            case tuple() as timeout:
+                connect_timeout, read_timeout = timeout
+                httpx_timeout = httpx.Timeout(
+                    connect=connect_timeout,
+                    read=read_timeout,
+                    write=None,
+                    pool=None,
+                )
+            case timeout:
+                httpx_timeout = httpx.Timeout(
+                    connect=timeout,
+                    read=timeout,
+                    write=None,
+                    pool=None,
+                )
+
+        httpx_response = await self._client.request(
+            method=method,
+            url=url,
+            headers=headers,
+            content=data,
+            timeout=httpx_timeout,
+            follow_redirects=True,
+        )
+
+        content = bytes(httpx_response.content)
+        request_content = httpx_response.request.content
+
+        return Response(
+            text=httpx_response.text,
+            url=str(object=httpx_response.url),
+            status_code=httpx_response.status_code,
+            headers=dict(httpx_response.headers),
+            request_body=bytes(request_content) or None,
+            tell_position=len(content),
+            content=content,
+        )

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/vumark_service.py

@@ -0,0 +1,138 @@
+"""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.base_exceptions import VWSError
+from vws.exceptions.custom_exceptions import ServerError
+from vws.exceptions.vws_exceptions import TooManyRequestsError
+from vws.transports import RequestsTransport, Transport
+from vws.vumark_accept import VuMarkAccept  # noqa: TC001
+
+
+@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,
+        transport: Transport | 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 HTTP transport to use for
+                requests. Defaults to
+                ``RequestsTransport()``.
+        """
+        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 if transport is not None else RequestsTransport()
+        )
+
+    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.AuthorizationFailedError: There was
+                a general authentication problem.
+            ~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.LicenseCheckFailedError: The
+                license state and/or type does not allow this request.
+            ~vws.exceptions.vws_exceptions.QuotaExceededError: No more
+                instances can be created for the associated license.
+            ~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},
+            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"]
+
+        raise VWSError.from_result_code(
+            result_code=result_code,
+            response=response,
+        )