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_generation_warning: ~mock_vws.model_target.ModelTargetGenerationWarning | None = None, 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 both requests and httpx.

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

Works with both requests and httpx.

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_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.

• 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 whether they will match in a query request.

• duplicate_match_checker – A callable which takes two image values and returns whether they are 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.

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.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: list[dict[str, Any]]

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.

• 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 TooManyRequests. 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=1, window_seconds=60.0))

The request rate limits documented by Vuforia.

These limits have not been verified against the real Vuforia Web Services, and so they 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: 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 https://developer.vuforia.com/target-manager.

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

A VuMark target as managed in https://developer.vuforia.com/target-manager.

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

Image matchers

protocol mock_vws.image_matchers.ImageMatcher

Protocol for a matcher for query and duplicate requests.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

__call__(first_image_content: bytes, second_image_content: bytes) → bool

Whether one image’s content matches another’s closely enough.

Parameters:

• first_image_content – One image’s content.

• second_image_content – Another image’s content.

__annotations_cache__ = {}

class mock_vws.image_matchers.ExactMatcher

A matcher which returns whether two images are exactly equal.

class mock_vws.image_matchers.StructuralSimilarityMatcher

A matcher which returns whether two images are similar using SSIM.

Target raters

protocol mock_vws.target_raters.TargetTrackingRater

Protocol for a rater of target quality.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

__call__(image_content: bytes) → int

The target tracking rating.

Parameters:

image_content – A target’s image’s content.

__annotations_cache__ = {}

class mock_vws.target_raters.RandomTargetTrackingRater

A rater which returns a random number.

class mock_vws.target_raters.HardcodedTargetTrackingRater(rating: int)

A rater which returns a hardcoded number.

Parameters:

rating – The rating to return.

class mock_vws.target_raters.BrisqueTargetTrackingRater

A rater which returns a rating based on a BRISQUE score.