vws-python-mock 2026.8.26__tar.gz → 2026.9.6__tar.gz

{vws_python_mock-2026.8.26 → vws_python_mock-2026.9.6}/.github/workflows/test.yml

@@ -46,6 +46,7 @@ jobs:
           - tests/mock_vws/test_query.py::TestTargetStatusFailed
           - tests/mock_vws/test_query.py::TestDateFormats
           - tests/mock_vws/test_query.py::TestInactiveProject
+          - tests/mock_vws/test_query.py::TestTruncatedBody
           - tests/mock_vws/test_add_target.py::TestContentTypes
           - tests/mock_vws/test_add_target.py::TestMissingData
           - tests/mock_vws/test_add_target.py::TestWidth
@@ -85,7 +86,10 @@ jobs:
           - tests/mock_vws/test_get_duplicates.py
           - tests/mock_vws/test_get_target.py
           - tests/mock_vws/test_invalid_given_id.py
-          - tests/mock_vws/test_invalid_json.py::TestInvalidJSON::test_invalid_json
+          - tests/mock_vws/test_invalid_json.py::TestInvalidJSON::test_not_json
+          - tests/mock_vws/test_invalid_json.py::TestInvalidJSON::test_not_an_object
+          - tests/mock_vws/test_invalid_json.py::TestInvalidJSON::test_not_utf_8
+          - tests/mock_vws/test_invalid_json.py::TestInvalidJSON::test_empty_body
           - tests/mock_vws/test_invalid_json.py::TestInvalidJSON::test_invalid_json_with_skewed_time
           - tests/mock_vws/test_target_list.py
           - tests/mock_vws/test_reco_counts_report.py
@@ -101,11 +105,13 @@ jobs:
           - tests/mock_vws/test_update_target.py::TestImage::test_image_valid
           - tests/mock_vws/test_update_target.py::TestImage::test_bad_image_format_or_color_space
           - tests/mock_vws/test_update_target.py::TestImage::test_corrupted
+          - tests/mock_vws/test_update_target.py::TestImage::test_truncated
           - tests/mock_vws/test_update_target.py::TestImage::test_image_too_large
           - tests/mock_vws/test_update_target.py::TestImage::test_not_base64_encoded_processable
           - tests/mock_vws/test_update_target.py::TestImage::test_not_base64_encoded_not_processable
           - tests/mock_vws/test_update_target.py::TestImage::test_not_image
           - tests/mock_vws/test_update_target.py::TestImage::test_invalid_type
+          - tests/mock_vws/test_update_target.py::TestImage::test_rating_does_not_return_to_minus_one
           - tests/mock_vws/test_update_target.py::TestImage::test_rating_can_change
           - tests/mock_vws/test_update_target.py::TestTargetName::test_name_valid
           - tests/mock_vws/test_update_target.py::TestTargetName::test_name_invalid
@@ -115,16 +121,19 @@ jobs:
           - tests/mock_vws/test_update_target.py::TestUpdate
           - tests/mock_vws/test_update_target.py::TestWidth
           - tests/mock_vws/test_update_target.py::TestInactiveProject
-          - tests/mock_vws/test_requests_mock_usage.py
-          - tests/mock_vws/test_respx_mock_usage.py
-          - tests/mock_vws/test_flask_app_usage.py
           - tests/mock_vws/test_model_target_generation_failure.py
           - tests/mock_vws/test_model_target_generation_warning.py
+          - tests/mock_vws/test_model_target_failure_response.py
           - tests/mock_vws/test_model_target_training_allowance.py
           - tests/mock_vws/test_model_target_web_api.py
+          - tests/mock_vws/test_model_target_retries.py
           - tests/mock_vws/test_vumark_generation_api.py
           - tests/mock_vws/test_vumark_generation_failure.py
           - tests/mock_vws/test_target_validators.py
+          - tests/mock_vws/test_requests_mock_usage.py
+          - tests/mock_vws/test_respx_mock_usage.py
+          - tests/mock_vws/test_httpx2_mock_usage.py
+          - tests/mock_vws/test_flask_app_usage.py
           - tests/mock_vws/test_healthcheck.py
           - tests/mock_vws/test_docker.py
           - README.rst
@@ -151,8 +160,11 @@ jobs:
           # See the "CI Setup" document for details of how this was set up.
           ci/decrypt_secret.sh
           tar xvf "${HOME}"/secrets/secrets.tar
