Merge branch 'release-0.12.0'

Author: dnl-blkv

.gitattributes

@@ -1 +1 @@
-bunq/sdk/model/generated linguist-generated=true
+bunq/sdk/model/generated/* linguist-generated=true

.gitignore

@@ -89,6 +89,6 @@ bunq.conf
 bunq-test.conf
 **/tmp
 config.json
-tests/connectQr.png
+connectQr.png
 .DS_Store
 bunq_sdk.egg-info

EXCEPTIONS.md

@@ -0,0 +1,69 @@
+## Exceptions
+When you make a request via the SDK, there is a chance of request failing
+due to various reasons. When such a failure happens, an exception
+corresponding to the error occurred is raised.
+
+
+----
+#### Possible Exceptions
+* `BadRequestException` If the request returns with status code `400`
+* `UnauthorizedException` If the request returns with status code `401`
+* `ForbiddenException` If the request returns with status code `403`
+* `NotFoundException` If the request returns with status code `404`
+* `MethodNotAllowedException` If the request returns with status code `405`
+* `TooManyRequestsException` If the request returns with status code `429`
+* `PleaseContactBunqException` If the request returns with status code `500`.
+If you get this exception, please contact us preferably via the support chat in the bunq app.
+* `UnknownApiErrorException` If none of the above mentioned exceptions are raised,
+this exception will be raised instead.
+
+For more information regarding these errors, please take a look on the documentation
+page here: https://doc.bunq.com/api/1/page/errors
+
+---
+#### Base exception
+All the exceptions have the same base exception which looks like this:
+```python
+class ApiException(Exception):
+    def __init__(self, message, response_code):
+        pass
+        
+    @property
+    def message(self):
+        """
+        :rtype: str
+        """
+
+        return self._message
+
+    @property
+    def response_code(self):
+        """
+        :rtype: int
+        """
+
+        return self._response_code
+```
+This means that each exception will have the response code and the error message 
+related to the specific exception that has been raised.
+
+---
+#### Exception handling
+Because we raise different exceptions for each error, you can catch an error
+if you expect it to be raised.
+
+```python
+from bunq.sdk.exception import BadRequestException
+from bunq.sdk.context import ApiEnvironmentType, ApiContext
+
+API_KEY = "Some invalid API key"
+DESCRIPTION = "This wil raise a BadRequestException"
+
+try:
+    # Make a call that might raise an exception
+    ApiContext(ApiEnvironmentType.SANDBOX, API_KEY, DESCRIPTION)
+except BadRequestException as error:
+    # Do something if exception is raised
+    print(error.response_code)
+    print(error.message) # or just print(error)
+```

README.md

@@ -183,3 +183,7 @@ Please do not forget to set the `_API_KEY` constant in
 
 Information regarding the test cases can be found in the [README.md](./tests/README.md)
 located in [test](/tests)
+
+## Exceptions
+The SDK can raise multiple exceptions. For an overview of these exceptions please
+take a look at [EXCEPTIONS.md](./EXCEPTIONS.md)

VERSION

@@ -1 +1 @@
-0.11.0
+0.12.0

bunq/__init__.py

@@ -1,3 +1,42 @@
-from bunq.sdk.json import registry
+from bunq.sdk.json import converter
 
-registry.initialize()
+
+def initialize_converter():
+    """
+    :rtype: None
+    """
+
+    import datetime
+
+    from bunq.sdk import client
+    from bunq.sdk import context
+    from bunq.sdk.model import core
+    from bunq.sdk.json import adapters
+    from bunq.sdk.json import converter
+    from bunq.sdk.model.generated import object_
+
+    converter.register_adapter(core.Installation, adapters.InstallationAdapter)
+    converter.register_adapter(
+        core.SessionServer,
+        adapters.SessionServerAdapter
+    )
+    converter.register_adapter(
+        context.InstallationContext,
+        adapters.InstallationContextAdapter
+    )
+    converter.register_adapter(
+        context.ApiEnvironmentType,
+        adapters.ApiEnvironmentTypeAdapter
+    )
+    converter.register_adapter(float, adapters.FloatAdapter)
+    converter.register_adapter(object_.Geolocation, adapters.GeolocationAdapter)
+    converter.register_adapter(
+        object_.MonetaryAccountReference,
+        adapters.MonetaryAccountReferenceAdapter
+    )
+    converter.register_adapter(object_.ShareDetail, adapters.ShareDetailAdapter)
+    converter.register_adapter(datetime.datetime, adapters.DateTimeAdapter)
+    converter.register_adapter(client.Pagination, adapters.PaginationAdapter)
+
+
+converter.set_initializer_function(initialize_converter)

bunq/sdk/client.py

@@ -4,15 +4,15 @@
 
 import requests
 
-from bunq.sdk import context
 from bunq.sdk import exception
 from bunq.sdk import security
+from bunq.sdk.exception_factory import ExceptionFactory
 from bunq.sdk.json import converter
 
 
 class ApiClient(object):
     """
-    :type _api_context: context.ApiContext
+    :type _api_context: bunq.sdk.context.ApiContext
     """
 
     # HTTPS type of proxy, the only used at bunq
@@ -31,7 +31,7 @@ class ApiClient(object):
     HEADER_AUTHENTICATION = 'X-Bunq-Client-Authentication'
 
     # Default header values
-    _USER_AGENT_BUNQ = 'bunq-sdk-python/0.11.0'
+    _USER_AGENT_BUNQ = 'bunq-sdk-python/0.12.0'
     _GEOLOCATION_ZERO = '0 0 0 0 NL'
     _LANGUAGE_EN_US = 'en_US'
     _REGION_NL_NL = 'nl_NL'
