Add Database Reco Counts report client support - #3146
Merged
Conversation
Add ``request_database_reco_counts_report``, ``download_reco_counts_report`` and ``wait_for_reco_counts_report`` to ``VWS`` and ``AsyncVWS``, along with an optional ``database_id`` constructor argument which the report endpoint needs. The download is not signed, is not against ``base_vws_url``, and 404s until the report is generated, so it does not go through ``make_request``. Closes #3133 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The month was a ``YYYY-mm`` string, which let callers pass a value that could not be a month at all. Taking two ints makes a malformed month unrepresentable, and reads better next to ``datetime`` attributes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Vuforia accepts only the current month and the previous month, so a month out of the 1-12 range is now rejected by the type rather than by the server. A month taken from a ``datetime`` needs wrapping in ``calendar.Month``, because ``datetime.month`` is a plain ``int`` and ``beartype`` rejects it otherwise. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #3133.
Adds client support for the Database Reco Counts report — the last VWS endpoint with no
vws-pythonequivalent.What is added
VWSandAsyncVWStake an optionaldatabase_id. The report endpoint is the first to need it, and it is not derivable from the server keys. Calling the report method without it raisesDatabaseIdNotSetError.request_database_reco_counts_report(year=..., month=...)returns aRecoCountsReportRequestwith the transaction ID and the presigned URL. The wire format is aYYYY-mmstring, but the arguments are two ints, so a malformed month is unrepresentable and the call site reads well next todatetimeattributes.download_reco_counts_report(presigned_url=...)fetches the report. It is unsigned, is not againstbase_vws_url, and does not go throughmake_request. A 404 raisesRecoCountsReportNotReadyError; any other non-200 raisesRecoCountsReportDownloadError, as an expired URL would give.wait_for_reco_counts_report(presigned_url=...)polls until the report is ready, raisingRecoCountsReportTimeoutErroron timeout.RecoCountsReportparses the CSV intoRecoCountitems and keepsraw_csv, since Vuforia does not document the format and it could gain columns. Unknown columns are ignored.Tests
Both clients are exercised against
vws-python-mockfor a successful report, a download before the report is ready, a wait which times out, a rejected month (out of range and out of the accepted window), a mismatched database ID, a missing database ID and a failed download. Parsing is tested for empty, populated and extra-column CSVs.Per the notes on the issue, the tests do not depend on the shape of the presigned URL and do not assert on non-empty report bodies, since the mock's reports are header-only until VWS-Python/vws-python-mock#3356 lands.
Docs
A "Recognition counts" example in the documentation, an API reference entry via the existing
automoduledirectives, and a news fragment.🤖 Generated with Claude Code
Note
Low Risk
Additive API surface with broad test coverage; download uses a separate unsigned URL path but does not change existing target-management behavior.
Overview
Adds client support for Vuforia’s Database Reco Counts report: per-target recognition counts for the current or previous month.
VWSandAsyncVWSnow accept an optionaldatabase_id(required only for this feature). New methods mirror the async/sync split elsewhere:request_database_reco_counts_report(year, month)kicks off background generation and returns a presigned URL;download_reco_counts_reportfetches the CSV via unsigned GET (notmake_request);wait_for_reco_counts_reportpolls until ready. Shared logic lives in_reco_counts.py.Models and errors:
RecoCountsReportRequest,RecoCount, andRecoCountsReport(CSV parsing withraw_csvpreserved; extra columns ignored). New exceptions includeDatabaseIdNotSetError,RecoCountsReportNotReadyError(404),RecoCountsReportDownloadError, andRecoCountsReportTimeoutError.Docs gain a “Recognition counts” example; tests and mock fixtures wire
database_id/VWS_DATABASE_ID.Reviewed by Cursor Bugbot for commit 613d8d5. Bugbot is set up for automated code reviews on this repo. Configure here.