API Reference¶

class mock_vws.MockVWS(*, base_vws_url: str = 'https://vws.vuforia.com', base_vwq_url: str = 'https://cloudreco.vuforia.com', cloud_query_failure_response: ~mock_vws.cloud_query.CloudQueryFailureResponse | None = None, duplicate_match_checker: ~mock_vws.image_matchers.ImageMatcher = <mock_vws.image_matchers.StructuralSimilarityMatcher object>, query_match_checker: ~mock_vws.image_matchers.ImageMatcher = <mock_vws.image_matchers.StructuralSimilarityMatcher object>, processing_time_seconds: float = 2.0, model_target_generation_failure: ~mock_vws.model_target.ModelTargetGenerationFailure | None = None, model_target_failure_response: ~mock_vws.model_target.ModelTargetFailureResponse | None = None, model_target_generation_warning: ~mock_vws.model_target.ModelTargetGenerationWarning | None = None, model_target_training_allowance_exceeded: bool = False, target_tracking_rater: ~mock_vws.target_raters.TargetTrackingRater = <mock_vws.target_raters.BrisqueTargetTrackingRater object>, real_http: bool = False, response_delay_seconds: float = 0.0, sleep_fn: ~collections.abc.Callable[[float], None] = <built-in function sleep>, vumark_generation_failure: ~mock_vws.vumark.VuMarkGenerationFailure | None = None)¶

Route requests to Vuforia’s Web Service APIs to fakes of those APIs.

Works with requests, httpx and httpx2.

An instance is usable as a context manager and as a decorator.

A context manager block shares one set of databases and targets with every other use of the same instance, so state created in one with block is still there in the next one.

A decorated function instead gets its own databases and targets for the duration of each call. The databases added to the instance are available inside the call, and the targets created during the call are discarded when it returns, so decorated functions do not affect each other.

Route requests to Vuforia’s Web Service APIs to fakes of those APIs.

Works with requests, httpx and httpx2.

Parameters:

• real_http¶ – Whether or not to forward requests to the real server if they are not handled by the mock. See https://requests-mock.readthedocs.io/en/latest/mocker.html#real-http-requests.

• processing_time_seconds¶ – The number of seconds to process each image for. In the real Vuforia Web Services, this is not deterministic.

• model_target_generation_failure¶ – A failure to return after every Model Target dataset finishes processing. By default, Model Target datasets finish successfully.

• model_target_failure_response¶ – A response to return for the selected Model Target dataset request phases, after OAuth2 token acquisition and before normal request validation. By default, Model Target dataset requests are handled normally.

• model_target_generation_warning¶ – A warning to return after every Model Target dataset finishes processing. By default, Model Target datasets finish without warnings. This cannot be combined with model_target_generation_failure.

• model_target_training_allowance_exceeded¶ – Whether Model Target dataset creation returns Vuforia’s TRAINING_ALLOWANCE_EXCEEDED response. By default, creation is allowed.

• base_vwq_url¶ – The base URL for the VWQ API.

• base_vws_url¶ – The base URL for the VWS API.

• cloud_query_failure_response¶ – A response to return for every Cloud Query request, bypassing normal request validation and image matching. By default, Cloud Query requests are handled normally.

• vumark_generation_failure¶ – A failure to return for every VuMark generation request, bypassing normal request validation and instance generation. By default, VuMark generation requests are handled normally.

• query_match_checker¶ – A callable which takes two image values and returns a match score for a query request, or None if they do not match.

• duplicate_match_checker¶ – A callable which takes two image values and returns a match score, or None if they are not duplicates.

• target_tracking_rater¶ – A callable for rating targets for tracking.

• response_delay_seconds¶ – The number of seconds to delay each response by. This can be used to test timeout handling.

• sleep_fn¶ – The function to use for sleeping during response delays. Defaults to time.sleep. Inject a custom function to control virtual time in tests without monkey-patching.

Raises:

• MissingSchemeError – There is no scheme in a given URL.

