Add vws generate-vumark command

.github/workflows/release.yml

@@ -200,6 +200,8 @@ jobs:
             spec: bin/vuforia-cloud-reco.py
           - name: vws-linux
             spec: bin/vuforia-web-services.py
+          - name: vumark-linux
+            spec: bin/vumark.py
 
     permissions:
       contents: write
@@ -348,12 +350,24 @@ jobs:
           upload_exe_with_name: vws-windows
           clean_checkout: false
 
+      - name: Create Windows binary for VuMark generation
+        uses: sayyid5416/pyinstaller@v1
+        with:
+          python_ver: '3.13'
+          pyinstaller_ver: ==6.12.0
+          spec: bin/vumark.py
+          requirements: requirements.txt
+          options: --onefile, --name "vumark-windows"
+          upload_exe_with_name: vumark-windows
+          clean_checkout: false
+
       - name: Upload Windows binaries to release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |-
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vws-windows.exe --clobber
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vuforia-cloud-reco-windows.exe --clobber
+          gh release upload ${{ needs.build.outputs.new_tag }} dist/vumark-windows.exe --clobber
 
   build-macos:
     name: Build macOS binaries
@@ -408,12 +422,24 @@ jobs:
           upload_exe_with_name: vws-macos
           clean_checkout: false
 
+      - name: Create macOS binary for VuMark generation
+        uses: sayyid5416/pyinstaller@v1
+        with:
+          python_ver: '3.13'
+          pyinstaller_ver: ==6.12.0
+          spec: bin/vumark.py
+          requirements: requirements.txt
+          options: --onefile, --name "vumark-macos"
+          upload_exe_with_name: vumark-macos
+          clean_checkout: false
+
       - name: Upload macOS binaries to release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |-
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vws-macos --clobber
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vuforia-cloud-reco-macos --clobber
+          gh release upload ${{ needs.build.outputs.new_tag }} dist/vumark-macos --clobber
 
   publish-to-winget:
     name: Publish to WinGet
@@ -423,6 +449,9 @@ jobs:
       contents: read
 
     steps:
+      # The first PR for a new package ID must be created manually on
+      # microsoft/winget-pkgs. We intentionally do not add vumark here yet.
+      # Tracked in https://github.com/VWS-Python/vws-cli/issues/1984.
       - uses: vedantmgoyal9/winget-releaser@v2
         with:
           identifier: VWSPython.vws-cli

README.rst

@@ -69,6 +69,12 @@ To use ``vuforia-cloud-reco``:
 
    $ docker run --rm --entrypoint vuforia-cloud-reco "ghcr.io/vws-python/vws-cli" --help
 
+To use ``vumark``:
+
+.. code-block:: console
+
+   $ docker run --rm --entrypoint vumark "ghcr.io/vws-python/vws-cli" --help
+
 With winget (Windows)
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -92,6 +98,11 @@ Pre-built Windows binaries
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Download the Windows executables from the `latest release`_ and place them in a directory on your ``PATH``.
+The filenames are:
+
+* ``vws-windows.exe``
+* ``vuforia-cloud-reco-windows.exe``
+* ``vumark-windows.exe``
 
 .. _latest release: https://github.com/VWS-Python/vws-cli/releases/latest
 

bin/vumark.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+
+"""Run VuMark generation CLI."""
+
+from vws_cli.vumark import generate_vumark
+
+generate_vumark()

docs/source/commands.rst

@@ -8,3 +8,6 @@ Commands
 .. click:: vws_cli.query:vuforia_cloud_reco
   :prog: vuforia-cloud-reco
   :show-nested:
+
+.. click:: vws_cli.vumark:generate_vumark
+  :prog: vumark

docs/source/install.rst

@@ -61,6 +61,13 @@ To use ``vuforia-cloud-reco``:
 
    $ docker run --rm --entrypoint vuforia-cloud-reco "|docker-image|" --help
 
+To use ``vumark``:
+
+.. code-block:: console
+   :substitutions:
+
+   $ docker run --rm --entrypoint vumark "|docker-image|" --help
+
 With winget (Windows)
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -83,11 +90,18 @@ Pre-built Linux (x86) binaries
        chmod +x /usr/local/bin/vws
    $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vuforia-cloud-reco-linux" -o /usr/local/bin/vuforia-cloud-reco &&
        chmod +x /usr/local/bin/vuforia-cloud-reco
