Add Model Target Web API client support

Add ``ModelTargetService`` and ``AsyncModelTargetService``, which cover
the create, poll, download and delete lifecycle for standard and
advanced Model Target datasets.

The clients authenticate with OAuth2 client credentials and reuse the
returned bearer token until it expires.  Typed request structures
describe the models, guide views and State-Based Model Target
configuration which Vuforia accepts, and the Model Target error envelope
is parsed into public exceptions.

Closes #3119.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: adamtheturtle

conftest.py

@@ -61,6 +61,16 @@ def fixture_mock_vws(
     monkeypatch.setenv(name="VWS_CLIENT_ACCESS_KEY", value=client_access_key)
     monkeypatch.setenv(name="VWS_CLIENT_SECRET_KEY", value=client_secret_key)
     monkeypatch.setenv(name="VWS_DATABASE_ID", value=database_id)
+    # The mock accepts one hard-coded pair of Model Target Web API OAuth2
+    # credentials, which it does not expose.
+    monkeypatch.setenv(
+        name="VWS_MODEL_TARGET_CLIENT_ID",
+        value="client-id",
+    )
+    monkeypatch.setenv(
+        name="VWS_MODEL_TARGET_CLIENT_SECRET",
+        value="client-secret",
+    )
     # We use a low processing time so that tests run quickly.
     with MockVWS(processing_time_seconds=0.2) as mock:
         mock.add_cloud_database(cloud_database=database)

docs/source/api-reference.rst

@@ -17,6 +17,18 @@ API Reference
    :undoc-members:
    :members:
 
+.. automodule:: vws.model_target_service
+   :undoc-members:
+   :members:
+
+.. automodule:: vws.async_model_target_service
+   :undoc-members:
+   :members:
+
+.. automodule:: vws.model_target_datasets
+   :undoc-members:
+   :members:
+
 .. automodule:: vws.reports
    :undoc-members:
    :members:

docs/source/exceptions.rst

@@ -28,6 +28,15 @@ CloudRecoService exceptions
    :inherited-members: Exception
    :exclude-members: errno, filename, filename2, strerror
 
+ModelTargetService exceptions
+-----------------------------
+
+.. automodule:: vws.exceptions.model_target_exceptions
+   :members:
+   :show-inheritance:
+   :inherited-members: Exception
+   :exclude-members: errno, filename, filename2, strerror
+
 Custom exceptions
 -----------------
 

docs/source/index.rst

@@ -110,6 +110,82 @@ The report is generated in the background, and the URL it is served from expires
    # This database has no targets, so nothing has been recognized.
    assert not reco_counts_by_target_id
 
+Model Targets
+-------------
+
+Vuforia generates Model Target datasets from CAD models.
+This uses OAuth2 client credentials, which are separate from the VWS server keys.
+
+Dataset generation happens in the background, and the generated dataset is downloaded as a zip file.
+
+.. clear-namespace
+
+.. code-block:: python
+
+   """Generate a Model Target dataset and download it."""
+
+   import os
+
+   from vws import ModelTargetService
+   from vws.model_target_datasets import (
+       CadDataFormat,
+       GuideViewPosition,
+       ModelTargetDatasetType,
+       ModelTargetModel,
+       ModelTargetView,
+   )
+   from vws.reports import ModelTargetDatasetStatuses
+
+   client_id = os.environ["VWS_MODEL_TARGET_CLIENT_ID"]
+   client_secret = os.environ["VWS_MODEL_TARGET_CLIENT_SECRET"]
+
+   model_target_client = ModelTargetService(
+       client_id=client_id,
+       client_secret=client_secret,
+   )
+
+   model = ModelTargetModel(
+       name="my_model",
+       cad_data_url="https://example.com/my_model.zip",
+       cad_data_format=CadDataFormat.ZIP,
+       views=[
+           ModelTargetView(
+               name="front",
+               guide_view_position=GuideViewPosition(
+                   rotation=[0.0, 0.0, 0.0, 1.0],
+                   translation=[0.0, 0.0, 1.0],
+               ),
+           ),
+       ],
+   )
+
+   dataset_uuid = model_target_client.create_dataset(
+       name="my_dataset",
+       target_sdk="11.0",
+       models=[model],
+       dataset_type=ModelTargetDatasetType.STANDARD,
+   )
+
+   report = model_target_client.wait_for_dataset_generated(
+       dataset_uuid=dataset_uuid,
+       dataset_type=ModelTargetDatasetType.STANDARD,
+   )
+
+   assert report.status == ModelTargetDatasetStatuses.DONE
+
+   dataset = model_target_client.download_dataset(
+       dataset_uuid=dataset_uuid,
+       dataset_type=ModelTargetDatasetType.STANDARD,
+   )
+
+   # The dataset is a zip file.
+   assert dataset.startswith(b"PK")
+
+   model_target_client.delete_dataset(
+       dataset_uuid=dataset_uuid,
+       dataset_type=ModelTargetDatasetType.STANDARD,
+   )
+
 Testing
 -------
 

newsfragments/3119.change.rst

@@ -0,0 +1,2 @@
+Add support for the Model Target Web API.
+``ModelTargetService`` and ``AsyncModelTargetService`` create standard and advanced Model Target datasets, wait for them to be generated, download them and delete them.

pyproject.toml

@@ -322,14 +322,26 @@ exclude = [ ".venv" ]
 # Ideally we would limit the paths to the source code where we want to ignore names,
 # but Vulture does not enable this.
 ignore_names = [
+    # Model Target model option values which this library does not use
+    # itself, from vws.model_target_datasets
+    "ADAPTIVE",
+    "ALWAYS",
+    "AR_CONTROLLER",
     # Public API classes imported by users from vws.transports
     "AsyncHTTPXTransport",
+    "AUTO",
     # Sphinx
     "autoclass_content",
     "autoclass_content",
     "autodoc_member_order",
+    "CAR",
     "copybutton_exclude",
+    "DAE",
+    "DEFAULT",
+    "DYNAMIC",
     "extensions",
+    "FALSE",
+    "FBX",
     # pytest fixtures - we name fixtures like this for this purpose
     "fixture_*",
     "html_show_copyright",
@@ -340,25 +352,34 @@ ignore_names = [
     "html_title",
     "htmlhelp_basename",
     "HTTPXTransport",
+    "IGES",
     "intersphinx_mapping",
     "language",
     "linkcheck_ignore",
     "linkcheck_retries",
+    "LOW_FEATURE_OBJECTS",
     "master_doc",
+    "NEVER",
     "nitpick_ignore",
     "nitpicky",
+    "OBJ",
     "project_copyright",
+    "PVZ",
     "pygments_style",
     # pytest configuration
     "pytest_collect_file",
     "pytest_plugins",
     "rst_prolog",
+    "SCAN",
     "source_suffix",
     "spelling_word_list_filename",
+    "STATIC",
+    "STL",
     "templates_path",
     "towncrier_draft_autoversion_mode",
     "towncrier_draft_include_empty",
     "towncrier_draft_working_directory",
+    "VRML",
     "warning_is_error",
 ]
 

spelling_private_dict.txt

@@ -11,6 +11,7 @@ LicenseCheckFailed
 MatchProcessing
 MaxNumResultsOutOfRange
 MetadataTooLarge
+OAuth
 OopsAnErrorOccurredPossiblyBadName
 OopsAnErrorOccurredPossiblyBadNameError
 ProjectHasNoApiAccess
@@ -33,6 +34,7 @@ args
 ascii
 async
 asyncio
+balancer
 beartype
 bool
 boolean
@@ -71,6 +73,7 @@ json
 keyring
 kib
 kwargs
+lifecycle
 linters
 linting
 login

src/vws/__init__.py

@@ -1,17 +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",
 ]