• ValueError – Both a Model Target generation failure and warning are configured.

add_cloud_database(cloud_database: CloudDatabase) → None¶

Add a cloud database.

Parameters:

cloud_database¶ – The cloud database to add.

Raises:

ValueError – One of the given cloud database keys matches a key for an existing cloud database.

add_vumark_database(vumark_database: VuMarkDatabase) → None¶

Add a VuMark database.

Parameters:

vumark_database¶ – The VuMark database to add.

Raises:

ValueError – One of the given database keys matches a key for an existing database.

set_target_recognition_counts(*, target_id: str, current_month_recos: int | None = None, previous_month_recos: int | None = None, total_recos: int | None = None) → None¶

Set the recognition counts of a target.

Queries do not change these counts, because the counts which real Vuforia reports lag behind its queries by longer than a test runs, so this is the only way to make them anything but zero.

Parameters:

• target_id¶ – The ID of the target to set recognition counts of.

• current_month_recos¶ – The number of recognitions of the target in the current month, or None to leave that count as it is.

• previous_month_recos¶ – The number of recognitions of the target in the previous month, or None to leave that count as it is.

• total_recos¶ – The total number of recognitions of the target, or None to leave that count as it is.

Raises:

ValueError – No target in any added cloud database has the given ID.

class mock_vws.MissingSchemeError(url: str)¶

Raised when a URL is missing a schema.

Parameters:

url¶ – The URL which is missing a scheme.

class mock_vws.CloudQueryFailureResponse(*, status_code, headers={}, body=b'')¶

A failure response returned by the Cloud Query API mock.

Parameters:

• status_code¶ – The HTTP status code to return.

• headers¶ – The HTTP response headers to return.

• body¶ – The raw response body. String bodies are encoded as UTF-8 by the HTTP backend; byte bodies are returned unchanged.

status_code: int¶

headers: dict[str, str]¶

body: str | bytes = b''¶

class mock_vws.ModelTargetFailureResponse(*, status_code, headers={}, body=b'', requests=...)¶

A configured failure returned by Model Target dataset requests.

OAuth2 token requests are always handled normally, so clients obtain a token before a configured dataset-request failure is returned.

Parameters:

• status_code¶ – The HTTP status code to return.

• headers¶ – The HTTP response headers to return.

• body¶ – The raw response body. String bodies are encoded as UTF-8 by the HTTP backend; byte bodies are returned unchanged.

• requests¶ – The dataset request phases which return this response. By default, every dataset request phase returns it.

status_code: int¶

headers: dict[str, str]¶

body: str | bytes = b''¶

requests: frozenset[ModelTargetRequest]¶

class mock_vws.ModelTargetRequest(*values)¶

A Model Target dataset request phase.

CREATE = 'create'¶

STATUS = 'status'¶

DOWNLOAD = 'download'¶

DELETE = 'delete'¶

class mock_vws.VuMarkGenerationFailure(*values)¶

A configured failure returned by the VuMark Generation API mock.

QUOTA_EXCEEDED = 'QuotaExceeded'¶

LICENSE_CHECK_FAILED = 'LicenseCheckFailed'¶

AUTHORIZATION_FAILED = 'AuthorizationFailed'¶

property status_code: HTTPStatus¶

Return the HTTP status documented for this failure.

class mock_vws.ModelTargetGenerationFailure(*, message: str = 'Model Target dataset generation failed')¶

A configured Model Target dataset generation failure.

Parameters:

message¶ – The failure message included in the dataset status response.

message: str = 'Model Target dataset generation failed'¶

class mock_vws.ModelTargetGenerationWarning(*, message='Warning after creating dataset', details=...)¶

A configured Model Target dataset generation warning.

Parameters:

• message¶ – The top-level warning message included in the dataset status response.

• details¶ – The warning details included in the dataset status response.

message: str = 'Warning after creating dataset'¶

details: Sequence[Mapping[str, JsonValue]]¶

mock_vws.model_target.JSONValue¶

