vws-python 2026.8.14__py3-none-any.whl

vws/__init__.py

@@ -0,0 +1,21 @@
+"""A library for Vuforia Web Services."""
+
+from .async_model_target_service import AsyncModelTargetService
+from .async_query import AsyncCloudRecoService
+from .async_vumark_service import AsyncVuMarkService
+from .async_vws import AsyncVWS
+from .model_target_service import ModelTargetService
+from .query import CloudRecoService
+from .vumark_service import VuMarkService
+from .vws import VWS
+
+__all__ = [
+    "VWS",
+    "AsyncCloudRecoService",
+    "AsyncModelTargetService",
+    "AsyncVWS",
+    "AsyncVuMarkService",
+    "CloudRecoService",
+    "ModelTargetService",
+    "VuMarkService",
+]

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  # noqa: TC001
+from vws.transports import AsyncTransport  # noqa: TC001
+
+
+@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/_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/_model_targets.py

@@ -0,0 +1,323 @@
+"""Internal helpers for the Vuforia Model Target Web API."""
+
+import base64
+import json
+from collections.abc import Sequence  # noqa: TC003
+from http import HTTPStatus
+from typing import Any
+
+from beartype import BeartypeConf, beartype
+
+from vws.exceptions.custom_exceptions import ServerError
+from vws.exceptions.model_target_exceptions import (
+    ModelTargetAuthenticationError,
+    ModelTargetDatasetNotDoneError,
+    ModelTargetError,
+    ModelTargetOAuth2Error,
+    ModelTargetValidationError,
+    UnknownModelTargetDatasetError,
+)
+from vws.exceptions.vws_exceptions import TooManyRequestsError
+from vws.model_target_datasets import (  # noqa: TC001
+    ModelTargetDatasetType,
+    ModelTargetModel,
+    ModelTargetView,
+)
+from vws.reports import ModelTargetDatasetStatusReport
+from vws.response import Response  # noqa: TC001
+
+OAUTH2_TOKEN_PATH = "/oauth2/token"  # noqa: S105
+OAUTH2_TOKEN_BODY = b"grant_type=client_credentials"
+OAUTH2_TOKEN_CONTENT_TYPE = "application/x-www-form-urlencoded"  # noqa: S105
+JSON_CONTENT_TYPE = "application/json"
+
+_DATASET_COLLECTION_PATHS = {
+    "standard": "/modeltargets/datasets",
+    "advanced": "/modeltargets/advancedDatasets",
+}
+_EXCEPTIONS_BY_STATUS_CODE: dict[int, type[ModelTargetError]] = {
+    HTTPStatus.BAD_REQUEST: ModelTargetValidationError,
+    HTTPStatus.UNAUTHORIZED: ModelTargetAuthenticationError,
+    HTTPStatus.NOT_FOUND: UnknownModelTargetDatasetError,
+    HTTPStatus.UNPROCESSABLE_ENTITY: ModelTargetDatasetNotDoneError,
+}
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def oauth2_token_headers(
+    *, client_id: str, client_secret: str
+) -> dict[str, str]:
+    """Get the headers for a request for an access token.
+
+    Args:
+        client_id: A Model Target Web API client ID.
+        client_secret: A Model Target Web API client secret.
+
+    Returns:
+        The headers to send with a token request.
+    """
+    credentials = f"{client_id}:{client_secret}".encode()
+    encoded_credentials = base64.b64encode(s=credentials).decode(
+        encoding="ascii",
+    )
+    return {
+        "Authorization": f"Basic {encoded_credentials}",
+        "Content-Type": OAUTH2_TOKEN_CONTENT_TYPE,
+    }
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def access_token_from_response(*, response: Response) -> tuple[str, float]:
+    """Get an access token and its lifetime from a token response.
+
+    Args:
+        response: The response from Vuforia's token endpoint.
+
+    Returns:
+        The access token, and the number of seconds until it expires.
+
+    Raises:
+        ~vws.exceptions.model_target_exceptions.ModelTargetOAuth2Error:
+            Vuforia did not give an access token.
+    """
+    if response.status_code != HTTPStatus.OK:
+        raise ModelTargetOAuth2Error(response=response)
+
+    response_data = dict(json.loads(s=response.text))
+    return response_data["access_token"], float(response_data["expires_in"])
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def dataset_collection_path(*, dataset_type: ModelTargetDatasetType) -> str:
+    """Get the path of the endpoint for datasets of a given type.
+
+    Args:
+        dataset_type: The kind of dataset to get the path for.
+
+    Returns:
+        The path of the dataset collection endpoint.
+    """
+    return _DATASET_COLLECTION_PATHS[dataset_type.value]
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def dataset_path(
+    *,
+    dataset_type: ModelTargetDatasetType,
+    dataset_uuid: str,
+) -> str:
+    """Get the path of the endpoint for one dataset.
+
+    Args:
+        dataset_type: The kind of dataset to get the path for.
+        dataset_uuid: The UUID of the dataset.
+
+    Returns:
+        The path of the dataset endpoint.
+    """
+    collection_path = dataset_collection_path(dataset_type=dataset_type)
+    return f"{collection_path}/{dataset_uuid}"
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def dataset_status_path(
+    *,
+    dataset_type: ModelTargetDatasetType,
+    dataset_uuid: str,
+) -> str:
+    """Get the path of the status endpoint for one dataset.
+
+    Args:
+        dataset_type: The kind of dataset to get the path for.
+        dataset_uuid: The UUID of the dataset.
+
+    Returns:
+        The path of the dataset status endpoint.
+    """
+    return (
+        dataset_path(dataset_type=dataset_type, dataset_uuid=dataset_uuid)
+        + "/status"
+    )
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def dataset_download_path(
+    *,
+    dataset_type: ModelTargetDatasetType,
+    dataset_uuid: str,
+) -> str:
+    """Get the path of the download endpoint for one dataset.
+
+    Args:
+        dataset_type: The kind of dataset to get the path for.
+        dataset_uuid: The UUID of the dataset.
+
+    Returns:
+        The path of the dataset download endpoint.
+    """
+    return (
+        dataset_path(dataset_type=dataset_type, dataset_uuid=dataset_uuid)
+        + "/dataset"
+    )
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def _view_dict(*, view: ModelTargetView) -> dict[str, Any]:
+    """Get the request representation of a guide view.
+
+    Args:
+        view: The guide view to represent.
+
+    Returns:
+        The guide view, as it is sent to Vuforia.
+    """
+    view_dict: dict[str, Any] = {
+        "name": view.name,
+        "guideViewPosition": {
+            "rotation": list(view.guide_view_position.rotation),
+            "translation": list(view.guide_view_position.translation),
+        },
+    }
+    if view.states is not None:
+        view_dict["states"] = list(view.states)
+
+    return view_dict
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def _model_dict(*, model: ModelTargetModel) -> dict[str, Any]:
+    """Get the request representation of a model.
+
+    Args:
+        model: The model to represent.
+
+    Returns:
+        The model, as it is sent to Vuforia.
+    """
+    model_dict: dict[str, Any] = {"name": model.name}
+    optional_values: dict[str, str | None] = {
+        "automaticColoring": model.automatic_coloring,
+        "cadDataBlob": model.cad_data_blob,
+        "cadDataFormat": model.cad_data_format,
+        "cadDataUrl": model.cad_data_url,
+        "motionHint": model.motion_hint,
+        "optimizeTrackingFor": model.optimize_tracking_for,
+        "realisticAppearance": model.realistic_appearance,
+        "simplify": model.simplify,
+        "stateBasedConfigurationJsonString": (
+            model.state_based_configuration_json_string
+        ),
+        "trackingMode": model.tracking_mode,
+    }
+    for field_name, value in optional_values.items():
+        if value is not None:
+            model_dict[field_name] = str(object=value)
+
+    if model.views is not None:
+        model_dict["views"] = [_view_dict(view=view) for view in model.views]
+
+    return model_dict
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def dataset_request_body(
+    *,
+    name: str,
+    target_sdk: str,
+    models: Sequence[ModelTargetModel],
+) -> bytes:
+    """Get the request body for creating a Model Target dataset.
+
+    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.
+
+    Returns:
+        The body of the request.
+    """
+    request_dict = {
+        "models": [_model_dict(model=model) for model in models],
+        "name": name,
+        "targetSdk": target_sdk,
+    }
+    return json.dumps(obj=request_dict).encode(encoding="utf-8")
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def raise_for_error(*, response: Response) -> None:
+    """Raise an exception for an unsuccessful Model Target Web API
+    response.
+
+    Args:
+        response: A response from the Model Target Web API.
+
+    Raises:
+        ~vws.exceptions.model_target_exceptions.ModelTargetAuthenticationError:
+            The request was not authenticated.
+        ~vws.exceptions.model_target_exceptions.ModelTargetValidationError:
+            Vuforia rejected the dataset creation request.
+        ~vws.exceptions.model_target_exceptions.UnknownModelTargetDatasetError:
+            No dataset of the given type matches the given UUID.
+        ~vws.exceptions.model_target_exceptions.ModelTargetDatasetNotDoneError:
+            The dataset has not been generated.
+        ~vws.exceptions.model_target_exceptions.ModelTargetError: Vuforia
+            returned another error.
+        ~vws.exceptions.custom_exceptions.ServerError: There is an error
+            with Vuforia's servers.
+        ~vws.exceptions.vws_exceptions.TooManyRequestsError: Vuforia is
+            rate limiting access.
+    """
+    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.BAD_REQUEST:
+        return
+
+    exception_type = _EXCEPTIONS_BY_STATUS_CODE.get(
+        response.status_code,
+        ModelTargetError,
+    )
+    raise exception_type(response=response)
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def dataset_uuid_from_response(*, response: Response) -> str:
+    """Get the UUID of a created dataset.
+
+    Args:
+        response: A response to a dataset creation request.
+
+    Returns:
+        The UUID of the created dataset.
+    """
+    response_data = dict(json.loads(s=response.text))
+    return str(object=response_data["uuid"])
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def status_report_from_response(
+    *,
+    response: Response,
+) -> ModelTargetDatasetStatusReport:
+    """Get a dataset status report from a status response.
+
+    Args:
+        response: A response to a dataset status request.
+
+    Returns:
+        The status of the dataset.
+    """
+    response_data = dict(json.loads(s=response.text))
+    return ModelTargetDatasetStatusReport.from_response_dict(
+        response_dict=response_data,
+    )