+   $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vumark-linux" -o /usr/local/bin/vumark &&
+       chmod +x /usr/local/bin/vumark
 
 Pre-built Windows binaries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Download the Windows executables from the `latest release`_ and place them in a directory on your ``PATH``.
+The filenames are:
+
+* ``vws-windows.exe``
+* ``vuforia-cloud-reco-windows.exe``
+* ``vumark-windows.exe``
 
 .. _latest release: https://github.com/VWS-Python/vws-cli/releases/latest
 
@@ -101,13 +115,16 @@ Pre-built macOS (ARM) binaries
        chmod +x /usr/local/bin/vws
    $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vuforia-cloud-reco-macos" -o /usr/local/bin/vuforia-cloud-reco &&
        chmod +x /usr/local/bin/vuforia-cloud-reco
+   $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vumark-macos" -o /usr/local/bin/vumark &&
+       chmod +x /usr/local/bin/vumark
 
 You may need to remove the quarantine attribute to allow the binaries to run:
 
 .. code-block:: console
 
    $ xattr -d com.apple.quarantine /usr/local/bin/vws
    $ xattr -d com.apple.quarantine /usr/local/bin/vuforia-cloud-reco
+   $ xattr -d com.apple.quarantine /usr/local/bin/vumark
 
 Shell completion
 ~~~~~~~~~~~~~~~~

docs/source/release-process.rst

@@ -8,7 +8,9 @@ Outcomes
 * A new package on PyPI.
 * A new Homebrew recipe available to install.
 * A new Docker image on GitHub Container Registry.
-* New Winget packages available to install.
+* New binary assets attached to the GitHub release.
+* New Winget packages available to install for ``vws`` and
+  ``vuforia-cloud-reco``.
 
 Perform a Release
 ~~~~~~~~~~~~~~~~~
@@ -23,3 +25,11 @@ Perform a Release
       $ gh workflow run release.yml --repo "|github-owner|/|github-repository|"
 
 .. _Install GitHub CLI: https://cli.github.com/
+
+WinGet for ``vumark``
+~~~~~~~~~~~~~~~~~~~~~
+
+The first WinGet PR for a new package ID must be created manually.
+For ``vumark``, do this after the first release that contains
+``vumark-windows.exe``, then automation can be added for subsequent releases.
+This is tracked in `issue #1984 <https://github.com/VWS-Python/vws-cli/issues/1984>`_.

spelling_private_dict.txt

@@ -20,6 +20,8 @@ macOS
 metadata
 noqa
 num
+pdf
+png
 pragma
 pre
 pyperclip
@@ -31,10 +33,12 @@ reportMissingTypeStubs
 reportUnknownArgumentType
 reportUnknownMemberType
 reportUnknownVariableType
+svg
 typeshed
 ubuntu
 versioned
 vuforia
+vumark
 vwq
 vws
 winget

src/vws_cli/vumark.py