A recursive JSON value type.

class mock_vws.database.CloudDatabase(*, database_id: str = <factory>, database_name: str = <factory>, server_access_key: str = <factory>, server_secret_key: str = <factory>, client_access_key: str = <factory>, client_secret_key: str = <factory>, targets: set[ImageTarget] = <factory>, state: States = States.WORKING, database_type: DatabaseType = DatabaseType.CLOUD_RECO, request_quota: int = 100000, reco_threshold: int = 1000, current_month_recos: int = 0, previous_month_recos: int = 0, total_recos: int = 0, target_quota: int = 1000, requests_per_second_limit: int | None = None, request_rate_limits: RequestRateLimits | None = None)¶

Credentials for VWS APIs.

Parameters:

• database_id¶ – The identifier of a VWS target manager database. Defaults to a random string. Endpoints which name a database in their path, such as the reco counts report endpoint, accept only the identifier of the database which the request’s server keys belong to.

• database_name¶ – The name of a VWS target manager database name. Defaults to a random string.

• server_access_key¶ – A VWS server access key. Defaults to a random string.

• server_secret_key¶ – A VWS server secret key. Defaults to a random string.

• client_access_key¶ – A VWS client access key. Defaults to a random string.

• client_secret_key¶ – A VWS client secret key. Defaults to a random string.

• state¶ – The state of the database.

• request_quota¶ – The request quota. Set this to 0 to make VWS endpoints return RequestQuotaReached.

• target_quota¶ – The target quota. When the database contains this many targets, adding another returns TargetQuotaReached.

• reco_threshold¶ – The recognition threshold shown in the database summary report.

• current_month_recos¶ – The number of recognitions in the current month, shown in the database summary report. The mock does not count recognitions, so this is whatever it is set to.

• previous_month_recos¶ – The number of recognitions in the previous month, shown in the database summary report. The mock does not count recognitions, so this is whatever it is set to.

• total_recos¶ – The total number of recognitions, shown in the database summary report. The mock does not count recognitions, so this is whatever it is set to.

• requests_per_second_limit¶ – The maximum number of VWS requests accepted in a rolling one-second window, across all VWS endpoints. Set this to 0 to make VWS endpoints return a 429 response. By default, the mock does not apply this limit.

• request_rate_limits¶ – Request rate limits which apply to individual groups of VWS endpoints, tracked separately from each other and from requests_per_second_limit. Set this to mock_vws.request_rate_limits.DOCUMENTED_REQUEST_RATE_LIMITS to apply the limits which Vuforia documents. By default, the mock does not apply per-endpoint request limits.

database_id: str¶

database_name: str¶

server_access_key: str¶

server_secret_key: str¶

client_access_key: str¶

client_secret_key: str¶

targets: set[ImageTarget]¶

state: States = 'working'¶

database_type: DatabaseType = 'cloud_reco'¶

request_quota: int = 100000¶

reco_threshold: int = 1000¶

current_month_recos: int = 0¶

previous_month_recos: int = 0¶

total_recos: int = 0¶

target_quota: int = 1000¶

requests_per_second_limit: int | None = None¶

request_rate_limits: RequestRateLimits | None = None¶

class mock_vws.database.VuMarkDatabase(*, database_name: str = <factory>, server_access_key: str = <factory>, server_secret_key: str = <factory>, vumark_targets: set[VuMarkTarget] = <factory>, state: States = States.WORKING)¶

Credentials for the VuMark generation API.

Parameters:

• database_name¶ – The name of a VWS target manager database name. Defaults to a random string.

• server_access_key¶ – A VWS server access key. Defaults to a random string.

• server_secret_key¶ – A VWS server secret key. Defaults to a random string.

database_name: str¶

server_access_key: str¶

server_secret_key: str¶

vumark_targets: set[VuMarkTarget]¶

state: States = 'working'¶

get_vumark_target(target_id: str) → VuMarkTarget¶

Return a VuMark target from the database with the given ID.

