vws-python-mock 2026.8.4__py3-none-any.whl

mock_vws/__init__.py

@@ -0,0 +1,9 @@
+"""Tools for using a fake implementation of Vuforia."""
+
+from mock_vws._mock_common import MissingSchemeError
+from mock_vws._requests_mock_server.decorators import MockVWS
+
+__all__ = [
+    "MissingSchemeError",
+    "MockVWS",
+]

mock_vws/_base64_decoding.py

@@ -0,0 +1,35 @@
+"""Helpers for handling Base64 like Vuforia does."""
+
+import base64
+import binascii
+import string
+
+from beartype import beartype
+
+
+@beartype
+def decode_base64(encoded_data: str) -> bytes:
+    """Decode base64 somewhat like Vuforia does.
+
+    Raises:
+        binascii.Error: Vuforia would consider this encoded data as an
+          "UNPROCESSABLE_ENTITY".
+
+    Returns:
+        The given data, decoded as base64.
+    """
+    acceptable_characters = string.ascii_letters + string.digits + "+/="
+    for character in encoded_data:
+        if character not in acceptable_characters:
+            raise binascii.Error
+
+    mod_four_result_to_modified_encoded_data = {
+        0: encoded_data,
+        1: encoded_data[:-1],
+        2: f"{encoded_data}==",
+        3: f"{encoded_data}=",
+    }
+    modified_encoded_data = mod_four_result_to_modified_encoded_data[
+        len(encoded_data) % 4
+    ]
+    return base64.b64decode(s=modified_encoded_data)

mock_vws/_constants.py

@@ -0,0 +1,84 @@
+"""Constants used to make the VWS mock."""
+
+from enum import Enum, unique
+
+from beartype import beartype
+
+VUMARK_PNG = (
+    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00"
+    b"\x01\x08\x04\x00\x00\x00\xb5\x1c\x0c\x02\x00\x00\x00\x0bIDATx\xdac"
+    b"\xfc\xff\x1f\x00\x03\x03\x02\x00\xee\xd9\x97\xa9\x00\x00\x00\x00IEND"
+    b"\xaeB`\x82"
+)
+
+VUMARK_SVG = (
+    b'<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"></svg>'
+)
+
+VUMARK_PDF = (
+    b"%PDF-1.4\n"
+    b"1 0 obj<</Type /Catalog /Pages 2 0 R>>endobj\n"
+    b"2 0 obj<</Type /Pages /Kids [3 0 R] /Count 1>>endobj\n"
+    b"3 0 obj<</Type /Page /MediaBox [0 0 100 100]>>endobj\n"
+    b"xref\n0 4\n"
+    b"0000000000 65535 f \n"
+    b"trailer<</Size 4/Root 1 0 R>>\n"
+    b"startxref\n9\n%%EOF"
+)
+
+
+@beartype
+@unique
+class ResultCodes(Enum):
+    """Constants representing various VWS result codes.
+
+    See
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#result-codes.
+
+    Some codes here are not documented in the above link.
+    """
+
+    SUCCESS = "Success"
+    TARGET_CREATED = "TargetCreated"
+    AUTHENTICATION_FAILURE = "AuthenticationFailure"
+    REQUEST_TIME_TOO_SKEWED = "RequestTimeTooSkewed"
+    TARGET_NAME_EXIST = "TargetNameExist"
+    UNKNOWN_TARGET = "UnknownTarget"
+    BAD_IMAGE = "BadImage"
+    IMAGE_TOO_LARGE = "ImageTooLarge"
+    METADATA_TOO_LARGE = "MetadataTooLarge"
+    # The documentation says "Start date is after the end date" but, at the
+    # time of writing, I do not know how to trigger that, therefore this is not
+    # tested.
+    DATE_RANGE_ERROR = "DateRangeError"
+    FAIL = "Fail"
+    TARGET_STATUS_PROCESSING = "TargetStatusProcessing"
+    # This is tested only against the mock. We do not deliberately exhaust the
+    # real test database's quota because that would stop the verified-fake test
+    # suite from using it.
+    REQUEST_QUOTA_REACHED = "RequestQuotaReached"
+    TARGET_STATUS_NOT_SUCCESS = "TargetStatusNotSuccess"
+    TARGET_QUOTA_REACHED = "TargetQuotaReached"
+    PROJECT_SUSPENDED = "ProjectSuspended"
+    PROJECT_INACTIVE = "ProjectInactive"
+    PROJECT_HAS_NO_API_ACCESS = "ProjectHasNoAPIAccess"
+    INACTIVE_PROJECT = "InactiveProject"
+    TOO_MANY_REQUESTS = "TooManyRequests"
+    INVALID_ACCEPT_HEADER = "InvalidAcceptHeader"
+    INVALID_INSTANCE_ID = "InvalidInstanceId"
+    BAD_REQUEST = "BadRequest"
+    INVALID_TARGET_TYPE = "InvalidTargetType"
+
+
+@beartype
+@unique
+class TargetStatuses(Enum):
+    """Constants representing VWS target statuses.
+
+    See the 'status' field in
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record
+    """
+
+    PROCESSING = "processing"
+    SUCCESS = "success"
+    FAILED = "failed"

mock_vws/_database_matchers.py

