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

mock_vws/_query_validators/fields_validators.py

@@ -0,0 +1,47 @@
+"""Validators for the fields given."""
+
+import io
+import logging
+from collections.abc import Mapping
+from email.message import EmailMessage
+
+from beartype import beartype
+from werkzeug.formparser import MultiPartParser
+
+from mock_vws._query_validators.exceptions import UnknownParametersError
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_extra_fields(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate that the no unknown fields are given.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        UnknownParametersError: Extra fields are given.
+    """
+    email_message = EmailMessage()
+    email_message["Content-Type"] = request_headers["Content-Type"]
+    boundary = email_message.get_boundary(failobj="")
+    parser = MultiPartParser()
+    fields, files = parser.parse(
+        stream=io.BytesIO(initial_bytes=request_body),
+        boundary=boundary.encode(encoding="utf-8"),
+        content_length=len(request_body),
+    )
+    parsed_keys = fields.keys() | files.keys()
+    known_parameters = {"image", "max_num_results", "include_target_data"}
+
+    if not parsed_keys - known_parameters:
+        return
+
+    _LOGGER.warning(msg="Unknown parameters are given.")
+    raise UnknownParametersError

mock_vws/_query_validators/image_validators.py

@@ -0,0 +1,197 @@
+"""Input validators for the image field use in the mock query API."""
+
+import io
+import logging
+from collections.abc import Mapping
+from email.message import EmailMessage
+
+from beartype import beartype
+from PIL import Image
+from werkzeug.datastructures import FileStorage, MultiDict
+from werkzeug.formparser import MultiPartParser
+
+from mock_vws._query_validators.exceptions import (
+    BadImageError,
+    ImageNotGivenError,
+    RequestEntityTooLargeError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def _parse_multipart_files(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> MultiDict[str, FileStorage]:
+    """Parse the multipart body and return the files section.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Returns:
+        The files parsed from the multipart body.
+    """
+    email_message = EmailMessage()
+    email_message["Content-Type"] = request_headers["Content-Type"]
+    boundary = email_message.get_boundary(failobj="")
+    parser = MultiPartParser()
+    _, files = parser.parse(
+        stream=io.BytesIO(initial_bytes=request_body),
+        boundary=boundary.encode(encoding="utf-8"),
+        content_length=len(request_body),
+    )
+    return files
+
+
+@beartype
+def validate_image_field_given(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate that the image field is given.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        ImageNotGivenError: The image field is not given.
+    """
+    files = _parse_multipart_files(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    if files.get(key="image") is not None:
+        return
+
+    _LOGGER.warning(msg="The image field is not given.")
+    raise ImageNotGivenError
+
+
+@beartype
+def validate_image_file_size(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the file size of the image given to the query endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        RequestEntityTooLargeError: The image file size is too large.
+    """
+    files = _parse_multipart_files(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    image_part = files["image"]
+    image_value = image_part.stream.read()
+
+    # This is the documented maximum size of a PNG as per.
+    # https://developer.vuforia.com/library/web-api/vuforia-query-web-api.
+    # However, the tests show that this maximum size also applies to JPEG
+    # files.
+    max_bytes = 2 * 1024 * 1024
+    # Ignore coverage on this as there is a bug in urllib3 which means that we
+    # do not trigger this exception.
+    # See https://github.com/urllib3/urllib3/issues/2733.
+    if len(image_value) > max_bytes:  # pragma: no cover
+        _LOGGER.warning(msg="The image file size is too large.")
+        raise RequestEntityTooLargeError
+
+
+@beartype
+def validate_image_dimensions(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the dimensions the image given to the query endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        BadImageError: The image is given and is not within the maximum width
+            and height limits.
+    """
+    files = _parse_multipart_files(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    image_part = files["image"]
+    image_value = image_part.stream.read()
+    image_file = io.BytesIO(initial_bytes=image_value)
+    with Image.open(fp=image_file) as pil_image:
+        max_width = 30000
+        max_height = 30000
+        if pil_image.height <= max_height and pil_image.width <= max_width:
+            return
+
+    _LOGGER.warning(msg="The image dimensions are too large.")
+    raise BadImageError
+
+
+@beartype
+def validate_image_format(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the format of the image given to the query endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        BadImageError: The image is given and is not either a PNG or a JPEG.
+    """
+    files = _parse_multipart_files(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    image_part = files["image"]
+    with Image.open(fp=image_part.stream) as pil_image:
+        if pil_image.format in {"PNG", "JPEG"}:
+            return
+
+    _LOGGER.warning(msg="The image format is not PNG or JPEG.")
+    raise BadImageError
+
+
+@beartype
+def validate_image_is_image(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate that the given image data is actually an image file.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        BadImageError: Image data is given and it is not an image file.
+    """
+    files = _parse_multipart_files(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    image_file = files["image"].stream
+
+    try:
+        with Image.open(fp=image_file) as _:
+            pass
+    except OSError as exc:
+        _LOGGER.warning(msg="The image is not an image file.")
+        raise BadImageError from exc

mock_vws/_query_validators/include_target_data_validators.py

@@ -0,0 +1,51 @@
+"""Validators for the ``include_target_data`` field."""
+
+import io
+import logging
+from collections.abc import Mapping
+from email.message import EmailMessage
+
+from beartype import beartype
+from werkzeug.formparser import MultiPartParser
+
+from mock_vws._query_validators.exceptions import InvalidIncludeTargetDataError
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_include_target_data(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the ``include_target_data`` field is either an accepted
+    value
+    or not given.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        InvalidIncludeTargetDataError: The ``include_target_data`` field is not
+            an accepted value.
+    """
+    email_message = EmailMessage()
+    email_message["Content-Type"] = request_headers["Content-Type"]
+    boundary = email_message.get_boundary(failobj="")
+    parser = MultiPartParser()
+    fields, _ = parser.parse(
+        stream=io.BytesIO(initial_bytes=request_body),
+        boundary=boundary.encode(encoding="utf-8"),
+        content_length=len(request_body),
+    )
+    include_target_data = fields.get(key="include_target_data", default="top")
+    allowed_included_target_data = {"top", "all", "none"}
+    if include_target_data.lower() in allowed_included_target_data:
+        return
+
+    _LOGGER.warning(
+        msg="The include_target_data field is not an accepted value.",
+    )
+    raise InvalidIncludeTargetDataError(given_value=include_target_data)

mock_vws/_query_validators/num_results_validators.py

@@ -0,0 +1,64 @@
+"""Validators for the ``max_num_results`` fields."""
+
+import io
+import logging
+from collections.abc import Mapping
+from email.message import EmailMessage
+
+from beartype import beartype
+from werkzeug.formparser import MultiPartParser
+
+from mock_vws._query_validators.exceptions import (
+    InvalidMaxNumResultsError,
+    MaxNumResultsOutOfRangeError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_max_num_results(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the ``max_num_results`` field is either an integer within
+    range
+    or not given.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        InvalidMaxNumResultsError: The ``max_num_results`` given is not an
+            integer less than or equal to the max integer in Java.
+        MaxNumResultsOutOfRangeError: The ``max_num_results`` given is not in
+            range.
+    """
+    email_message = EmailMessage()
+    email_message["Content-Type"] = request_headers["Content-Type"]
+    boundary = email_message.get_boundary(failobj="")
+    parser = MultiPartParser()
+    fields, _ = parser.parse(
+        stream=io.BytesIO(initial_bytes=request_body),
+        boundary=boundary.encode(encoding="utf-8"),
+        content_length=len(request_body),
+    )
+    max_num_results = fields.get(key="max_num_results", default="1")
+
+    try:
+        max_num_results_int = int(max_num_results)
+    except ValueError as exc:
+        _LOGGER.warning(msg="The max_num_results field is not an integer.")
+        raise InvalidMaxNumResultsError(given_value=max_num_results) from exc
+
+    java_max_int = 2147483647
+    if max_num_results_int > java_max_int:
+        _LOGGER.warning(msg="The max_num_results field is too large.")
+        raise InvalidMaxNumResultsError(given_value=max_num_results)
+
+    max_allowed_results = 50
+    if max_num_results_int < 1 or max_num_results_int > max_allowed_results:
+        _LOGGER.warning(msg="The max_num_results field is out of range.")
+        raise MaxNumResultsOutOfRangeError(given_value=max_num_results)

mock_vws/_query_validators/project_state_validators.py

@@ -0,0 +1,49 @@
+"""Validators for the project state."""
+
+import logging
+from collections.abc import Iterable, Mapping
+
+from beartype import beartype
+
+from mock_vws._database_matchers import get_database_matching_client_keys
+from mock_vws._query_validators.exceptions import InactiveProjectError
+from mock_vws.database import CloudDatabase
+from mock_vws.states import States
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_project_state(
+    *,
+    request_path: str,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+    request_method: str,
+    databases: Iterable[CloudDatabase],
+) -> None:
+    """Validate the state of the project.
+
+    Args:
+        request_path: The path of the request.
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+        request_method: The HTTP method of the request.
+        databases: All Vuforia databases.
+
+    Raises:
+        InactiveProjectError: The project is inactive.
+    """
+    database = get_database_matching_client_keys(
+        request_headers=request_headers,
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+        databases=databases,
+    )
+
+    if database.state != States.PROJECT_INACTIVE:
+        return
+
+    _LOGGER.warning(msg="The project is inactive.")
+    raise InactiveProjectError

mock_vws/_requests_mock_server/__init__.py

@@ -0,0 +1 @@
+"""An interface to the mock Vuforia which uses ``responses``."""

mock_vws/_requests_mock_server/decorators.py

@@ -0,0 +1,275 @@
+"""Decorators for using the mock."""
+
+import re
+import time
+from collections.abc import Callable, Mapping
+from contextlib import ContextDecorator
+from typing import TYPE_CHECKING, Any, Literal, Self
+from urllib.parse import urlparse
+
+import requests
+from beartype import BeartypeConf, beartype
+from requests import PreparedRequest
+from responses import RequestsMock
+
+from mock_vws._mock_common import MissingSchemeError, RequestData
+from mock_vws._respx_mock_server.decorators import start_respx_router
+from mock_vws.database import CloudDatabase, VuMarkDatabase
+from mock_vws.image_matchers import (
+    ImageMatcher,
+    StructuralSimilarityMatcher,
+)
+from mock_vws.target_manager import TargetManager
+from mock_vws.target_raters import (
+    BrisqueTargetTrackingRater,
+    TargetTrackingRater,
+)
+
+from .mock_web_query_api import MockVuforiaWebQueryAPI
+from .mock_web_services_api import MockVuforiaWebServicesAPI
+
+if TYPE_CHECKING:
+    import respx
+
+_ResponseType = tuple[int, Mapping[str, str], str | bytes]
+_MockCallback = Callable[[RequestData], _ResponseType]
+_ResponsesCallback = Callable[[PreparedRequest], _ResponseType]
+
+_STRUCTURAL_SIMILARITY_MATCHER = StructuralSimilarityMatcher()
+_BRISQUE_TRACKING_RATER = BrisqueTargetTrackingRater()
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class MockVWS(ContextDecorator):
+    """Route requests to Vuforia's Web Service APIs to fakes of those APIs.
+
+    Works with both ``requests`` and ``httpx``.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_vws_url: str = "https://vws.vuforia.com",
+        base_vwq_url: str = "https://cloudreco.vuforia.com",
+        duplicate_match_checker: ImageMatcher = _STRUCTURAL_SIMILARITY_MATCHER,
+        query_match_checker: ImageMatcher = _STRUCTURAL_SIMILARITY_MATCHER,
+        processing_time_seconds: float = 2.0,
+        target_tracking_rater: TargetTrackingRater = _BRISQUE_TRACKING_RATER,
+        real_http: bool = False,
+        response_delay_seconds: float = 0.0,
+        sleep_fn: Callable[[float], None] = time.sleep,
+    ) -> None:
+        """Route requests to Vuforia's Web Service APIs to fakes of those
+        APIs.
+
+        Works with both ``requests`` and ``httpx``.
+
+        Args:
+            real_http: Whether or not to forward requests to the real
+                server if they are not handled by the mock.
+                See
+                https://requests-mock.readthedocs.io/en/latest/mocker.html#real-http-requests.
+            processing_time_seconds: The number of seconds to process each
+                image for.
+                In the real Vuforia Web Services, this is not deterministic.
+            base_vwq_url: The base URL for the VWQ API.
+            base_vws_url: The base URL for the VWS API.
+            query_match_checker: A callable which takes two image values and
+                returns whether they will match in a query request.
+            duplicate_match_checker: A callable which takes two image values
+                and returns whether they are duplicates.
+            target_tracking_rater: A callable for rating targets for tracking.
+            response_delay_seconds: The number of seconds to delay each
+                response by. This can be used to test timeout handling.
+            sleep_fn: The function to use for sleeping during response
+                delays. Defaults to ``time.sleep``. Inject a custom
+                function to control virtual time in tests without
+                monkey-patching.
+
+        Raises:
+            MissingSchemeError: There is no scheme in a given URL.
+        """
+        super().__init__()
+        self._real_http = real_http
+        self._response_delay_seconds = response_delay_seconds
+        self._sleep_fn = sleep_fn
+        self._mock: RequestsMock
+        self._router: respx.MockRouter
+        self._target_manager = TargetManager()
+
+        self._base_vws_url = base_vws_url
+        self._base_vwq_url = base_vwq_url
+        for url in (base_vwq_url, base_vws_url):
+            parse_result = urlparse(url=url)
+            if not parse_result.scheme:
+                raise MissingSchemeError(url=url)
+
+        self._mock_vws_api = MockVuforiaWebServicesAPI(
+            target_manager=self._target_manager,
+            processing_time_seconds=float(processing_time_seconds),
+            duplicate_match_checker=duplicate_match_checker,
+            target_tracking_rater=target_tracking_rater,
+        )
+
+        self._mock_vwq_api = MockVuforiaWebQueryAPI(
+            target_manager=self._target_manager,
+            query_match_checker=query_match_checker,
+        )
+
+    def add_cloud_database(self, cloud_database: CloudDatabase) -> None:
+        """Add a cloud database.
+
+        Args:
+            cloud_database: The cloud database to add.
+
+        Raises:
+            ValueError: One of the given cloud database keys matches a key for
+                an existing cloud database.
+        """
+        self._target_manager.add_cloud_database(
+            cloud_database=cloud_database,
+        )
+
+    def add_vumark_database(self, vumark_database: VuMarkDatabase) -> None:
+        """Add a VuMark database.
+
+        Args:
+            vumark_database: The VuMark database to add.
+
+        Raises:
+            ValueError: One of the given database keys matches a key for
+                an existing database.
+        """
+        self._target_manager.add_vumark_database(
+            vumark_database=vumark_database,
+        )
+
+    @staticmethod
+    def _wrap_callback(
+        callback: _MockCallback,
+        delay_seconds: float,
+        sleep_fn: Callable[[float], None],
+        base_path: str,
+    ) -> _ResponsesCallback:
+        """Wrap a callback to add a response delay."""
+
+        def wrapped(
+            request: PreparedRequest,
+        ) -> _ResponseType:
+            """Handle the response delay and timeout logic."""
+            # req_kwargs is added dynamically by the responses
+            # library onto PreparedRequest objects - it is not
+            # in the requests type stubs.
+            req_kwargs: dict[str, Any] = getattr(  # pylint: disable=bad-builtin
+                request,
+                "req_kwargs",
+                {},
+            )
+            timeout: tuple[float, float] | float | int | None = req_kwargs.get(
+                "timeout"
+            )
+            # requests allows timeout as a (connect, read)
+            # tuple. The delay simulates server response
+            # time, so compare against the read timeout.
+            match timeout:
+                case (_, int() | float() as read_timeout):
+                    effective: float | None = float(read_timeout)
+                case int() | float():
+                    effective = float(timeout)
+                case _:
+                    effective = None
+
+            if effective is not None and delay_seconds > effective:
+                sleep_fn(effective)
+                raise requests.exceptions.Timeout
+
+            match request.body:
+                case None:
+                    body_bytes = b""
+                case str() as raw_body:
+                    body_bytes = raw_body.encode(encoding="utf-8")
+                case _:
+                    body_bytes = request.body
+
+            path = request.path_url
+            if base_path and path.startswith(base_path):
+                path = path[len(base_path) :]
+
+            request_data = RequestData(
+                method=request.method or "",
+                path=path,
+                headers=dict(request.headers),
+                body=body_bytes,
+            )
+            result = callback(request_data)
+            sleep_fn(delay_seconds)
+            return result
+
+        return wrapped
+
+    def __enter__(self) -> Self:
+        """Start an instance of a Vuforia mock.
+
+        Returns:
+            ``self``.
+        """
+        mock = RequestsMock(assert_all_requests_are_fired=False)
+
+        for api, base_url in (
+            (self._mock_vws_api, self._base_vws_url),
+            (self._mock_vwq_api, self._base_vwq_url),
+        ):
+            base_path = urlparse(url=base_url).path.rstrip("/")
+            for route in api.routes:
+                url_pattern = base_url.rstrip("/") + route.path_pattern + "$"
+                compiled_url_pattern = re.compile(pattern=url_pattern)
+
+                for http_method in route.http_methods:
+                    original_callback = getattr(  # pylint: disable=bad-builtin
+                        api,
+                        route.route_name,
+                    )
+                    mock.add_callback(
+                        method=http_method,
+                        url=compiled_url_pattern,
+                        callback=self._wrap_callback(
+                            callback=original_callback,
+                            delay_seconds=self._response_delay_seconds,
+                            sleep_fn=self._sleep_fn,
+                            base_path=base_path,
+                        ),
+                        content_type=None,
+                    )
+
+        if self._real_http:
+            all_requests_pattern = re.compile(pattern=".*")
+            mock.add_passthru(prefix=all_requests_pattern)
+
+        self._mock = mock
+        self._mock.start()
+
+        self._router = start_respx_router(
+            mock_vws_api=self._mock_vws_api,
+            mock_vwq_api=self._mock_vwq_api,
+            base_vws_url=self._base_vws_url,
+            base_vwq_url=self._base_vwq_url,
+            response_delay_seconds=self._response_delay_seconds,
+            sleep_fn=self._sleep_fn,
+            real_http=self._real_http,
+        )
+
+        return self
+
+    def __exit__(self, *exc: object) -> Literal[False]:
+        """Stop the Vuforia mock.
+
+        Returns:
+            False
+        """
+        # __exit__ needs this to be passed in but vulture thinks that it is
+        # unused, so we "use" it here.
+        del exc
+
+        self._mock.stop()
+        self._router.stop()
+        return False