class mock_vws.request_rate_limits.RequestRateLimit(*, max_requests: int, window_seconds: float)¶

A maximum number of requests within a rolling time window.

Parameters:

• max_requests¶ – The number of requests accepted within the window.

• window_seconds¶ – The length of the rolling window, in seconds.

max_requests: int¶

window_seconds: float¶

class mock_vws.request_rate_limits.RequestRateLimits(*, other: RequestRateLimit | None = None, get_target: RequestRateLimit | None = None, get_duplicates: RequestRateLimit | None = None, list_targets: RequestRateLimit | None = None)¶

Request rate limits for each group of VWS endpoints.

Each limit is tracked separately, in the same way that the real Vuforia Web Services document separate limits per endpoint. Endpoints without their own limit share the other limit. A limit of None means that no limit is applied.

Parameters:

• other¶ – The limit for endpoints without their own limit.

• get_target¶ – The limit for GET /targets/{target_id} requests.

• get_duplicates¶ – The limit for GET /duplicates/{target_id} requests.

• list_targets¶ – The limit for GET /targets requests.

other: RequestRateLimit | None = None¶

get_target: RequestRateLimit | None = None¶

get_duplicates: RequestRateLimit | None = None¶

list_targets: RequestRateLimit | None = None¶

class mock_vws.request_rate_limits.RateLimitedEndpoint(*values)¶

A group of VWS endpoints which share a request rate limit.

GET_TARGET = 1¶

GET_DUPLICATES = 2¶

LIST_TARGETS = 3¶

OTHER = 4¶

mock_vws.request_rate_limits.DOCUMENTED_REQUEST_RATE_LIMITS = RequestRateLimits(other=RequestRateLimit(max_requests=15, window_seconds=1.0), get_target=RequestRateLimit(max_requests=45, window_seconds=1.0), get_duplicates=RequestRateLimit(max_requests=10, window_seconds=1.0), list_targets=RequestRateLimit(max_requests=2, window_seconds=60.0))¶

The request rate limits which Vuforia documents, corrected by observation.

Vuforia documents 15 requests per second for VWS endpoints in general, 45 per second for GET /targets/{target_id}, 10 per second for GET /duplicates/{target_id} and one per minute for GET /targets. Real Vuforia was observed on 2026-09-08 to accept two GET /targets requests per minute, not one, so that is the limit here.

These limits are not applied by default.

class mock_vws.states.States(*values)¶

Constants representing various web service states.

WORKING = 'working'¶

PROJECT_SUSPENDED = 'project_suspended'¶

PROJECT_INACTIVE = 'project_inactive'¶

PROJECT_HAS_NO_API_ACCESS = 'project_has_no_api_access'¶

class mock_vws.database_type.DatabaseType(*values)¶

Constants representing various database types.

CLOUD_RECO = 'cloud_reco'¶

class mock_vws.target.ImageTarget(*, active_flag: bool, application_metadata: str | None, image_value: bytes, name: str, processing_time_seconds: int | float, width: float, target_tracking_rater: TargetTrackingRater, current_month_recos: int = 0, delete_date: datetime | None = None, last_modified_date: datetime = <factory>, previous_month_recos: int = 0, reco_rating: str = '', target_id: str = <factory>, total_recos: int = 0, upload_date: datetime = <factory>)¶

A Vuforia image target as managed in the Vuforia Target Manager.

current_month_recos, previous_month_recos and total_recos are the recognition counts which the target summary report and the reco counts report show for this target. The mock does not count recognitions, so these are whatever they are set to. Targets are created by API requests, so set them with mock_vws.MockVWS.set_target_recognition_counts() rather than by constructing a target.

class mock_vws.target.VuMarkTarget(*, name: str, processing_time_seconds: int | float = 0.0, target_id: str = <factory>, last_modified_date: datetime = <factory>, upload_date: datetime = <factory>)¶

A VuMark target as managed in the Vuforia Target Manager.

Unlike ImageTarget, VuMark targets do not require an image — they use a VuMark template.