Refactor transifex.api's exceptions for down/uploads

Previously, for uploads and downloads we could get a "successful"
response that includes an error report for a download or upload. This
means that as far as {json:api} semantics go, no error has happened.
However, we intercepted this response and raised it as if it was a
{json:api} exception.

This raising was buggy because it didn't use the `JsonApiException.new`
invocation (and thus can't be captured with `JsonApiException.get`) and
also it didn't have the third required argument which was the response.

Instead of fixing the aforementioned bugs however, we decided to
implement new exception classes in `transifex.api` (which is the SDK
itself, as opposed to `transifex.api.jsonapi` which is the "SDK
library"). This makes it clearer to the user that as far as the
{json:api} semantics are concerned, no error has occured. The problem is
that the download or upload "job"'s status (which was successfully
retrieved) is reporting an error.

The new exception classes give priority to their first argument which is
the 'detail' field of the first error included in the response. The rest
of the errors, if any, will be accessible from the exception's second
argument. Keep in mind that at the time of writing, Transifex APIv3 will
only include one error in the case of an unsuccessful upload or
download.

Author: Konstantinos Bairaktaris

transifex/api/__init__.py

@@ -2,9 +2,9 @@
 
 import transifex
 
+from .exceptions import DownloadException, UploadException
 from .jsonapi import JsonApi
 from .jsonapi import Resource as JsonApiResource
-from .jsonapi.exceptions import JsonApiException
 
 
 class DownloadMixin(object):
@@ -19,16 +19,11 @@ def download(cls, interval=5, *args, **kwargs):
         download = cls.create(*args, **kwargs)
         while True:
             if hasattr(download, "errors") and len(download.errors) > 0:
-                errors = [
-                    {
-                        "code": e["code"],
-                        "detail": e["detail"],
-                        "title": e["detail"],
-                        "status": "409",
-                    }
-                    for e in download.errors
-                ]
-                raise JsonApiException(409, errors)
+                # The way Transifex APIv3 works right now, only one error will be
+                # returned, so we give priority to the first error's 'detail' field. If
+                # more errors are included in the future, the user can inspect the
+                # exception's second argument
+                raise DownloadException(download.error[0]["detail"], download.errors)
             if download.redirect:
                 return download.redirect
             time.sleep(interval)
@@ -54,16 +49,11 @@ def upload(cls, content, interval=5, **data):
 
         while True:
             if hasattr(upload, "errors") and len(upload.errors) > 0:
-                errors = [
-                    {
-                        "code": e["code"],
-                        "detail": e["detail"],
-                        "title": e["detail"],
-                        "status": "409",
-                    }
-                    for e in upload.errors
-                ]
-                raise JsonApiException(409, errors)
+                # The way Transifex APIv3 works right now, only one error will be
+                # returned, so we give priority to the first error's 'detail' field. If
+                # more errors are included in the future, the user can inspect the
+                # exception's second argument
+                raise UploadException(upload.errors[0]["detail"], upload.errors)
 
             if upload.redirect:
                 return upload.follow()

transifex/api/exceptions.py

@@ -0,0 +1,35 @@
+class FileExchangeException(Exception):
+    def __init__(self, message, errors):
+        super().__init__(message, errors)
+
+    @property
+    def message(self):
+        return self.args[0]
+
+    @property
+    def errors(self):
+        return self.args[1]
+
+    def __str__(self):
+        """We expect Transifex APIv3 to only return one error during a file exchange.
+        Even though for future compatibility we include the full list of errors in the
+        exception objects, we override 'str' so that if someone does:
+
+        >>> try:
+        ...     transifex_api.ResourceStringsAsyncUpload(...)
+        ... except UploadException as e:
+        ...     print(f"Upload error: {e}")
+
+        We want the first error's 'detail' field to appear. The full error list
+        can still be accessed via the second argument.
+        """
+
+        return self.message
+
+
+class DownloadException(FileExchangeException):
+    pass
+
+
+class UploadException(FileExchangeException):
+    pass