vws/_reco_counts.py

@@ -0,0 +1,80 @@
+"""Internal helpers for the database reco counts report endpoints."""
+
+import calendar  # noqa: TC003
+import json
+from http import HTTPStatus
+
+from beartype import BeartypeConf, beartype
+
+from vws.exceptions.custom_exceptions import (
+    DatabaseIdNotSetError,
+    RecoCountsReportDownloadError,
+    RecoCountsReportNotReadyError,
+)
+from vws.reports import RecoCountsReport
+from vws.response import Response  # noqa: TC001
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def reco_counts_report_path(*, database_id: str | None) -> str:
+    """Get the path of the reco counts report endpoint for a database.
+
+    Args:
+        database_id: The ID of the database to get the path for.
+
+    Returns:
+        The path of the reco counts report endpoint.
+
+    Raises:
+        ~vws.exceptions.custom_exceptions.DatabaseIdNotSetError: No
+            ``database_id`` was given to the client.
+    """
+    if database_id is None:
+        msg = (
+            "A database ID is needed to request a reco counts report. Give "
+            "``database_id`` when creating the client."
+        )
+        raise DatabaseIdNotSetError(msg)
+
+    return f"/imagetargets/databases/{database_id}/reports/recoCounts"
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def reco_counts_report_body(*, year: int, month: calendar.Month) -> bytes:
+    """Get the request body for requesting a reco counts report.
+
+    Args:
+        year: The year to request the report for.
+        month: The month of the year to request the report for.
+
+    Returns:
+        The body of the request.
+    """
+    month_string = f"{year:04d}-{month:02d}"
+    return json.dumps(obj={"month": month_string}).encode(encoding="utf-8")
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def report_from_download_response(*, response: Response) -> RecoCountsReport:
+    """Get a reco counts report from a response from a report's URL.
+
+    Args:
+        response: The response from a report's download URL.
+
+    Returns:
+        The downloaded report.
+
+    Raises:
+        ~vws.exceptions.custom_exceptions.RecoCountsReportNotReadyError:
+            Vuforia has not finished generating the report.
+        ~vws.exceptions.custom_exceptions.RecoCountsReportDownloadError: The
+            report could not be downloaded. For example, the report's URL may
+            have expired.
+    """
+    if response.status_code == HTTPStatus.NOT_FOUND:
+        raise RecoCountsReportNotReadyError(response=response)
+
+    if response.status_code != HTTPStatus.OK:
+        raise RecoCountsReportDownloadError(response=response)
+
+    return RecoCountsReport.from_csv(csv_bytes=response.content)

vws/_vws_request.py

@@ -0,0 +1,76 @@
+"""Internal helper for making authenticated 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  # noqa: TC001
+from vws.transports import Transport  # noqa: TC001
+
+
+@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],
+    transport: Transport,
+) -> Response:
+    """Make a 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 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 transport(
+        method=method,
+        url=url,
+        headers=headers,
+        data=data,
+        request_timeout=request_timeout_seconds,
+    )