|
| 1 | +"""Interface to the Vuforia VuMark Generation Web API.""" |
| 2 | + |
| 3 | +import json |
| 4 | +from http import HTTPMethod, HTTPStatus |
| 5 | + |
| 6 | +from beartype import BeartypeConf, beartype |
| 7 | + |
| 8 | +from vws.exceptions.custom_exceptions import ServerError |
| 9 | +from vws.exceptions.vws_exceptions import ( |
| 10 | + AuthenticationFailureError, |
| 11 | + BadRequestError, |
| 12 | + DateRangeError, |
| 13 | + FailError, |
| 14 | + InvalidAcceptHeaderError, |
| 15 | + InvalidInstanceIdError, |
| 16 | + InvalidTargetTypeError, |
| 17 | + RequestTimeTooSkewedError, |
| 18 | + TargetStatusNotSuccessError, |
| 19 | + TooManyRequestsError, |
| 20 | + UnknownTargetError, |
| 21 | +) |
| 22 | +from vws.vumark_accept import VuMarkAccept |
| 23 | +from vws.vws import _target_api_request |
| 24 | + |
| 25 | + |
| 26 | +@beartype(conf=BeartypeConf(is_pep484_tower=True)) |
| 27 | +class VuMarkService: |
| 28 | + """An interface to the Vuforia VuMark Generation Web API.""" |
| 29 | + |
| 30 | + def __init__( |
| 31 | + self, |
| 32 | + server_access_key: str, |
| 33 | + server_secret_key: str, |
| 34 | + base_vws_url: str = "https://vws.vuforia.com", |
| 35 | + request_timeout_seconds: float | tuple[float, float] = 30.0, |
| 36 | + ) -> None: |
| 37 | + """ |
| 38 | + Args: |
| 39 | + server_access_key: A VWS server access key. |
| 40 | + server_secret_key: A VWS server secret key. |
| 41 | + base_vws_url: The base URL for the VWS API. |
| 42 | + request_timeout_seconds: The timeout for each HTTP request, as |
| 43 | + used by ``requests.request``. This can be a float to set |
| 44 | + both the connect and read timeouts, or a (connect, read) |
| 45 | + tuple. |
| 46 | + """ |
| 47 | + self._server_access_key = server_access_key |
| 48 | + self._server_secret_key = server_secret_key |
| 49 | + self._base_vws_url = base_vws_url |
| 50 | + self._request_timeout_seconds = request_timeout_seconds |
| 51 | + |
| 52 | + def generate_vumark_instance( |
| 53 | + self, |
| 54 | + *, |
| 55 | + target_id: str, |
| 56 | + instance_id: str, |
| 57 | + accept: VuMarkAccept, |
| 58 | + ) -> bytes: |
| 59 | + """Generate a VuMark instance image. |
| 60 | +
|
| 61 | + See |
| 62 | + https://developer.vuforia.com/library/vuforia-engine/web-api/vumark-generation-web-api/ |
| 63 | + for parameter details. |
| 64 | +
|
| 65 | + Args: |
| 66 | + target_id: The ID of the VuMark target. |
| 67 | + instance_id: The instance ID to encode in the VuMark. |
| 68 | + accept: The image format to return. |
| 69 | +
|
| 70 | + Returns: |
| 71 | + The VuMark instance image bytes. |
| 72 | +
|
| 73 | + Raises: |
| 74 | + ~vws.exceptions.vws_exceptions.AuthenticationFailureError: The |
| 75 | + secret key is not correct. |
| 76 | + ~vws.exceptions.vws_exceptions.FailError: There was an error with |
| 77 | + the request. For example, the given access key does not match a |
| 78 | + known database. |
| 79 | + ~vws.exceptions.vws_exceptions.InvalidAcceptHeaderError: The |
| 80 | + Accept header value is not supported. |
| 81 | + ~vws.exceptions.vws_exceptions.InvalidInstanceIdError: The |
| 82 | + instance ID is invalid. For example, it may be empty. |
| 83 | + ~vws.exceptions.vws_exceptions.InvalidTargetTypeError: The target |
| 84 | + is not a VuMark template target. |
| 85 | + ~vws.exceptions.vws_exceptions.RequestTimeTooSkewedError: There is |
| 86 | + an error with the time sent to Vuforia. |
| 87 | + ~vws.exceptions.vws_exceptions.TargetStatusNotSuccessError: The |
| 88 | + target is not in the success state. |
| 89 | + ~vws.exceptions.vws_exceptions.UnknownTargetError: The given target |
| 90 | + ID does not match a target in the database. |
| 91 | + ~vws.exceptions.custom_exceptions.ServerError: There is an error |
| 92 | + with Vuforia's servers. |
| 93 | + ~vws.exceptions.vws_exceptions.TooManyRequestsError: Vuforia is |
| 94 | + rate limiting access. |
| 95 | + """ |
| 96 | + request_path = f"/targets/{target_id}/instances" |
| 97 | + content_type = "application/json" |
| 98 | + request_data = json.dumps(obj={"instance_id": instance_id}).encode( |
| 99 | + encoding="utf-8", |
| 100 | + ) |
| 101 | + |
| 102 | + response = _target_api_request( |
| 103 | + content_type=content_type, |
| 104 | + server_access_key=self._server_access_key, |
| 105 | + server_secret_key=self._server_secret_key, |
| 106 | + method=HTTPMethod.POST, |
| 107 | + data=request_data, |
| 108 | + request_path=request_path, |
| 109 | + base_vws_url=self._base_vws_url, |
| 110 | + request_timeout_seconds=self._request_timeout_seconds, |
| 111 | + extra_headers={"Accept": accept}, |
| 112 | + ) |
| 113 | + |
| 114 | + if ( |
| 115 | + response.status_code == HTTPStatus.TOO_MANY_REQUESTS |
| 116 | + ): # pragma: no cover |
| 117 | + # The Vuforia API returns a 429 response with no JSON body. |
| 118 | + raise TooManyRequestsError(response=response) |
| 119 | + |
| 120 | + if ( |
| 121 | + response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR |
| 122 | + ): # pragma: no cover |
| 123 | + raise ServerError(response=response) |
| 124 | + |
| 125 | + if response.status_code == HTTPStatus.OK: |
| 126 | + return response.content |
| 127 | + |
| 128 | + result_code = json.loads(s=response.text)["result_code"] |
| 129 | + |
| 130 | + exception = { |
| 131 | + "AuthenticationFailure": AuthenticationFailureError, |
| 132 | + "BadRequest": BadRequestError, |
| 133 | + "DateRangeError": DateRangeError, |
| 134 | + "Fail": FailError, |
| 135 | + "InvalidAcceptHeader": InvalidAcceptHeaderError, |
| 136 | + "InvalidInstanceId": InvalidInstanceIdError, |
| 137 | + "InvalidTargetType": InvalidTargetTypeError, |
| 138 | + "RequestTimeTooSkewed": RequestTimeTooSkewedError, |
| 139 | + "TargetStatusNotSuccess": TargetStatusNotSuccessError, |
| 140 | + "UnknownTarget": UnknownTargetError, |
| 141 | + }[result_code] |
| 142 | + |
| 143 | + raise exception(response=response) |
0 commit comments