@@ -201,7 +201,7 @@ def _assert_response_success(self, response):
         """
 
         if response.status_code != self._STATUS_CODE_OK:
-            raise exception.ApiException(
+            raise ExceptionFactory.create_exception_for_response(
                 response.status_code,
                 self._fetch_error_messages(response)
             )
@@ -372,6 +372,18 @@ def pagination(self):
 
         return self._pagination
 
+    @classmethod
+    def cast_from_bunq_response(cls, bunq_response):
+        """
+        :type bunq_response: BunqResponse
+        """
+
+        return cls(
+            bunq_response.value,
+            bunq_response.headers,
+            bunq_response.pagination
+        )
+
 
 class Pagination(object):
     """

bunq/sdk/context.py

@@ -3,10 +3,10 @@
 import aenum
 from Cryptodome.PublicKey import RSA
 
-from bunq.sdk import model
+from bunq.sdk.model import core
 from bunq.sdk import security
 from bunq.sdk.json import converter
-from bunq.sdk.model import generated
+from bunq.sdk.model.generated import endpoint
 
 
 class ApiEnvironmentType(aenum.AutoNumberEnum):
@@ -95,7 +95,7 @@ def _initialize_installation(self):
         """
 
         private_key_client = security.generate_rsa_private_key()
-        installation = model.Installation.create(
+        installation = core.Installation.create(
             self,
             security.public_key_to_string(private_key_client.publickey())
         ).value
@@ -119,12 +119,12 @@ def _register_device(self, device_description,
         :rtype: None
         """
 
-        generated.DeviceServer.create(
+        endpoint.DeviceServer.create(
             self,
             {
-                generated.DeviceServer.FIELD_DESCRIPTION: device_description,
-                generated.DeviceServer.FIELD_SECRET: self.api_key,
-                generated.DeviceServer.FIELD_PERMITTED_IPS: permitted_ips,
+                endpoint.DeviceServer.FIELD_DESCRIPTION: device_description,
+                endpoint.DeviceServer.FIELD_SECRET: self.api_key,
+                endpoint.DeviceServer.FIELD_PERMITTED_IPS: permitted_ips,
             }
         )
 
@@ -133,7 +133,7 @@ def _initialize_session(self):
         :rtype: None
         """
 
-        session_server = model.SessionServer.create(self).value
+        session_server = core.SessionServer.create(self).value
         token = session_server.token.token
         expiry_time = self._get_expiry_timestamp(session_server)
 
@@ -142,7 +142,7 @@ def _initialize_session(self):
     @classmethod
     def _get_expiry_timestamp(cls, session_server):
         """
-        :type session_server: model.SessionServer
+        :type session_server: core.SessionServer
 
         :rtype: datetime.datetime
         """
@@ -155,7 +155,7 @@ def _get_expiry_timestamp(cls, session_server):
     @classmethod
     def _get_session_timeout_seconds(cls, session_server):
         """
-        :type session_server: model.SessionServer
+        :type session_server: core.SessionServer
 
         :rtype: int
         """
@@ -210,7 +210,7 @@ def _delete_session(self):
         :rtype: None
         """
 
-        generated.Session.delete(self, self._SESSION_ID_DUMMY)
+        endpoint.Session.delete(self, self._SESSION_ID_DUMMY)
 
     @property
     def environment_type(self):
@@ -300,7 +300,7 @@ def restore(cls, path=None):
 
         with open(path, cls._FILE_MODE_READ) as file_:
             return cls.from_json(file_.read())
-        
+
     @classmethod
     def from_json(cls, json_str):
         """

bunq/sdk/exception.py

@@ -1,44 +1,22 @@
 class ApiException(Exception):
-    """
-    :type _response_code: int
-    """
-
-    # Constants for formatting messages
-    _FORMAT_RESPONSE_CODE_LINE = 'HTTP Response Code: {}'
-    _GLUE_ERROR_MESSAGES = '\n'
-
-    def __init__(self, response_code, messages):
+    def __init__(self, message, response_code):
         """
+        :type message: str
         :type response_code: int
-        :type messages: list[str]
         """
 
-        super(ApiException, self).__init__(
-            self.generate_message_error(response_code, messages)
-        )
+        self._message = message
         self._response_code = response_code
 
-    def generate_message_error(self, response_code, messages):
-        """
-        :type response_code: int
-        :type messages: list[str]
-
-        :rtype: str
-        """
-
-        line_response_code = self._FORMAT_RESPONSE_CODE_LINE \
-            .format(response_code)
-
-        return self.glue_messages([line_response_code] + messages)
+        super(ApiException, self).__init__(message)
 
-    def glue_messages(self, messages):
+    @property
+    def message(self):
         """
-        :type messages: list[str]
-
         :rtype: str
         """
 
-        return self._GLUE_ERROR_MESSAGES.join(messages)
+        return self._message
 
     @property
     def response_code(self):
@@ -52,3 +30,35 @@ def response_code(self):
 class BunqException(Exception):
     def __init__(self, message):
         super(BunqException, self).__init__(message)
+
+
+class UnknownApiErrorException(ApiException):
+    pass
+
+
+class BadRequestException(ApiException):
+    pass
+
+
+class UnauthorizedException(ApiException):
+    pass
+
+
+class ForbiddenException(ApiException):
+    pass
+
+
+class NotFoundException(ApiException):
+    pass
+
+
+class MethodNotAllowedException(ApiException):
+    pass
+
+
+class TooManyRequestsException(ApiException):
+    pass
+
+
+class PleaseContactBunqException(ApiException):
+    pass