-          # Matrix jobs are 0-based; only secrets 0-99 exist. Wrap for overflow
-          # (e.g. docs/ at index 100 after the suite grew past 100 patterns).
+          # Matrix jobs are 0-based; only secrets 0-99 exist, so patterns
+          # past index 99 wrap and share a database with an earlier job.
+          # The ci_pattern list is therefore ordered so that every pattern
+          # from index 100 on is one which never parametrises over the Real
+          # Vuforia backend, and so never uses these credentials.
           SECRET_INDEX=$((JOB_INDEX % 100))
           cp "./ci_secrets/vuforia_secrets_${SECRET_INDEX}.env" ./vuforia_secrets.env
 

{vws_python_mock-2026.8.26 → vws_python_mock-2026.9.6}/CHANGELOG.rst

@@ -3,6 +3,41 @@ Changelog
 
 .. towncrier release notes start
 
+2026.09.06
+----------
+
+- Add ``MockVWS.set_target_recognition_counts`` and a matching target manager endpoint for the Flask and Docker mock, for setting the recognition counts which the target summary report and the reco counts report show for a target.
+  A reco counts report now has a row for each target with recognitions in the requested month, and the recognition counts and recognition threshold of a cloud database are kept when the database is created in the Flask and Docker mock.
+
+- Order Query API and ``GET /duplicates/{target_id}`` results by match score, with the best match first, as the real Query API does.
+  Matches with equal scores keep the existing upload date and then target ID order.
+
+  Image matchers now return a score, or ``None`` for no match, rather than a ``bool``.
+  ``StructuralSimilarityMatcher`` returns the images' SSIM score, and ``ExactMatcher`` gives every match the same score.
+  A custom ``query_match_checker`` or ``duplicate_match_checker`` which returns a ``bool`` now raises a ``TypeError``; return a score, such as ``1.0``, for a match and ``None`` for no match instead.
+  The mock's ranking is its matcher's opinion, not Vuforia's proprietary one, so the mock's order still need not agree with the real Query API's order.
+
+- Respond, rather than failing to respond, to a request body which is not UTF-8 and to a query request whose ``multipart/form-data`` body ends before its closing boundary.
+
+- Return a ``400`` response which names the offending field and the accepted values, rather than a ``500`` response, when the target manager container is given an invalid cloud database or VuMark database to create.
+  Return a ``404`` response, rather than a ``500`` response, when the target manager container is asked to add a target to a database which does not exist.
+
+- Say which claims about the real Vuforia Web Services the mock has not had checked against them. :doc:`unverified-behavior` lists each such claim and what would verify it, and ``differences-to-vws`` marks the unverified assumptions among its deliberate differences.
+
+- Return a ``BadImage`` response, rather than failing to respond, when an image given to the Target API is truncated before the end of its image data.
+
+- ``MockVWS`` now intercepts ``httpx2`` requests, synchronous and asynchronous, alongside ``requests`` and ``httpx``. The ``httpx2`` path uses native ``httpx2`` requests and responses, and does not need ``httpx2.alias_httpx()``.
+
+- Fix nested ``MockVWS`` instances on the ``httpx`` backend: an inner mock is now the only one which answers while it is running, matching the ``requests`` and ``httpx2`` backends. Previously the outer mock kept answering and requests to the inner mock's URL were refused.
+
+- Return a response, rather than raising an uncaught ``JSONDecodeError``, when an empty body is given to a VWS endpoint which takes a JSON body.
+  As real Vuforia does, ``POST /targets`` and ``PUT /targets/<target_id>`` now return a 500 ``Fail`` response, the reco counts report endpoint returns a 400 ``Fail`` response, and the VuMark instance generation endpoint returns a 400 ``BadRequest`` response.
+
+2026.08.26.1
+------------
+
+- Add configurable Model Target HTTP failure responses for selected dataset request phases.
+
 2026.08.26
 ----------
 

