Rename database methods and endpoints to cloud_databases (#2970)

Clarify that database-related methods, endpoints, and variables refer to cloud databases rather than generic databases. This lays the groundwork for supporting additional database types in the future.

Changes:
- Rename Flask endpoints from /databases to /cloud_databases
- Rename TargetManager methods: add_database → add_cloud_database, remove_database → remove_cloud_database
- Rename MockVWS.add_database → add_cloud_database
- Update all callers, tests, documentation, and error messages accordingly

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: adamtheturtle

README.rst

@@ -30,7 +30,7 @@ This requires Python |minimum-python-version|\+.
 
     with MockVWS() as mock:
         database = CloudDatabase()
-        mock.add_database(database=database)
+        mock.add_cloud_database(cloud_database=database)
         # This will use the Vuforia mock.
         requests.get(url="https://vws.vuforia.com/summary", timeout=30)
 

docs/source/basic-example.rst

@@ -11,7 +11,7 @@ Using the mock redirects requests to Vuforia made with `requests`_ to an in-memo
 
     with MockVWS() as mock:
         database = CloudDatabase()
-        mock.add_database(database=database)
+        mock.add_cloud_database(cloud_database=database)
         # This will use the Vuforia mock.
         requests.get(url="https://vws.vuforia.com/summary", timeout=30)
 

docs/source/docker.rst

@@ -63,7 +63,7 @@ For example, with the containers set up as in :ref:`creating-containers`, use ``
    $ curl --request POST \
        --header "Content-Type: application/json" \
        --data '{}' \
-       '127.0.0.1:5005/databases'
+       '127.0.0.1:5005/cloud_databases'
    {
        "client_access_key": "2d61c1d17bb94694bee77c1f1f41e5d9",
        "client_secret_key": "b73f8170cf7d42728fa8ce66221ad147",
@@ -80,7 +80,7 @@ Deleting a database
 To delete a database use the following endpoint:
 
 .. autoflask:: mock_vws._flask_server.target_manager:TARGET_MANAGER_FLASK_APP
-   :endpoints: delete_database
+   :endpoints: delete_cloud_database
 
 
 .. _Target Manager: https://developer.vuforia.com/target-manager

src/mock_vws/_flask_server/target_manager.py

@@ -58,14 +58,14 @@ class TargetManagerSettings(BaseSettings):
 
 
 @TARGET_MANAGER_FLASK_APP.route(
-    rule="/databases/<string:database_name>",
+    rule="/cloud_databases/<string:database_name>",
     methods=[HTTPMethod.DELETE],
 )
 @beartype
-def delete_database(database_name: str) -> Response:
-    """Delete a database.
+def delete_cloud_database(database_name: str) -> Response:
+    """Delete a cloud database.
 
-    :status 200: The database has been deleted.
+    :status 200: The cloud database has been deleted.
     """
     try:
         (matching_database,) = {
@@ -76,14 +76,16 @@ def delete_database(database_name: str) -> Response:
     except ValueError:
         return Response(response="", status=HTTPStatus.NOT_FOUND)
 
-    TARGET_MANAGER.remove_database(database=matching_database)
+    TARGET_MANAGER.remove_cloud_database(cloud_database=matching_database)
     return Response(response="", status=HTTPStatus.OK)
 
 
-@TARGET_MANAGER_FLASK_APP.route(rule="/databases", methods=[HTTPMethod.GET])
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases", methods=[HTTPMethod.GET]
+)
 @beartype
 def get_cloud_databases() -> Response:
-    """Return a list of all databases."""
+    """Return a list of all cloud databases."""
     databases = [
         database.to_dict() for database in TARGET_MANAGER.cloud_databases
     ]
@@ -93,47 +95,53 @@ def get_cloud_databases() -> Response:
     )
 
 
-@TARGET_MANAGER_FLASK_APP.route(rule="/databases", methods=[HTTPMethod.POST])
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/cloud_databases", methods=[HTTPMethod.POST]
+)
 @beartype
 def create_cloud_database() -> Response:
-    """Create a new database.
+    """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
-      database.
+      cloud database.
 
     :reqjson string client_secret_key: (Optional) The client secret key for the
-      database.
+      cloud database.
 
-    :reqjson string database_name: (Optional) The name of the database.
+    :reqjson string database_name: (Optional) The name of the cloud database.
 
     :reqjson string server_access_key: (Optional) The server access key for the
-      database.
+      cloud database.
 
     :reqjson string server_secret_key: (Optional) The server secret key for the
-      database.
+      cloud database.
 
-    :reqjson string state_name: (Optional) The state of the database. This can
-     be "WORKING" or "PROJECT_INACTIVE". This defaults to "WORKING".
+    :reqjson string state_name: (Optional) The state of the cloud database.
+     This can be "WORKING" or "PROJECT_INACTIVE". This defaults to "WORKING".
 
-    :resjson string client_access_key: The client access key for the database.
+    :resjson string client_access_key: The client access key for the cloud
+      database.
 
-    :resjson string client_secret_key: The client secret key for the database.
+    :resjson string client_secret_key: The client secret key for the cloud
+      database.
 
-    :resjson string database_name: The database name.
+    :resjson string database_name: The cloud database name.
 
-    :resjson string server_access_key: The server access key for the database.
+    :resjson string server_access_key: The server access key for the cloud
+      database.
 
-    :resjson string server_secret_key: The server secret key for the database.
+    :resjson string server_secret_key: The server secret key for the cloud
+      database.
 
-    :resjson string state_name: The database state. This will be "WORKING" or
-      "PROJECT_INACTIVE".
+    :resjson string state_name: The cloud database state. This will be
+      "WORKING" or "PROJECT_INACTIVE".
 
-    :reqjsonarr targets: The targets in the database.
+    :reqjsonarr targets: The targets in the cloud database.
 
-    :status 201: The database has been successfully created.
+    :status 201: The cloud database has been successfully created.
     """
     random_database = CloudDatabase()
     request_json = json.loads(s=request.data)
@@ -173,7 +181,7 @@ def create_cloud_database() -> Response:
         state=state,
     )
     try:
-        TARGET_MANAGER.add_database(database=database)
+        TARGET_MANAGER.add_cloud_database(cloud_database=database)
     except ValueError as exc:
         return Response(
             response=str(object=exc),
@@ -187,12 +195,12 @@ def create_cloud_database() -> Response:
 
 
 @TARGET_MANAGER_FLASK_APP.route(
-    rule="/databases/<string:database_name>/targets",
+    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 database."""
+    """Create a new target in a given cloud database."""
     (database,) = (
         database
         for database in TARGET_MANAGER.cloud_databases
@@ -223,7 +231,7 @@ def create_target(database_name: str) -> Response:
 
 
 @TARGET_MANAGER_FLASK_APP.route(
-    rule="/databases/<string:database_name>/targets/<string:target_id>",
+    rule="/cloud_databases/<string:database_name>/targets/<string:target_id>",
     methods={HTTPMethod.DELETE},
 )
 @beartype
@@ -250,7 +258,7 @@ def delete_target(database_name: str, target_id: str) -> Response:
 
 
 @TARGET_MANAGER_FLASK_APP.route(
-    rule="/databases/<string:database_name>/targets/<string:target_id>",
+    rule="/cloud_databases/<string:database_name>/targets/<string:target_id>",
     methods=[HTTPMethod.PUT],
 )
 def update_target(database_name: str, target_id: str) -> Response:

src/mock_vws/_flask_server/vwq.py

@@ -67,7 +67,7 @@ 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}/databases",
+        url=f"{settings.target_manager_base_url}/cloud_databases",
         timeout=30,
     )
     return {

src/mock_vws/_flask_server/vws.py

@@ -91,7 +91,7 @@ def get_all_cloud_databases() -> set[CloudDatabase]:
     settings = VWSSettings.model_validate(obj={})
     timeout_seconds = 30
     response = requests.get(
-        url=f"{settings.target_manager_base_url}/databases",
+        url=f"{settings.target_manager_base_url}/cloud_databases",
         timeout=timeout_seconds,
     )
     return {
@@ -202,7 +202,7 @@ def add_target() -> Response:
         target_tracking_rater=target_tracking_rater,
     )
 
-    databases_url = f"{settings.target_manager_base_url}/databases"
+    databases_url = f"{settings.target_manager_base_url}/cloud_databases"
     timeout_seconds = 30
     requests.post(
         url=f"{databases_url}/{database.database_name}/targets",
@@ -318,7 +318,7 @@ def delete_target(target_id: str) -> Response:
     if target.status == TargetStatuses.PROCESSING.value:
         raise TargetStatusProcessingError
 
-    databases_url = f"{settings.target_manager_base_url}/databases"
+    databases_url = f"{settings.target_manager_base_url}/cloud_databases"
     requests.delete(
         url=f"{databases_url}/{database.database_name}/targets/{target_id}",
         timeout=30,
@@ -669,7 +669,7 @@ def update_target(target_id: str) -> Response:
         update_values["image"] = image
 
     put_url = (
-        f"{settings.target_manager_base_url}/databases/"
+        f"{settings.target_manager_base_url}/cloud_databases/"
         f"{database.database_name}/targets/{target_id}"
     )
     requests.put(url=put_url, json=update_values, timeout=30)

src/mock_vws/_requests_mock_server/decorators.py

@@ -126,17 +126,19 @@ def __init__(
             query_match_checker=query_match_checker,
         )
 
-    def add_database(self, database: CloudDatabase) -> None:
+    def add_cloud_database(self, cloud_database: CloudDatabase) -> None:
         """Add a cloud database.
 
         Args:
-            database: The database to add.
+            cloud_database: The cloud database to add.
 
         Raises:
-            ValueError: One of the given database keys matches a key for an
-                existing database.
+            ValueError: One of the given cloud database keys matches a key for
+                an existing cloud database.
         """
-        self._target_manager.add_database(database=database)
+        self._target_manager.add_cloud_database(
+            cloud_database=cloud_database,
+        )
 
     @staticmethod
     def _wrap_callback(

src/mock_vws/target_manager.py

@@ -19,69 +19,71 @@ class TargetManager:
     """
 
     def __init__(self) -> None:
-        """Create a target manager with no databases."""
-        self._databases: Iterable[CloudDatabase] = set()
+        """Create a target manager with no cloud databases."""
+        self._cloud_databases: Iterable[CloudDatabase] = set()
 
-    def remove_database(self, database: CloudDatabase) -> None:
+    def remove_cloud_database(self, cloud_database: CloudDatabase) -> None:
         """Remove a cloud database.
 
         Args:
-            database: The database to add.
+            cloud_database: The cloud database to remove.
 
         Raises:
-            KeyError: The database is not in the target manager.
+            KeyError: The cloud database is not in the target manager.
         """
-        self._databases = {db for db in self._databases if db != database}
+        self._cloud_databases = {
+            db for db in self._cloud_databases if db != cloud_database
+        }
 
-    def add_database(self, database: CloudDatabase) -> None:
+    def add_cloud_database(self, cloud_database: CloudDatabase) -> None:
         """Add a cloud database.
 
         Args:
-            database: The database to add.
+            cloud_database: The cloud database to add.
 
         Raises:
-            ValueError: One of the given database keys matches a key for an
-                existing database.
+            ValueError: One of the given cloud database keys matches a key for
+                an existing cloud database.
         """
         message_fmt = (
             "All {key_name}s must be unique. "
-            'There is already a database with the {key_name} "{value}".'
+            'There is already a cloud database with the {key_name} "{value}".'
         )
         for existing_db in self.cloud_databases:
             for existing, new, key_name in (
                 (
                     existing_db.server_access_key,
-                    database.server_access_key,
+                    cloud_database.server_access_key,
                     "server access key",
                 ),
                 (
                     existing_db.server_secret_key,
-                    database.server_secret_key,
+                    cloud_database.server_secret_key,
                     "server secret key",
                 ),
                 (
                     existing_db.client_access_key,
-                    database.client_access_key,
+                    cloud_database.client_access_key,
                     "client access key",
                 ),
                 (
                     existing_db.client_secret_key,
-                    database.client_secret_key,
+                    cloud_database.client_secret_key,
                     "client secret key",
                 ),
                 (
                     existing_db.database_name,
-                    database.database_name,
+                    cloud_database.database_name,
                     "name",
                 ),
             ):
                 if existing == new:
                     message = message_fmt.format(key_name=key_name, value=new)
                     raise ValueError(message)
 
-        self._databases = {*self._databases, database}
+        self._cloud_databases = {*self._cloud_databases, cloud_database}
 
     @property
     def cloud_databases(self) -> set[CloudDatabase]:
         """All cloud databases."""
-        return set(self._databases)
+        return set(self._cloud_databases)

tests/mock_vws/fixtures/vuforia_backends.py

@@ -137,9 +137,9 @@ def _enable_use_mock_vuforia(
     )
 
     with MockVWS() as mock:
-        mock.add_database(database=working_database)
-        mock.add_database(database=inactive_database)
-        mock.add_database(database=vumark_database)
+        mock.add_cloud_database(cloud_database=working_database)
+        mock.add_cloud_database(cloud_database=inactive_database)
+        mock.add_cloud_database(cloud_database=vumark_database)
         yield
 
 
@@ -196,7 +196,7 @@ def _enable_use_docker_in_memory(
             base_url=target_manager_base_url,
         )
 
-        databases_url = target_manager_base_url + "/databases"
+        databases_url = target_manager_base_url + "/cloud_databases"
         databases = requests.get(url=databases_url, timeout=30).json()
         for database in databases:
             database_name = database["database_name"]

tests/mock_vws/test_database_summary.py

@@ -246,7 +246,7 @@ def test_processing_images(
         )
 
         with MockVWS() as mock:
-            mock.add_database(database=database)
+            mock.add_cloud_database(cloud_database=database)
             vws_client.add_target(
                 name=uuid.uuid4().hex,
                 width=1,