@@ -0,0 +1,151 @@
+"""``click`` command for VuMark generation."""
+
+import contextlib
+import sys
+from collections.abc import Iterator
+from enum import StrEnum, unique
+from pathlib import Path
+
+import click
+from beartype import beartype
+from vws import VuMarkService
+from vws.exceptions.base_exceptions import VWSError
+from vws.exceptions.custom_exceptions import ServerError
+from vws.exceptions.vws_exceptions import (
+    InvalidInstanceIdError,
+    TargetStatusNotSuccessError,
+    UnknownTargetError,
+)
+from vws.vumark_accept import VuMarkAccept
+
+from vws_cli import __version__
+from vws_cli._error_handling import get_error_message
+from vws_cli.options.credentials import (
+    server_access_key_option,
+    server_secret_key_option,
+)
+from vws_cli.options.targets import target_id_option
+from vws_cli.options.timeout import (
+    connection_timeout_seconds_option,
+    read_timeout_seconds_option,
+)
+from vws_cli.options.vws import base_vws_url_option
+
+
+@beartype
+@unique
+class VuMarkFormatChoice(StrEnum):
+    """Choices for the VuMark output format."""
+
+    PNG = "png"
+    SVG = "svg"
+    PDF = "pdf"
+
+
+_FORMAT_CHOICE_TO_ACCEPT: dict[VuMarkFormatChoice, VuMarkAccept] = {
+    VuMarkFormatChoice.PNG: VuMarkAccept.PNG,
+    VuMarkFormatChoice.SVG: VuMarkAccept.SVG,
+    VuMarkFormatChoice.PDF: VuMarkAccept.PDF,
+}
+
+
+@beartype
+@contextlib.contextmanager
+def _handle_vumark_exceptions() -> Iterator[None]:
+    """Show error messages and catch exceptions from ``VWS-Python``."""
+    error_message = ""
+
+    try:
+        yield
+    except (UnknownTargetError, TargetStatusNotSuccessError) as exc:
+        if isinstance(exc, UnknownTargetError):
+            error_message = f'Error: Target "{exc.target_id}" does not exist.'
+        else:
+            error_message = (
+                f'Error: The target "{exc.target_id}" is not in the success '
+                "state and cannot be used to generate a VuMark instance."
+            )
+    except (VWSError, ServerError) as exc:
+        if isinstance(exc, InvalidInstanceIdError):
+            error_message = "Error: The given instance ID is invalid."
+        else:
+            error_message = get_error_message(exc=exc)
+    else:
+        return
+
+    click.echo(message=error_message, err=True)
+    sys.exit(1)
+
+
+@click.command(name="vumark")
+@server_access_key_option
+@server_secret_key_option
+@target_id_option
+@click.option(
+    "--instance-id",
+    type=str,
+    required=True,
+    help="The instance ID to encode in the VuMark.",
+)
+@click.option(
+    "--format",
+    "format_choice",
+    type=click.Choice(choices=VuMarkFormatChoice, case_sensitive=False),
+    default=VuMarkFormatChoice.PNG.lower(),
+    help="The output format for the generated VuMark.",
+    show_default=True,
+)
+@click.option(
+    "--output",
+    "output_file_path",
+    type=click.Path(
+        dir_okay=False,
+        writable=True,
+        path_type=Path,
+    ),
+    required=True,
+    help="The path to write the generated VuMark to.",
+)
+@_handle_vumark_exceptions()
+@base_vws_url_option
+@connection_timeout_seconds_option
+@read_timeout_seconds_option
+@click.version_option(version=__version__)
+@beartype
+def generate_vumark(
+    *,
+    server_access_key: str,
+    server_secret_key: str,
+    target_id: str,
+    instance_id: str,
+    format_choice: VuMarkFormatChoice,
+    output_file_path: Path,
+    base_vws_url: str,
+    connection_timeout_seconds: float,
+    read_timeout_seconds: float,
+) -> None:
+    """Generate a VuMark instance.
+
+    \b
+    See
+    https://developer.vuforia.com/library/vuforia-engine/web-api/vumark-generation-web-api/
+    """
+    vumark_client = VuMarkService(
+        server_access_key=server_access_key,
+        server_secret_key=server_secret_key,
+        base_vws_url=base_vws_url,
+        request_timeout_seconds=(
+            connection_timeout_seconds,
+            read_timeout_seconds,
+        ),
+    )
+
+    accept = _FORMAT_CHOICE_TO_ACCEPT[format_choice]
+
+    vumark_data = vumark_client.generate_vumark_instance(
+        target_id=target_id,
+        instance_id=instance_id,
+        accept=accept,
+    )
+
+    output_file_path.write_bytes(data=vumark_data)

tests/conftest.py

@@ -5,7 +5,8 @@
 import pytest
 from beartype import beartype
 from mock_vws import MockVWS
-from mock_vws.database import CloudDatabase
+from mock_vws.database import CloudDatabase, VuMarkDatabase
+from mock_vws.target import VuMarkTarget
 from vws import VWS, CloudRecoService
 
 
@@ -35,6 +36,22 @@ def vws_client(mock_database: CloudDatabase) -> VWS:
     )
 
 
+@pytest.fixture(name="vumark_database")
+def fixture_vumark_database() -> Iterator[VuMarkDatabase]:
+    """Yield a mock ``VuMarkDatabase`` with one pre-created target."""
+    vumark_target = VuMarkTarget(name="test-vumark-target")
+    database = VuMarkDatabase(vumark_targets={vumark_target})
+    with MockVWS() as mock:
+        mock.add_vumark_database(vumark_database=database)
+        yield database
+
+
+@pytest.fixture(name="vumark_target")
+def fixture_vumark_target(vumark_database: VuMarkDatabase) -> VuMarkTarget:
+    """Return the pre-created ``VuMarkTarget`` in the database."""
+    return next(iter(vumark_database.not_deleted_targets))
+
+
 @pytest.fixture
 def cloud_reco_client(
     mock_database: CloudDatabase,