{vws_python_mock-2026.8.26/src/vws_python_mock.egg-info → vws_python_mock-2026.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vws-python-mock
-Version: 2026.8.26
+Version: 2026.9.6
 Summary: A mock for the Vuforia Web Services (VWS) API.
 Author-email: Adam Dangoor <adamdangoor@gmail.com>
 License-Expression: MIT
@@ -20,9 +20,11 @@ License-File: LICENSE
 Requires-Dist: beartype>=0.22.9
 Requires-Dist: flask>=3.0.3
 Requires-Dist: httpx>=0.27.0
+Requires-Dist: httpx2>=2.12
 Requires-Dist: numpy>=2.4.4
 Requires-Dist: opencv-contrib-python-headless>=5.0.0.93
 Requires-Dist: pillow>=12.2.0
+Requires-Dist: pydantic>=2.6
 Requires-Dist: pydantic-settings>=2.6.1
 Requires-Dist: pyteenybrisque>=0.1.1
 Requires-Dist: requests>=2.32.3
@@ -35,37 +37,38 @@ Provides-Extra: dev
 Requires-Dist: actionlint-py==1.7.12.24; extra == "dev"
 Requires-Dist: check-manifest==0.51; extra == "dev"
 Requires-Dist: check-wheel-contents==0.6.3; extra == "dev"
-Requires-Dist: coverage==7.15.4; extra == "dev"
+Requires-Dist: coverage==7.16.0; extra == "dev"
 Requires-Dist: deptry==0.25.1; extra == "dev"
 Requires-Dist: dirty-equals==0.11; extra == "dev"
 Requires-Dist: doc8==2.0.0; extra == "dev"
-Requires-Dist: doccmd==2026.8.16; extra == "dev"
+Requires-Dist: doccmd==2026.8.30.1; extra == "dev"
 Requires-Dist: docker==7.2.0; extra == "dev"
 Requires-Dist: freezegun==1.5.5; extra == "dev"
 Requires-Dist: furo==2025.12.19; extra == "dev"
+Requires-Dist: hadolint-coatl==2.15.1; extra == "dev"
 Requires-Dist: interrogate==1.7.0; extra == "dev"
 Requires-Dist: mypy[faster-cache]==2.3.1; extra == "dev"
-Requires-Dist: mypy-strict-kwargs==2026.7.19.1; extra == "dev"
-Requires-Dist: no-defaults==2.1.0; extra == "dev"
-Requires-Dist: prek==0.4.14; extra == "dev"
+Requires-Dist: mypy-strict-kwargs==2026.8.25.1; extra == "dev"
+Requires-Dist: no-defaults==2.3.0; extra == "dev"
+Requires-Dist: prek==0.5.1; extra == "dev"
 Requires-Dist: pydocstringformatter==1.0.0; extra == "dev"
 Requires-Dist: pydocstyle==6.3; extra == "dev"
-Requires-Dist: pylint[spelling]==4.0.7; extra == "dev"
+Requires-Dist: pylint[spelling]==4.0.8; extra == "dev"
 Requires-Dist: pylint-per-file-ignores==3.2.1; extra == "dev"
-Requires-Dist: pyproject-fmt==2.28.0; extra == "dev"
+Requires-Dist: pyproject-fmt==2.29.2; extra == "dev"
 Requires-Dist: pyrefly==1.2.0; extra == "dev"
 Requires-Dist: pyright==1.1.411; extra == "dev"
 Requires-Dist: pyroma==5.0.1; extra == "dev"
 Requires-Dist: pytest==9.1.1; extra == "dev"
 Requires-Dist: pytest-beartype-tests==2026.8.16; extra == "dev"
-Requires-Dist: pytest-partition-check==2026.8.10.1; extra == "dev"
+Requires-Dist: pytest-partition-check==2026.8.23; extra == "dev"
 Requires-Dist: pytest-retry==1.7.0; extra == "dev"
 Requires-Dist: pytest-xdist==3.8.0; extra == "dev"
 Requires-Dist: pyyaml==6.0.3; extra == "dev"
 Requires-Dist: requests-mock-flask==2026.8.16; extra == "dev"
-Requires-Dist: ruff==0.16.4; extra == "dev"
+Requires-Dist: ruff==0.16.5; extra == "dev"
 Requires-Dist: shellcheck-py==0.11.0.1; extra == "dev"
-Requires-Dist: shfmt-py==4.0.0; extra == "dev"
+Requires-Dist: shfmt-py==4.1.0; extra == "dev"
 Requires-Dist: sphinx==9.1.0; extra == "dev"
 Requires-Dist: sphinx-copybutton==0.5.2; extra == "dev"
 Requires-Dist: sphinx-lint==1.0.2; extra == "dev"
@@ -76,22 +79,22 @@ Requires-Dist: sphinx-toolbox==4.3.0; extra == "dev"
 Requires-Dist: sphinxcontrib-httpdomain==2.0.0; extra == "dev"
 Requires-Dist: sphinxcontrib-spelling==8.0.2; extra == "dev"
 Requires-Dist: sphinxcontrib-towncrier==0.5.0a0; extra == "dev"
-Requires-Dist: strict-kwargs==2026.8.16; extra == "dev"
+Requires-Dist: strict-kwargs==2026.8.28.post2; extra == "dev"
 Requires-Dist: sybil==10.1.0; extra == "dev"
 Requires-Dist: tenacity==9.1.4; extra == "dev"
 Requires-Dist: towncrier==25.8.0; extra == "dev"
-Requires-Dist: ty==0.0.73; extra == "dev"
-Requires-Dist: types-docker==7.2.0.20260819; extra == "dev"
+Requires-Dist: ty==0.0.77; extra == "dev"
+Requires-Dist: types-docker==7.2.0.20260827; extra == "dev"
 Requires-Dist: types-pyyaml==6.0.12.20260815; extra == "dev"
 Requires-Dist: types-requests==2.33.0.20260712; extra == "dev"
 Requires-Dist: urllib3==2.7.0; extra == "dev"
-Requires-Dist: vale==3.17.1.0; extra == "dev"
+Requires-Dist: vale==3.19.0.0; extra == "dev"
 Requires-Dist: vulture==2.16; extra == "dev"
-Requires-Dist: vws-python==2026.8.14; extra == "dev"
-Requires-Dist: vws-test-fixtures==2026.8.23; extra == "dev"
-Requires-Dist: vws-web-tools==2026.8.7; extra == "dev"
+Requires-Dist: vws-python==2026.8.26; extra == "dev"
+Requires-Dist: vws-test-fixtures==2026.8.26; extra == "dev"
+Requires-Dist: vws-web-tools==2026.8.27; extra == "dev"
 Requires-Dist: yamlfix==1.19.1; extra == "dev"
-Requires-Dist: zizmor==1.29.0; extra == "dev"
+Requires-Dist: zizmor==1.30.0; extra == "dev"
 Provides-Extra: release
 Requires-Dist: check-wheel-contents==0.6.3; extra == "release"
 Requires-Dist: towncrier==25.8.0; extra == "release"
@@ -110,7 +113,7 @@ Mock for the Vuforia Web Services (VWS) API, the Vuforia Web Query API, and the
 Mocking calls made to Vuforia
 ------------------------------
 
-``MockVWS`` intercepts requests made with `requests`_ or `httpx`_.
+``MockVWS`` intercepts requests made with `requests`_, `httpx`_ or `HTTPX2`_.
 
 .. code-block:: shell
 
@@ -150,10 +153,30 @@ This requires Python |minimum-python-version|\+.
         # This will use the Vuforia mock.
         httpx.get(url="https://vws.vuforia.com/summary", timeout=30)
 
+``MockVWS`` also intercepts `HTTPX2`_ requests, with no need for ``httpx2.alias_httpx()``:
+
+.. code-block:: python
+
+    """Make a request to the Vuforia Web Services API mock using httpx2."""
+
+    import httpx2
+
+    from mock_vws import MockVWS
+    from mock_vws.database import CloudDatabase
+
+    with MockVWS() as mock:
+        database = CloudDatabase()
+        mock.add_cloud_database(cloud_database=database)
+        # This will use the Vuforia mock.
+        httpx2.get(url="https://vws.vuforia.com/summary", timeout=30)
+
+Asynchronous ``httpx`` and `HTTPX2`_ clients are intercepted as well.
+
 By default, an exception will be raised if any requests to unmocked addresses are made.
 
 .. _requests: https://pypi.org/project/requests/
 .. _httpx: https://pypi.org/project/httpx/
+.. _HTTPX2: https://httpx2.pydantic.dev/
 
 Using Docker to mock calls to Vuforia from any language
 -------------------------------------------------------

{vws_python_mock-2026.8.26 → vws_python_mock-2026.9.6}/README.rst

@@ -11,7 +11,7 @@ Mock for the Vuforia Web Services (VWS) API, the Vuforia Web Query API, and the
 Mocking calls made to Vuforia
 ------------------------------
 
-``MockVWS`` intercepts requests made with `requests`_ or `httpx`_.
+``MockVWS`` intercepts requests made with `requests`_, `httpx`_ or `HTTPX2`_.
 
 .. code-block:: shell
 
@@ -51,10 +51,30 @@ This requires Python |minimum-python-version|\+.
         # This will use the Vuforia mock.
         httpx.get(url="https://vws.vuforia.com/summary", timeout=30)
 
+``MockVWS`` also intercepts `HTTPX2`_ requests, with no need for ``httpx2.alias_httpx()``:
+
+.. code-block:: python
+
+    """Make a request to the Vuforia Web Services API mock using httpx2."""
+
+    import httpx2
+
+    from mock_vws import MockVWS
+    from mock_vws.database import CloudDatabase
+
+    with MockVWS() as mock:
+        database = CloudDatabase()
+        mock.add_cloud_database(cloud_database=database)
+        # This will use the Vuforia mock.
+        httpx2.get(url="https://vws.vuforia.com/summary", timeout=30)
+
+Asynchronous ``httpx`` and `HTTPX2`_ clients are intercepted as well.
+
 By default, an exception will be raised if any requests to unmocked addresses are made.
 
 .. _requests: https://pypi.org/project/requests/
 .. _httpx: https://pypi.org/project/httpx/
+.. _HTTPX2: https://httpx2.pydantic.dev/
 
 Using Docker to mock calls to Vuforia from any language
 -------------------------------------------------------

{vws_python_mock-2026.8.26 → vws_python_mock-2026.9.6}/conftest.py

@@ -28,5 +28,18 @@ def pytest_set_filtered_exceptions() -> tuple[type[Exception], ...]:
 
     This is for ``pytest-retry``.
     The configuration for retries is in ``pyproject.toml``.
+
+    ``pytest-retry`` treats this as an allowlist: a test which fails
+    with anything else is not retried, whatever ``retries`` is set to.
+    That is deliberate, because widening it to ``AssertionError`` would
+    retry every failing assertion in the suite ten times.
+
+    The consequence is that a test which turns a response into an
+    ``AssertionError`` itself, rather than letting an exception out of
+    the client, is never retried here. The Model Target Web API tests
+    assert on ``requests.Response`` objects and so are in that
+    position; they get their own, narrower policy, applied before the
+    assertion, in
+    :py:mod:`tests.mock_vws.utils.model_target_retries`.
     """
     return TRANSIENT_VWS_EXCEPTIONS

{vws_python_mock-2026.8.26 → vws_python_mock-2026.9.6}/docs/source/basic-example.rst

@@ -1,4 +1,4 @@
-``MockVWS`` intercepts requests to Vuforia made with `requests`_ or `httpx`_.
+``MockVWS`` intercepts requests to Vuforia made with `requests`_, `httpx`_ or `HTTPX2`_.
 
 .. code-block:: python
 
@@ -47,3 +47,4 @@ See :ref:`mock-api-reference` for details of what can be changed and how.
 
 .. _requests: https://pypi.org/project/requests/
 .. _httpx: https://pypi.org/project/httpx/
+.. _HTTPX2: https://httpx2.pydantic.dev/

{vws_python_mock-2026.8.26 → vws_python_mock-2026.9.6}/docs/source/contributing.rst

@@ -124,6 +124,42 @@ Use the following custom ``pytest`` options to skip some tests:
    --skip-docker_build_tests
                          Skip tests for building Docker images
 
+Verifying signed Model Target requests
+--------------------------------------
+
+Creating an advanced Model Target dataset with a state-based configuration or a standard dataset with inline CAD data is a "signed" request: the real Vuforia signs the trained dataset, and each signing consumes the account's Model Target training allowance.
+The allowance is small (roughly 20 signings), it is shared by every CI job and every concurrent run, and it cannot be raised or reset.
+Verifying signed requests on every run exhausted the allowance within hours and then made every CI run fail with ``TRAINING_ALLOWANCE_EXCEEDED``.
+
+The signed test cases therefore run against the mock backends on every run, but are skipped against the real Vuforia by default.
+To verify them against the real Vuforia, for example after the allowance has recovered, opt in with:
+
+.. code-block:: text
+
+   --verify-model-target-signing
+                         Run signed Model Target dataset tests against
+                         the real Vuforia
+
+The equivalent unsigned requests (a standard dataset, or an advanced dataset without a state-based configuration) are far cheaper and are verified against the real Vuforia on every run.
+With enough traffic even unsigned dataset creation can be rejected with ``TRAINING_ALLOWANCE_EXCEEDED``; an unexpected allowance rejection is reported as an expected failure rather than a test failure, and the affected tests pass again automatically once the allowance recovers.
+
+Retrying transient real Model Target failures
+---------------------------------------------
+
+The load balancer in front of the real Model Target Web API sometimes answers a perfectly good request with a gateway error, or drops the connection.
+That is nothing to do with the contract under test, and a rerun of the same job passes, so a small number of retries is applied to requests which are safe to repeat.
+
+The policy is in ``tests/mock_vws/utils/model_target_retries.py``.
+It applies only while a test is running against the real Model Target backend, and only to ``GET`` requests: repeating a dataset creation can create a second dataset and can consume the account's Model Target training allowance, so mutating requests are sent exactly once.
+Three attempts are made, with an exponential backoff with jitter of up to ten seconds, using ``tenacity``.
+A request which still fails transiently on the last attempt is not hidden: the response is returned as it is, so the assertion reports the real status and body.
+
+The mock backends are unaffected, so tests which configure a mock to answer with a 5xx still get that response immediately.
+
+This is separate from the repository-wide ``pytest-retry`` configuration, which retries a test only when it fails with one of the exception types returned by ``pytest_set_filtered_exceptions`` in the top level ``conftest.py``.
+The Model Target tests assert on ``requests.Response`` objects, so a gateway error reaches ``pytest-retry`` as an ``AssertionError`` and is never retried by it.
+Widening that allowlist would retry every failing assertion in the suite, which is why the Model Target policy sits in the request helper instead, before the assertion.
+
 Documentation
 -------------
 
@@ -154,6 +190,8 @@ This is because the target goes into a processing state.
 ``image`` is required for ``POST /targets``, but it is documented as not mandatory.
 
 The ``tracking_rating`` returned by ``GET /targets/<target_id>`` can be -1.
+This happens only while a newly uploaded target is processing, and it lasts for about a second.
+Updating a target returns it to the processing state but does not return the rating to -1; the new image's rating is reported straight away.
 
 The database summary from ``GET /summary`` has multiple undocumented return fields.
 

{vws_python_mock-2026.8.26 → vws_python_mock-2026.9.6}/docs/source/differences-to-vws.rst

@@ -4,12 +4,21 @@ Differences between the mock and the real Vuforia Web Services
 The mock attempts to be realistic, but it was built without access to the source code of the original API.
 Please report any issues `here <https://github.com/VWS-Python/vws-python-mock/issues>`__.
 
+This document mixes three kinds of statement, and it says which is which:
+
+* A deliberate difference, where the mock does something else on purpose.
+  The image matchers are one.
+* Behavior which the mock does not implement.
+* An unverified assumption, where the mock follows Vuforia's documentation and nobody has checked that the documentation is accurate.
+  Each of these carries a note pointing at its entry in :doc:`unverified-behavior`, which says what would verify it.
+  These are the ones which can bite: the mock passes its tests, your tests pass, and the divergence appears in production.
+
 Image matching
 --------------
 
 Vuforia's image matching is proprietary and we do not intend to accurately copy it.
 Instead, we aim for simple algorithms which are fast and are good enough for testing purposes.
-The image matcher is configurable, using :paramref:`~mock_vws.MockVWS.match_checker`.
+The image matchers are configurable, using :paramref:`~mock_vws.MockVWS.query_match_checker` and :paramref:`~mock_vws.MockVWS.duplicate_match_checker`.
 
 Speed and summary accuracy
 --------------------------
@@ -23,7 +32,22 @@ In the real Vuforia Web Services, the processing stage takes varying lengths of
 The database summary in the real Vuforia Web Services takes some time to account for images and recognitions.
 Sometimes the real summary skips image states such as the processing state.
 The mock is accurate immediately with regards to images.
+
 The mock does not count recognitions.
+Real Vuforia's recognition counts lag behind its queries by far longer than a
+test runs, so a query in the mock does not change any count either.
+Set the counts you want to see instead:
+:paramref:`mock_vws.database.CloudDatabase.total_recos`,
+:paramref:`mock_vws.database.CloudDatabase.current_month_recos`,
+:paramref:`mock_vws.database.CloudDatabase.previous_month_recos` and
+:paramref:`mock_vws.database.CloudDatabase.reco_threshold` for the database
+summary report, and
+:meth:`mock_vws.MockVWS.set_target_recognition_counts` for the counts of a
+target, which the target summary report and the reco counts report show.
+Targets are created by API requests, so their counts are set after the target
+is created.
+The Flask and Docker mock has an equivalent target manager endpoint, described
+in :doc:`docker`.
 
 Image quality and ratings
 -------------------------
@@ -32,6 +56,10 @@ Targets are assigned a rating between 0 and 5 of how good they are for tracking
 In the mock this is calculated from the image quality, differently to how Vuforia does this.
 This is customizable with the :paramref:`~mock_vws.MockVWS.target_tracking_rater` parameter.
 
+A target which is being processed after an upload reports a rating of -1 for a short time, and then the image's rating, while it is still processing.
+An update does not start a new -1 window: it returns the target to the processing state and reports the new image's rating straight away.
+The mock does the same, in proportion to :paramref:`~mock_vws.MockVWS.processing_time_seconds` rather than to the real timings.
+
 Image targets which are not suited to detection are given 'failed' statuses.
 The criteria for these images is not defined by the Vuforia documentation.
 The mock is more forgiving than the real Vuforia Web Services.
@@ -41,14 +69,14 @@ Result ordering
 ---------------
 
 The real Query API orders results by match score, with the best match first.
-The mock has no match score, so it cannot reproduce that order.
-Instead, the mock orders the targets it returns by upload date and then by target ID.
-This makes repeated runs agree with each other, but it means that the mock's order is not a ranking.
-Do not rely on the first result of a mock query being the best match.
+The mock does the same, with the score which its image matcher gives each match.
+That matcher is not Vuforia's, so the mock's ranking is not Vuforia's ranking.
+The order decides which results survive ``max_num_results``, and which result gets target data with ``include_target_data=top``.
 
-This affects which results survive ``max_num_results``, and which result gets target data with ``include_target_data=top``.
+Matches with the same score, which is every match of :class:`~mock_vws.image_matchers.ExactMatcher`, are ordered by upload date and then by target ID.
+The real Vuforia Web Services give no such guarantee.
 
-``GET /targets`` and ``GET /duplicates/{target_id}`` use the same order.
+``GET /duplicates/{target_id}`` is ordered by match score too, and ``GET /targets`` by upload date and then by target ID.
 The real Vuforia Web Services do not document an order for those endpoints.
 
 Matching recently deleted targets
@@ -111,7 +139,11 @@ NGINX Error cases
 
 Vuforia uses NGINX.
 This has error handling which is not duplicated in the mock.
-For example, Vuforia returns a 400 (``BAD REQUEST``) response if a header or cookie is given which is larger than 8 KiB.
+For example, Vuforia is documented as returning a 400 (``BAD REQUEST``) response if a header or cookie is given which is larger than 8 KiB.
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-nginx-oversized-header-or-cookie`
 
 Result codes
 ------------
@@ -127,11 +159,12 @@ These are:
 Request quota exhaustion
 ------------------------
 
-The mock returns ``RequestQuotaReached`` when a
-:class:`mock_vws.database.CloudDatabase` is created with
-``request_quota=0``. This behavior follows the public Vuforia documentation,
-but the response has not been verified against a real database with an
-exhausted quota.
+The mock returns ``RequestQuotaReached`` when a :class:`mock_vws.database.CloudDatabase` is created with ``request_quota=0``.
+This behavior follows the public Vuforia documentation.
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-request-quota-exhaustion`
 
 Request rate limits
 -------------------
@@ -141,11 +174,14 @@ endpoints in general, with 45 requests per second for
 ``GET /targets/{target_id}``, 10 requests per second for
 ``GET /duplicates/{target_id}``, and 1 request per minute for ``GET /targets``.
 
-The mock models these limits separately for each group of endpoints, but it
-applies no limit by default. The documented numbers have not been verified
-against a real database, and applying a limit of 1 request per minute to
-``GET /targets`` by default would break the tests of anything which uses the
-mock. Set ``request_rate_limits`` to
+The mock models these limits separately for each group of endpoints, but it applies no limit by default.
+Applying a limit of 1 request per minute to ``GET /targets`` by default would break the tests of anything which uses the mock.
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-request-rate-limits`
+
+Set ``request_rate_limits`` to
 :data:`mock_vws.request_rate_limits.DOCUMENTED_REQUEST_RATE_LIMITS` to apply
 the documented limits::
 
@@ -167,9 +203,11 @@ the documented limits::
 VWS endpoints together, and it is tracked separately from the per-endpoint
 limits.
 
-Vuforia also documents that ``GET /targets`` fails for databases with more than
-1 million images. The mock does not implement this, as the behavior is not
-reproducible against a test account.
+Vuforia also documents that ``GET /targets`` fails for databases with more than 1 million images, which the mock does not implement.
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-targets-over-one-million-images`
 
 Configurable Cloud Query failures
 ---------------------------------
@@ -178,7 +216,7 @@ The Vuforia Cloud Query API documents failure responses with JSON, arbitrary
 content, or no body. Use
 :paramref:`mock_vws.MockVWS.cloud_query_failure_response` to make every Cloud
 Query request return a particular documented failure shape through the
-in-process ``requests`` and ``httpx`` backends::
+in-process ``requests``, ``httpx`` and ``httpx2`` backends::
 
     from mock_vws import CloudQueryFailureResponse, MockVWS
 
@@ -196,11 +234,45 @@ The configured response bypasses normal Cloud Query validation and image
 matching. Omitting it preserves the normal successful-query behavior. This
 configuration is not supported by the Flask/Docker backend.
 
+Configurable Model Target failures
+----------------------------------
+
+Use :paramref:`mock_vws.MockVWS.model_target_failure_response` to return a
+particular HTTP failure from selected Model Target dataset request phases. The
+OAuth2 token request is still handled normally, so this exercises client
+behavior after successful token acquisition::
+
+    from mock_vws import (
+        MockVWS,
+        ModelTargetFailureResponse,
+        ModelTargetRequest,
+    )
+
+    failure = ModelTargetFailureResponse(
+        status_code=503,
+        headers={"Content-Type": "text/plain", "Retry-After": "10"},
+        body=b"Temporarily unavailable",
+        requests=frozenset({ModelTargetRequest.STATUS}),
+    )
+
+    with MockVWS(model_target_failure_response=failure):
+        # Model Target status calls return the configured response.
+        ...
+
+Omit ``requests`` to affect create, status, download, and delete requests.
+Other phases retain their normal behavior. This configuration works with
+the in-process ``requests``, ``httpx`` and ``httpx2`` backends and is not
+supported by the Flask/Docker backend.
+
 Other configurable result codes
 -------------------------------
 
-The mock also supports four other result codes which have not been verified
-against real databases in the corresponding states:
+The mock also supports four other result codes which come from Vuforia's result codes table rather than from a response which a real database gave:
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-additional-result-codes`
+
 
 * ``TargetQuotaReached`` is returned when adding a target to a
   :class:`mock_vws.database.CloudDatabase` which already contains
@@ -318,14 +390,15 @@ Real Vuforia uses ``userId:<numeric-user-id>`` where the numeric portion is per-
 Standard and advanced routes share datasets by UUID. Access to each route
 family is separated by its corresponding OAuth scope.
 
-Some Model Target Web API paths remain mock-only in
-``tests/mock_vws/test_model_target_web_api.py::TestAdditionalBehaviors``.
+Some Model Target Web API paths remain mock-only in ``tests/mock_vws/test_model_target_web_api.py::TestAdditionalBehaviors``.
 Downloads of still-processing datasets are mock-only because exercising the path against real Vuforia would require creating a dataset on every test run; the mock drives the processing window deterministically.
-A download request for a dataset which is not ready reports the dataset's
-training status. The mock reports ``not-started`` for the whole processing
-window, as real Vuforia does for a dataset which was just created, and
-``failed`` for a dataset whose generation failed. The name which real Vuforia
-reports for a failed dataset has not been observed.
+A download request for a dataset which is not ready reports the dataset's training status.
+The mock reports ``not-started`` for the whole processing window, as real Vuforia does for a dataset which was just created, and ``failed`` for a dataset whose generation failed.
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-model-target-failed-dataset-name`
+
 Some malformed State-Based Model Target configuration documents remain
 mock-only because real Vuforia returns an internal server error for them.
 
@@ -334,9 +407,24 @@ Reco counts reports
 
 The mock does not count recognitions, so a generated reco counts report
 contains only the ``target_id,reco_count`` header row, ending with a carriage
-return and a line feed.
+return and a line feed, until recognition counts are set on targets.
 That is what real Vuforia returns for a database with no recognitions.
-The mock returns the same report for the current month and the previous month.
+
+A report for the current month has a row for each target with a non-zero
+``current_month_recos``, and a report for the previous month has a row for
+each target with a non-zero ``previous_month_recos``.
+Each row ends with a carriage return and a line feed, as the header row does.
+The mock takes the counts when the report is requested, so counts which are
+set after that are not in that report.
+The mock orders the rows by target ID.
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-reco-counts-report-row-order`
+
+Setting recognition counts is mock-only, because real Vuforia's counts are
+delayed for longer than a test runs, so the tests for reports with rows in
+``tests/mock_vws/test_reco_counts_report.py`` run against the mocks only.
 As with real Vuforia, the report is served with a ``text/plain`` content type
 rather than a CSV one.
 
@@ -375,8 +463,10 @@ The mock's URL returns a 404 response until the report is ready, and requires
 no authorization.
 The lack of authorization matches real Vuforia, whose URL carries its own
 signature.
-The 404 has not been verified, because no request for a real report has caught
-one before it was generated.
+
+.. admonition:: Unverified assumption
+
+   :ref:`unverified-reco-counts-report-not-ready`
 
 Paths which the mock does not serve
 -----------------------------------
@@ -389,9 +479,9 @@ For any other request which it does not serve, such as ``DELETE /summary`` or
 and the path of the request.
 The Flask and Docker mock reproduces both response shapes.
 
-The ``requests`` and ``httpx`` backends mock only the paths which the mock
-serves, so a request to any other path raises a connection error rather than
-giving the 404 response which real Vuforia gives.
+The ``requests``, ``httpx`` and ``httpx2`` backends mock only the paths which
+the mock serves, so a request to any other path raises a connection error
+rather than giving the 404 response which real Vuforia gives.
 
 Header cases
 ------------