Skip to content

Commit 6f1a79a

Browse files
adamtheturtleadamtheturtle
committed
Document new exception locations
1 parent 9faac72 commit 6f1a79a

File tree

6 files changed

+174
-114
lines changed

6 files changed

+174
-114
lines changed

‎CHANGELOG.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ Changelog
66
Next
77
----
88

9+
* Breaking change: Move exceptions and create base exceptions.
10+
It is now possible to, for example, catch
11+
``vws.exceptions.base_exceptions.VWSException`` to catch many of the
12+
exceptions raised by the ``VWS`` client.
13+
Credit to ``@laymonage`` for this change.
14+
915
2020.08.21.0
1016
------------
1117

‎docs/source/exceptions.rst‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,39 @@
11
Exceptions
22
==========
33

4-
.. automodule:: vws.exceptions
4+
.. contents::
5+
6+
Base exceptions
7+
---------------
8+
9+
.. automodule:: vws.exceptions.base_exceptions
10+
:members:
11+
:show-inheritance:
12+
:inherited-members: Exception
13+
:exclude-members: errno, filename, filename2, strerror
14+
15+
VWS exceptions
16+
--------------
17+
18+
.. automodule:: vws.exceptions.vws_exceptions
19+
:members:
20+
:show-inheritance:
21+
:inherited-members: Exception
22+
:exclude-members: errno, filename, filename2, strerror
23+
24+
CloudRecoService exceptions
25+
---------------------------
26+
27+
.. automodule:: vws.exceptions.cloud_reco_exceptions
28+
:members:
29+
:show-inheritance:
30+
:inherited-members: Exception
31+
:exclude-members: errno, filename, filename2, strerror
32+
33+
Custom exceptions
34+
-----------------
35+
36+
.. automodule:: vws.exceptions.custom_exceptions
537
:members:
638
:show-inheritance:
739
:inherited-members: Exception

‎src/vws/exceptions/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""
2+
Custom exceptions raised by this package.
3+
"""

‎src/vws/exceptions/vws_exceptions.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,6 @@ class ProjectHasNoAPIAccess(VWSException): # pragma: no cover
9999
"""
100100

101101