@@ -0,0 +1,107 @@
+"""Helpers for getting databases which match keys given in requests."""
+
+from collections.abc import Iterable, Mapping
+
+from beartype import beartype
+from vws_auth_tools import authorization_header
+
+from mock_vws.database import CloudDatabase, VuMarkDatabase
+
+AnyDatabase = CloudDatabase | VuMarkDatabase
+
+
+@beartype
+def get_database_matching_client_keys(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes | None,
+    request_method: str,
+    request_path: str,
+    databases: Iterable[CloudDatabase],
+) -> CloudDatabase:
+    """Return the first of the given databases which is being accessed by
+    the
+    given client request.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The request body.
+        request_method: The HTTP method of the request.
+        request_path: The path of the request.
+        databases: The databases to check for matches.
+
+    Returns:
+        The database which is being accessed by the given client request.
+
+    Raises:
+        ValueError: No database matches the given request.
+    """
+    request_headers_dict = dict(request_headers)
+    content_type = request_headers_dict.get("Content-Type", "").split(sep=";")[
+        0
+    ]
+    auth_header = request_headers_dict.get("Authorization")
+    date = request_headers_dict.get("Date", "")
+
+    for database in databases:
+        expected_authorization_header = authorization_header(
+            access_key=database.client_access_key,
+            secret_key=database.client_secret_key,
+            method=request_method,
+            content=request_body,
+            content_type=content_type,
+            date=date,
+            request_path=request_path,
+        )
+
+        if auth_header == expected_authorization_header:
+            return database
+    raise ValueError
+
+
+@beartype
+def get_database_matching_server_keys[DatabaseT: AnyDatabase](
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes | None,
+    request_method: str,
+    request_path: str,
+    databases: Iterable[DatabaseT],
+) -> DatabaseT:
+    """Return the first of the given databases which is being accessed by
+    the
+    given server request.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The request body.
+        request_method: The HTTP method of the request.
+        request_path: The path of the request.
+        databases: The databases to check for matches.
+
+    Returns:
+        The database being accessed by the given server request.
+
+    Raises:
+        ValueError: No database matches the given request.
+    """
+    request_headers_dict = dict(request_headers)
+    content_type_header = request_headers_dict.get("Content-Type", "")
+    content_type = content_type_header.split(sep=";")[0]
+    auth_header = request_headers_dict.get("Authorization")
+    date = request_headers_dict.get("Date", "")
+
+    for database in databases:
+        expected_authorization_header = authorization_header(
+            access_key=database.server_access_key,
+            secret_key=database.server_secret_key,
+            method=request_method,
+            content=request_body,
+            content_type=content_type,
+            date=date,
+            request_path=request_path,
+        )
+
+        if auth_header == expected_authorization_header:
+            return database
+    raise ValueError

mock_vws/_flask_server/Dockerfile

@@ -0,0 +1,32 @@
+FROM ghcr.io/astral-sh/uv:0.11.7-python3.14-trixie-slim AS base
+# We set this pretend version as we do not have Git in our path, and we do
+# not care enough about having the version correct inside the Docker container
+# to install it.
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0
+# Avoid using root user.
+RUN useradd -ms /bin/bash myuser
+USER myuser
+COPY --chown=myuser:myuser . /app
+
+# See https://pythonspeed.com/articles/activate-virtualenv-dockerfile/
+# For why we use this method of activating the virtual environment.
+ENV UV_PROJECT_ENVIRONMENT=/app/docker_venvs/.venv
+ENV PATH="$UV_PROJECT_ENVIRONMENT/bin:$PATH"
+
+WORKDIR /app
+RUN uv sync --no-cache
+EXPOSE 5000
+ENTRYPOINT ["python"]
+HEALTHCHECK --interval=1s --timeout=10s --start-period=5s --retries=3 CMD ["python", "/app/src/mock_vws/_flask_server/healthcheck.py"]
+
+FROM base AS vws
+ENV VWS_HOST=0.0.0.0
+CMD ["src/mock_vws/_flask_server/vws.py"]
+
+FROM base AS vwq
+ENV VWQ_HOST=0.0.0.0
+CMD ["src/mock_vws/_flask_server/vwq.py"]
+
+FROM base AS target-manager
+ENV TARGET_MANAGER_HOST=0.0.0.0
+CMD ["src/mock_vws/_flask_server/target_manager.py"]

mock_vws/_flask_server/__init__.py

@@ -0,0 +1 @@
+"""Flask server for the mock Vuforia web service."""

mock_vws/_flask_server/healthcheck.py

@@ -0,0 +1,31 @@
+"""Health check for the Flask server."""
+
+import http.client
+import socket
+import sys
+from http import HTTPStatus
+
+from beartype import beartype
+
+
+@beartype
+def flask_app_healthy(port: int) -> bool:
+    """Check if the Flask app is healthy."""
+    conn = http.client.HTTPConnection(host="localhost", port=port)
+    try:
+        conn.request(method="GET", url="/some-random-endpoint")
+        response = conn.getresponse()
+    except TimeoutError, http.client.HTTPException, socket.gaierror:
+        return False
+    finally:
+        conn.close()
+
+    return response.status in {
+        HTTPStatus.NOT_FOUND,
+        HTTPStatus.UNAUTHORIZED,
+        HTTPStatus.FORBIDDEN,
+    }
+
+
+if __name__ == "__main__":
+    sys.exit(int(not flask_app_healthy(port=5000)))