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

mock_vws/_flask_server/target_manager.py

@@ -0,0 +1,447 @@
+"""Storage layer for the mock Vuforia Flask application."""
+
+import base64
+import copy
+import datetime
+import json
+from enum import StrEnum, auto
+from http import HTTPMethod, HTTPStatus
+from typing import assert_never
+from zoneinfo import ZoneInfo
+
+from beartype import beartype
+from flask import Flask, Response, request
+from pydantic_settings import BaseSettings
+
+from mock_vws.database import CloudDatabase, VuMarkDatabase
+from mock_vws.database_type import DatabaseType
+from mock_vws.states import States
+from mock_vws.target import ImageTarget, VuMarkTarget
+from mock_vws.target_manager import TargetManager
+from mock_vws.target_raters import (
+    BrisqueTargetTrackingRater,
+    HardcodedTargetTrackingRater,
+    RandomTargetTrackingRater,
+    TargetTrackingRater,
+)
+
+TARGET_MANAGER_FLASK_APP = Flask(import_name=__name__, static_folder=None)
+
+TARGET_MANAGER = TargetManager()
+
+
+@beartype
+class _TargetRaterChoice(StrEnum):
+    """Target rater choices."""
+
+    BRISQUE = auto()
+    PERFECT = auto()
+    RANDOM = auto()
+
+    def to_target_rater(
+        self: _TargetRaterChoice,
+    ) -> TargetTrackingRater:
+        """Get the target rater."""
+        match self:
+            case _TargetRaterChoice.BRISQUE:
+                return BrisqueTargetTrackingRater()
+            case _TargetRaterChoice.PERFECT:
+                return HardcodedTargetTrackingRater(rating=5)
+            case _TargetRaterChoice.RANDOM:
+                return RandomTargetTrackingRater()
+            case _ as unreachable:
+                assert_never(unreachable)
+
+
+@beartype
+class TargetManagerSettings(BaseSettings):
+    """Settings for the Target Manager Flask app."""
+
+    target_manager_host: str = ""
+    target_rater: _TargetRaterChoice = _TargetRaterChoice.BRISQUE
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases/<string:database_name>",
+    methods=[HTTPMethod.DELETE],
+)
+@beartype
+def delete_cloud_database(database_name: str) -> Response:
+    """Delete a cloud database.
+
+    :status 200: The cloud database has been deleted.
+    """
+    try:
+        (matching_database,) = {
+            database
+            for database in TARGET_MANAGER.cloud_databases
+            if database_name == database.database_name
+        }
+    except ValueError:
+        return Response(response="", status=HTTPStatus.NOT_FOUND)
+
+    TARGET_MANAGER.remove_cloud_database(cloud_database=matching_database)
+    return Response(response="", status=HTTPStatus.OK)
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases/<string:database_name>",
+    methods=[HTTPMethod.DELETE],
+)
+@beartype
+def delete_vumark_database(database_name: str) -> Response:
+    """Delete a VuMark database.
+
+    :status 200: The VuMark database has been deleted.
+    """
+    try:
+        (matching_database,) = {
+            database
+            for database in TARGET_MANAGER.vumark_databases
+            if database_name == database.database_name
+        }
+    except ValueError:
+        return Response(response="", status=HTTPStatus.NOT_FOUND)
+
+    TARGET_MANAGER.remove_vumark_database(vumark_database=matching_database)
+    return Response(response="", status=HTTPStatus.OK)
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases", methods=[HTTPMethod.GET]
+)
+@beartype
+def get_cloud_databases() -> Response:
+    """Return a list of all cloud databases."""
+    databases = [
+        database.to_dict() for database in TARGET_MANAGER.cloud_databases
+    ]
+    return Response(
+        response=json.dumps(obj=databases),
+        status=HTTPStatus.OK,
+    )
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases",
+    methods=[HTTPMethod.GET],
+)
+@beartype
+def get_vumark_databases() -> Response:
+    """Return a list of all VuMark databases."""
+    databases = [
+        database.to_dict() for database in TARGET_MANAGER.vumark_databases
+    ]
+    return Response(
+        response=json.dumps(obj=databases),
+        status=HTTPStatus.OK,
+    )
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases", methods=[HTTPMethod.POST]
+)
+@beartype
+def create_cloud_database() -> Response:
+    """Create a new cloud database.
+
+    :reqheader Content-Type: application/json
+    :resheader Content-Type: application/json
+
+    :reqjson string client_access_key: (Optional) The client access key for the
+      cloud database.
+
+    :reqjson string client_secret_key: (Optional) The client secret key for the
+      cloud database.
+
+    :reqjson string database_name: (Optional) The name of the cloud database.
+
+    :reqjson int request_quota: (Optional) The request quota. Set this to zero
+      to make VWS endpoints return ``RequestQuotaReached``.
+
+    :reqjson int target_quota: (Optional) The target quota. Once this many
+      targets exist, adding another returns ``TargetQuotaReached``.
+
+    :reqjson string server_access_key: (Optional) The server access key for the
+      cloud database.
+
+    :reqjson string server_secret_key: (Optional) The server secret key for the
+      cloud database.
+
+    :reqjson string state_name: (Optional) The state of the cloud database.
+     This can be "WORKING", "PROJECT_INACTIVE", "PROJECT_SUSPENDED", or
+     "PROJECT_HAS_NO_API_ACCESS". This defaults to "WORKING".
+
+    :resjson string client_access_key: The client access key for the cloud
+      database.
+
+    :resjson string client_secret_key: The client secret key for the cloud
+      database.
+
+    :resjson string database_name: The cloud database name.
+
+    :resjson int request_quota: The request quota.
+
+    :resjson int target_quota: The target quota.
+
+    :resjson string server_access_key: The server access key for the cloud
+      database.
+
+    :resjson string server_secret_key: The server secret key for the cloud
+      database.
+
+    :resjson string state_name: The cloud database state.
+
+    :reqjsonarr targets: The targets in the cloud database.
+
+    :status 201: The cloud database has been successfully created.
+    """
+    random_database = CloudDatabase()
+    request_json = json.loads(s=request.data)
+    server_access_key = request_json.get(
+        "server_access_key",
+        random_database.server_access_key,
+    )
+    server_secret_key = request_json.get(
+        "server_secret_key",
+        random_database.server_secret_key,
+    )
+    client_access_key = request_json.get(
+        "client_access_key",
+        random_database.client_access_key,
+    )
+    client_secret_key = request_json.get(
+        "client_secret_key",
+        random_database.client_secret_key,
+    )
+    database_name = request_json.get(
+        "database_name",
+        random_database.database_name,
+    )
+    state_name = request_json.get(
+        "state_name",
+        random_database.state.name,
+    )
+    database_type_name = request_json.get(
+        "database_type_name",
+        random_database.database_type.name,
+    )
+    request_quota = request_json.get(
+        "request_quota",
+        random_database.request_quota,
+    )
+    target_quota = request_json.get(
+        "target_quota",
+        random_database.target_quota,
+    )
+
+    state = States[state_name]
+    database_type = DatabaseType[database_type_name]
+
+    database = CloudDatabase(
+        server_access_key=server_access_key,
+        server_secret_key=server_secret_key,
+        client_access_key=client_access_key,
+        client_secret_key=client_secret_key,
+        database_name=database_name,
+        state=state,
+        database_type=database_type,
+        request_quota=request_quota,
+        target_quota=target_quota,
+    )
+    try:
+        TARGET_MANAGER.add_cloud_database(cloud_database=database)
+    except ValueError as exc:
+        return Response(
+            response=str(object=exc),
+            status=HTTPStatus.CONFLICT,
+        )
+
+    return Response(
+        response=json.dumps(obj=database.to_dict()),
+        status=HTTPStatus.CREATED,
+    )
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases",
+    methods=[HTTPMethod.POST],
+)
+@beartype
+def create_vumark_database() -> Response:
+    """Create a new VuMark database.
+
+    :status 201: The database has been successfully created.
+    """
+    request_json = json.loads(s=request.data)
+    random_vumark_database = VuMarkDatabase()
+    state_name = request_json.get(
+        "state_name",
+        random_vumark_database.state.name,
+    )
+    database = VuMarkDatabase(
+        server_access_key=request_json.get(
+            "server_access_key",
+            random_vumark_database.server_access_key,
+        ),
+        server_secret_key=request_json.get(
+            "server_secret_key",
+            random_vumark_database.server_secret_key,
+        ),
+        database_name=request_json.get(
+            "database_name",
+            random_vumark_database.database_name,
+        ),
+        state=States[state_name],
+    )
+
+    try:
+        TARGET_MANAGER.add_vumark_database(vumark_database=database)
+    except ValueError as exc:
+        return Response(
+            response=str(object=exc),
+            status=HTTPStatus.CONFLICT,
+        )
+
+    return Response(
+        response=json.dumps(obj=database.to_dict()),
+        status=HTTPStatus.CREATED,
+    )
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases/<string:database_name>/targets",
+    methods=[HTTPMethod.POST],
+)
+@beartype
+def create_target(database_name: str) -> Response:
+    """Create a new target in a given cloud database."""
+    (database,) = (
+        database
+        for database in TARGET_MANAGER.cloud_databases
+        if database.database_name == database_name
+    )
+    request_json = json.loads(s=request.data)
+    settings = TargetManagerSettings.model_validate(obj={})
+
+    image_bytes = base64.b64decode(s=request_json["image_base64"])
+    target_tracking_rater = settings.target_rater.to_target_rater()
+    target = ImageTarget(
+        name=request_json["name"],
+        width=request_json["width"],
+        image_value=image_bytes,
+        active_flag=request_json["active_flag"],
+        processing_time_seconds=request_json["processing_time_seconds"],
+        application_metadata=request_json["application_metadata"],
+        target_id=request_json["target_id"],
+        target_tracking_rater=target_tracking_rater,
+    )
+    database.targets.add(target)
+
+    return Response(
+        response=json.dumps(obj=target.to_dict()),
+        status=HTTPStatus.CREATED,
+    )
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases/<string:database_name>/vumark_targets",
+    methods=[HTTPMethod.POST],
+)
+@beartype
+def create_vumark_target(database_name: str) -> Response:
+    """Create a new VuMark target in a given database."""
+    (database,) = (
+        database
+        for database in TARGET_MANAGER.vumark_databases
+        if database.database_name == database_name
+    )
+    request_json = json.loads(s=request.data)
+    target = VuMarkTarget.from_dict(target_dict=request_json)
+    database.vumark_targets.add(target)
+
+    return Response(
+        response=json.dumps(obj=target.to_dict()),
+        status=HTTPStatus.CREATED,
+    )
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases/<string:database_name>/targets/<string:target_id>",
+    methods={HTTPMethod.DELETE},
+)
+@beartype
+def delete_target(database_name: str, target_id: str) -> Response:
+    """Delete a target."""
+    (database,) = (
+        database
+        for database in TARGET_MANAGER.cloud_databases
+        if database.database_name == database_name
+    )
+    target = database.get_target(target_id=target_id)
+    now = datetime.datetime.now(tz=target.upload_date.tzinfo)
+    # See https://github.com/facebook/pyrefly/issues/1897
+    new_target: ImageTarget = copy.replace(
+        target,  # pyrefly: ignore[bad-argument-type]
+        delete_date=now,
+    )
+    database.targets.remove(target)
+    database.targets.add(new_target)
+    return Response(
+        response=json.dumps(obj=new_target.to_dict()),
+        status=HTTPStatus.OK,
+    )
+
+
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases/<string:database_name>/targets/<string:target_id>",
+    methods=[HTTPMethod.PUT],
+)
+@beartype
+def update_target(database_name: str, target_id: str) -> Response:
+    """Update a target."""
+    (database,) = (
+        database
+        for database in TARGET_MANAGER.cloud_databases
+        if database.database_name == database_name
+    )
+    target = database.get_target(target_id=target_id)
+
+    request_json = json.loads(s=request.data)
+    name = request_json.get("name", target.name)
+    active_flag = request_json.get("active_flag", target.active_flag)
+
+    gmt = ZoneInfo(key="GMT")
+    last_modified_date = datetime.datetime.now(tz=gmt)
+
+    width = request_json.get("width", target.width)
+    application_metadata = request_json.get(
+        "application_metadata",
+        target.application_metadata,
+    )
+    image_value = target.image_value
+    if "image" in request_json:
+        image_value = base64.b64decode(s=request_json["image"])
+    # See https://github.com/facebook/pyrefly/issues/1897
+    new_target: ImageTarget = copy.replace(
+        target,  # pyrefly: ignore[bad-argument-type]
+        name=name,
+        width=width,
+        active_flag=active_flag,
+        application_metadata=application_metadata,
+        image_value=image_value,
+        last_modified_date=last_modified_date,
+    )
+
+    database.targets.remove(target)
+    database.targets.add(new_target)
+
+    return Response(
+        response=json.dumps(obj=new_target.to_dict()),
+        status=HTTPStatus.OK,
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    SETTINGS = TargetManagerSettings.model_validate(obj={})
+    TARGET_MANAGER_FLASK_APP.run(host=SETTINGS.target_manager_host)

mock_vws/_flask_server/vwq.py

@@ -0,0 +1,173 @@
+"""A fake implementation of the Vuforia Web Query API using Flask.
+
+See
+https://developer.vuforia.com/library/web-api/vuforia-query-web-api
+"""
+
+import email.utils
+import time
+from enum import StrEnum, auto
+from http import HTTPMethod, HTTPStatus
+from typing import assert_never
+
+import requests
+from beartype import beartype
+from flask import Flask, Response, request
+from pydantic_settings import BaseSettings
+
+from mock_vws._query_tools import (
+    get_query_match_response_text,
+)
+from mock_vws._query_validators import run_query_validators
+from mock_vws._query_validators.exceptions import (
+    ValidatorError,
+)
+from mock_vws.database import CloudDatabase
+from mock_vws.image_matchers import (
+    ExactMatcher,
+    ImageMatcher,
+    StructuralSimilarityMatcher,
+)
+
+CLOUDRECO_FLASK_APP = Flask(import_name=__name__, static_folder=None)
+CLOUDRECO_FLASK_APP.config["PROPAGATE_EXCEPTIONS"] = True
+
+
+@beartype
+class _ImageMatcherChoice(StrEnum):
+    """Image matcher choices."""
+
+    EXACT = auto()
+    STRUCTURAL_SIMILARITY = auto()
+
+    def to_image_matcher(self: _ImageMatcherChoice) -> ImageMatcher:
+        """Get the image matcher."""
+        match self:
+            case _ImageMatcherChoice.EXACT:
+                return ExactMatcher()
+            case _ImageMatcherChoice.STRUCTURAL_SIMILARITY:
+                return StructuralSimilarityMatcher()
+            case _ as unreachable:
+                assert_never(unreachable)
+
+
+@beartype
+class VWQSettings(BaseSettings):
+    """Settings for the VWQ Flask app."""
+
+    vwq_host: str = ""
+    target_manager_base_url: str
+    query_image_matcher: _ImageMatcherChoice = (
+        _ImageMatcherChoice.STRUCTURAL_SIMILARITY
+    )
+    response_delay_seconds: float = 0.0
+
+
+@beartype
+def get_all_cloud_databases() -> set[CloudDatabase]:
+    """Get all database objects from the target manager back-end."""
+    settings = VWQSettings.model_validate(obj={})
+    response = requests.get(
+        url=f"{settings.target_manager_base_url}/cloud_databases",
+        timeout=30,
+    )
+    return {
+        CloudDatabase.from_dict(database_dict=database_dict)
+        for database_dict in response.json()
+    }
+
+
+@CLOUDRECO_FLASK_APP.before_request
+@beartype
+def set_terminate_wsgi_input() -> None:
+    """We set ``wsgi.input_terminated`` to ``True`` when going through
+    ``requests`` in our tests, so that requests have the given ``Content-
+    Length`` headers and the given data in ``request.headers`` and
+    ``request.data``.
+
+    We do not set this at all when running an application as standalone.
+    This is because when running the Flask application, if this is set,
+    reading ``request.data`` hangs.
+
+    Therefore, when running the real Flask application, the behavior is not the
+    same as the real Vuforia.
+    This is documented as a difference in the documentation for this package.
+    """
+    try:
+        set_terminate_wsgi_input_true = (
+            CLOUDRECO_FLASK_APP.config["VWS_MOCK_TERMINATE_WSGI_INPUT"] is True
+        )
+    except KeyError:
+        set_terminate_wsgi_input_true = False
+
+    if set_terminate_wsgi_input_true:
+        request.environ["wsgi.input_terminated"] = True
+
+
+@CLOUDRECO_FLASK_APP.after_request
+@beartype
+def add_response_delay(response: Response) -> Response:
+    """Add a delay to each response."""
+    settings = VWQSettings.model_validate(obj={})
+    time.sleep(settings.response_delay_seconds)
+    return response
+
+
+@CLOUDRECO_FLASK_APP.errorhandler(code_or_exception=ValidatorError)
+@beartype
+def handle_exceptions(exc: ValidatorError) -> Response:
+    """Return the error response associated with the given exception."""
+    response = Response(
+        status=exc.status_code.value,
+        response=exc.response_text,
+        headers=exc.headers,
+    )
+
+    response.headers.clear()
+    response.headers.extend(exc.headers)
+    return response
+
+
+@CLOUDRECO_FLASK_APP.route(rule="/v1/query", methods=[HTTPMethod.POST])
+@beartype
+def query() -> Response:
+    """Perform an image recognition query."""
+    settings = VWQSettings.model_validate(obj={})
+    query_match_checker = settings.query_image_matcher.to_image_matcher()
+
+    databases = get_all_cloud_databases()
+    request_body = request.stream.read()
+    run_query_validators(
+        request_headers=dict(request.headers),
+        request_body=request_body,
+        request_method=request.method,
+        request_path=request.path,
+        databases=databases,
+    )
+    date = email.utils.formatdate(timeval=None, localtime=False, usegmt=True)
+
+    response_text = get_query_match_response_text(
+        request_headers=dict(request.headers),
+        request_body=request_body,
+        request_method=request.method,
+        request_path=request.path,
+        databases=databases,
+        query_match_checker=query_match_checker,
+    )
+
+    headers = {
+        "Content-Type": "application/json",
+        "Date": date,
+        "Connection": "keep-alive",
+        "Server": "nginx",
+    }
+    return Response(
+        status=HTTPStatus.OK,
+        response=response_text,
+        headers=headers,
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    SETTINGS = VWQSettings.model_validate(obj={})
+    CLOUDRECO_FLASK_APP.run(host=SETTINGS.vwq_host)