102-
# TODO separate InactiveProject
103102
class ProjectInactive(VWSException):
104103
"""
105104
Exception raised when Vuforia returns a response with a result code

‎src/vws/query.py‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -69,21 +69,22 @@ def query(
6969
none (return no target_data), all (for all matched targets).
7070
7171
Raises:
72-
~vws.exceptions.AuthenticationFailure: The client access key pair
73-
is not correct.
74-
~vws.exceptions.MaxNumResultsOutOfRange: ``max_num_results`` is not
75-
within the range (1, 50).
76-
~vws.exceptions.MatchProcessing: The given image matches a target
77-
which was recently added, updated or deleted and Vuforia
78-
returns an error in this case.
79-
~vws.exceptions.ProjectInactive: The project is inactive.
80-
~vws.exceptions.ConnectionErrorPossiblyImageTooLarge: The given
81-
image is too large.
82-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
83-
time sent to Vuforia.
84-
~vws.exceptions.BadImage: There is a problem with the given image.
85-
For example, it must be a JPEG or PNG file in the grayscale or
86-
RGB color space.
72+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The client
73+
access key pair is not correct.
74+
~vws.exceptions.cloud_reco_exceptions.MaxNumResultsOutOfRange:
75+
``max_num_results`` is not within the range (1, 50).
76+
~vws.exceptions.cloud_reco_exceptions.MatchProcessing: The given
77+
image matches a target which was recently added, updated or
78+
deleted and Vuforia returns an error in this case.
79+
~vws.exceptions.vws_exceptions.ProjectInactive: The project is
80+
inactive.
81+
~vws.exceptions.custom_exceptions.ConnectionErrorPossiblyImageTooLarge:
82+
The given image is too large.
83+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
84+
error with the time sent to Vuforia.
85+
~vws.exceptions.vws_exceptions.BadImage: There is a problem with
86+
the given image. For example, it must be a JPEG or PNG file in
87+
the grayscale or RGB color space.
8788
8889
Returns:
8990
An ordered list of target details of matching targets.

‎src/vws/vws.py‎

Lines changed: 116 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -174,25 +174,30 @@ def add_target(
174174
The target ID of the new target.
175175
176176
Raises:
177-
~vws.exceptions.AuthenticationFailure: The secret key is not
178-
correct.
179-
~vws.exceptions.BadImage: There is a problem with the given image.
177+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
178+
key is not correct.
179+
~vws.exceptions.vws_exceptions.BadImage: There is a problem with
180+
the given image.
180181
For example, it must be a JPEG or PNG file in the grayscale or
181182
RGB color space.
182-
~vws.exceptions.Fail: There was an error with the request. For
183-
example, the given access key does not match a known database.
184-
~vws.exceptions.MetadataTooLarge: The given metadata is too large.
185-
The maximum size is 1 MB of data when Base64 encoded.
186-
~vws.exceptions.ImageTooLarge: The given image is too large.
187-
~vws.exceptions.TargetNameExist: A target with the given ``name``
188-
already exists.
189-
~vws.exceptions.ProjectInactive: The project is inactive.
190-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
191-
time sent to Vuforia.
192-
~vws.exceptions.UnknownVWSErrorPossiblyBadName: Vuforia returns an
193-
HTML page with the text "Oops, an error occurred". This has
194-
been seen to happen when the given name includes a bad
195-
character.
183+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
184+
request. For example, the given access key does not match a
185+
known database.
186+
~vws.exceptions.vws_exceptions.MetadataTooLarge: The given metadata
187+
is too large. The maximum size is 1 MB of data when Base64
188+
encoded.
189+
~vws.exceptions.vws_exceptions.ImageTooLarge: The given image is
190+
too large.
191+
~vws.exceptions.vws_exceptions.TargetNameExist: A target with the
192+
given ``name`` already exists.
193+
~vws.exceptions.vws_exceptions.ProjectInactive: The project is
194+
inactive.
195+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
196+
error with the time sent to Vuforia.
197+
~vws.exceptions.custom_exceptions.UnknownVWSErrorPossiblyBadName:
198+
Vuforia returns an HTML page with the text "Oops, an error
199+
occurred". This has been seen to happen when the given name
200+
includes a bad character.
196201
"""
197202
image_data = image.getvalue()
198203
image_data_encoded = base64.b64encode(image_data).decode('ascii')
@@ -230,14 +235,15 @@ def get_target_record(self, target_id: str) -> TargetStatusAndRecord:
230235
Response details of a target from Vuforia.
231236
232237
Raises:
233-
~vws.exceptions.AuthenticationFailure: The secret key is not
234-
correct.
235-
~vws.exceptions.Fail: There was an error with the request. For
236-
example, the given access key does not match a known database.
237-
~vws.exceptions.UnknownTarget: The given target ID does not match a
238-
target in the database.
239-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
240-
time sent to Vuforia.
238+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
239+
key is not correct.
240+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
241+
request. For example, the given access key does not match a
242+
known database.
243+
~vws.exceptions.vws_exceptions.UnknownTarget: The given target ID
244+
does not match a target in the database.
245+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
246+
error with the time sent to Vuforia.
241247
"""
242248
response = self._make_request(
243249
method='GET',
@@ -277,16 +283,17 @@ def _wait_for_target_processed(
277283
requests made while polling the target status.
278284
279285
Raises:
280-
~vws.exceptions.AuthenticationFailure: The secret key is not
281-
correct.
282-
~vws.exceptions.Fail: There was an error with the request. For
283-
example, the given access key does not match a known database.
286+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
287+
key is not correct.
288+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
289+
request. For example, the given access key does not match a
290+
known database.
284291
TimeoutError: The target remained in the processing stage for more
285292
than five minutes.
286-
~vws.exceptions.UnknownTarget: The given target ID does not match a
287-
target in the database.
288-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
289-
time sent to Vuforia.
293+
~vws.exceptions.vws_exceptions.UnknownTarget: The given target ID
294+
does not match a target in the database.
295+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
296+
error with the time sent to Vuforia.
290297
"""
291298
while True:
292299
report = self.get_target_summary_report(target_id=target_id)
@@ -317,16 +324,18 @@ def wait_for_target_processed(
317324
applied.
318325
319326
Raises:
320-
~vws.exceptions.AuthenticationFailure: The secret key is not
321-
correct.
322-
~vws.exceptions.Fail: There was an error with the request. For
323-
example, the given access key does not match a known database.
324-
~vws.exceptions.TargetProcessingTimeout: The target remained in the
325-
processing stage for more than ``timeout_seconds`` seconds.
326-
~vws.exceptions.UnknownTarget: The given target ID does not match a
327-
target in the database.
328-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
329-
time sent to Vuforia.
327+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
328+
key is not correct.
329+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
330+
request. For example, the given access key does not match a
331+
known database.
332+
~vws.exceptions.custom_exceptions.TargetProcessingTimeout: The
333+
target remained in the processing stage for more than
334+
``timeout_seconds`` seconds.
335+
~vws.exceptions.vws_exceptions.UnknownTarget: The given target ID
336+
does not match a target in the database.
337+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
338+
error with the time sent to Vuforia.
330339
"""
331340

332341
@func_set_timeout(timeout=timeout_seconds)
@@ -352,12 +361,13 @@ def list_targets(self) -> List[str]:
352361
The IDs of all targets in the database.
353362
354363
Raises:
355-
~vws.exceptions.AuthenticationFailure: The secret key is not
356-
correct.
357-
~vws.exceptions.Fail: There was an error with the request. For
358-
example, the given access key does not match a known database.
359-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
360-
time sent to Vuforia.
364+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
365+
key is not correct.
366+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
367+
request. For example, the given access key does not match a
368+
known database.
369+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
370+
error with the time sent to Vuforia.
361371
"""
362372
response = self._make_request(
363373
method='GET',
@@ -382,14 +392,15 @@ def get_target_summary_report(self, target_id: str) -> TargetSummaryReport:
382392
Details of the target.
383393
384394
Raises:
385-
~vws.exceptions.AuthenticationFailure: The secret key is not
386-
correct.
387-
~vws.exceptions.Fail: There was an error with the request. For
388-
example, the given access key does not match a known database.
389-
~vws.exceptions.UnknownTarget: The given target ID does not match a
390-
target in the database.
391-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
392-
time sent to Vuforia.
395+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
396+
key is not correct.
397+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
398+
request. For example, the given access key does not match a
399+
known database.
400+
~vws.exceptions.vws_exceptions.UnknownTarget: The given target ID
401+
does not match a target in the database.
402+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
403+
error with the time sent to Vuforia.
393404
"""
394405
response = self._make_request(
395406
method='GET',
@@ -422,12 +433,13 @@ def get_database_summary_report(self) -> DatabaseSummaryReport:
422433
Details of the database.
423434
424435
Raises:
425-
~vws.exceptions.AuthenticationFailure: The secret key is not
426-
correct.
427-
~vws.exceptions.Fail: There was an error with the request. For
428-
example, the given access key does not match a known database.
429-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
430-
time sent to Vuforia.
436+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
437+
key is not correct.
438+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
439+
request. For example, the given access key does not match a
440+
known database.
441+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
442+
error with the time sent to Vuforia.
431443
"""
432444
response = self._make_request(
433445
method='GET',
@@ -464,16 +476,17 @@ def delete_target(self, target_id: str) -> None:
464476
target_id: The ID of the target to delete.
465477
466478
Raises:
467-
~vws.exceptions.AuthenticationFailure: The secret key is not
468-
correct.
469-
~vws.exceptions.Fail: There was an error with the request. For
470-
example, the given access key does not match a known database.
471-
~vws.exceptions.UnknownTarget: The given target ID does not match a
472-
target in the database.
473-
~vws.exceptions.TargetStatusProcessing: The given target is in the
474-
processing state.
475-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
476-
time sent to Vuforia.
479+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
480+
key is not correct.
481+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
482+
request. For example, the given access key does not match a
483+
known database.
484+
~vws.exceptions.vws_exceptions.UnknownTarget: The given target ID
485+
does not match a target in the database.
486+
~vws.exceptions.vws_exceptions.TargetStatusProcessing: The given
487+
target is in the processing state.
488+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
489+
error with the time sent to Vuforia.
477490
"""
478491
self._make_request(
479492
method='DELETE',
@@ -496,15 +509,17 @@ def get_duplicate_targets(self, target_id: str) -> List[str]:
496509
The target IDs of duplicate targets.
497510
498511
Raises:
499-
~vws.exceptions.AuthenticationFailure: The secret key is not
500-
correct.
501-
~vws.exceptions.Fail: There was an error with the request. For
502-
example, the given access key does not match a known database.
503-
~vws.exceptions.UnknownTarget: The given target ID does not match a
504-
target in the database.
505-
~vws.exceptions.ProjectInactive: The project is inactive.
506-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
507-
time sent to Vuforia.
512+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
513+
key is not correct.
514+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
515+
request. For example, the given access key does not match a
516+
known database.
517+
~vws.exceptions.vws_exceptions.UnknownTarget: The given target ID
518+
does not match a target in the database.
519+
~vws.exceptions.vws_exceptions.ProjectInactive: The project is
520+
inactive.
521+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
522+
error with the time sent to Vuforia.
508523
"""
509524
response = self._make_request(
510525
method='GET',
@@ -545,21 +560,25 @@ def update_target(
545560
Giving ``None`` will not change the application metadata.
546561
547562
Raises:
548-
~vws.exceptions.AuthenticationFailure: The secret key is not
549-
correct.
550-
~vws.exceptions.BadImage: There is a problem with the given image.
551-
For example, it must be a JPEG or PNG file in the grayscale or
552-
RGB color space.
553-
~vws.exceptions.Fail: There was an error with the request. For
554-
example, the given access key does not match a known database.
555-
~vws.exceptions.MetadataTooLarge: The given metadata is too large.
556-
The maximum size is 1 MB of data when Base64 encoded.
557-
~vws.exceptions.ImageTooLarge: The given image is too large.
558-
~vws.exceptions.TargetNameExist: A target with the given ``name``
559-
already exists.
560-
~vws.exceptions.ProjectInactive: The project is inactive.
561-
~vws.exceptions.RequestTimeTooSkewed: There is an error with the
562-
time sent to Vuforia.
563+
~vws.exceptions.vws_exceptions.AuthenticationFailure: The secret
564+
key is not correct.
565+
~vws.exceptions.vws_exceptions.BadImage: There is a problem with
566+
the given image. For example, it must be a JPEG or PNG file in
567+
the grayscale or RGB color space.
568+
~vws.exceptions.vws_exceptions.Fail: There was an error with the
569+
request. For example, the given access key does not match a
570+
known database.
571+
~vws.exceptions.vws_exceptions.MetadataTooLarge: The given metadata
572+
is too large. The maximum size is 1 MB of data when Base64
573+
encoded.
574+
~vws.exceptions.vws_exceptions.ImageTooLarge: The given image is
575+
too large.
576+
~vws.exceptions.vws_exceptions.TargetNameExist: A target with the
577+
given ``name`` already exists.
578+
~vws.exceptions.vws_exceptions.ProjectInactive: The project is
579+
inactive.
580+
~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
581+
error with the time sent to Vuforia.
563582
"""
564583
data: Dict[str, Union[str, bool, float, int]] = {}
565584

0 commit comments

Comments
 (0)