Version 1.2.0

* Added exception for 429 status code and improved tests

* Updated gitignore

* Renamed exception classes

* Updated README files

* Flake8 and version bump

Author: roedesh

.editorconfig

@@ -3,3 +3,13 @@ end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
+
+[*.py]
+max_line_length = 80
+
+[*.json]
+indent_size = 2
+insert_final_newline = ignore
+
+[Makefile]
+indent_style = tab

.gitignore

@@ -8,12 +8,10 @@ __pycache__/
 build/
 dist/
 
-# OS generated files
-.idea
-
 # Unit test / coverage reports
 htmlcov/
 .coverage
 
 # IDE
 .vscode
+.idea

README.md

@@ -1,6 +1,6 @@
 # postcodeapi
 
-`postcodeapi` is a tiny Python wrapper around the Postcode API V2.
+`postcodeapi` is an unofficial Python wrapper around the Postcode API V2.
 
 [![PyPI version](https://badge.fury.io/py/postcodeapi.svg)](https://badge.fury.io/py/postcodeapi)
 [![Build Status](https://travis-ci.org/roedesh/postcodeapi.svg?branch=master)](https://travis-ci.org/roedesh/postcodeapi)
@@ -11,7 +11,7 @@
 
 ### Installation
 
-*postcodeapi* can be installed by running `pip install postcodeapi`.
+_postcodeapi_ can be installed by running `pip install postcodeapi`.
 
 ### Usage
 
@@ -31,6 +31,7 @@ client = PostcodeAPIClient(api_key="YOUR_API_KEY")
 # The number parameter only works together with postal_code
 data = client.get_all_addresses(postal_code="5038EA", number=19)
 addresses = data["results"] # List of addresses
+next_id = data["next"] # Next ID to search from (used for pagination)
 
 # Fetch a single address
 address = client.get_address(address_id="0855200000046355")
@@ -39,17 +40,31 @@ address = client.get_address(address_id="0855200000046355")
 # The area parameter is optional
 data = client.get_all_postal_codes(area="5038")
 postal_codes = data["results"] # List of postal codes
+next_postal_code = data["next"] # Next postal code to search from (used for pagination)
 
 # Fetch a single postal code
 postal_code = client.get_postal_code("5038EA")
 ```
 
+### Exceptions
+
+There are 5 exceptions that can occur:
+
+- `NoAccessException`, which occurs when the current account does not have the required privileges to perform the action;
+- `ResourceNotFoundException`, which occurs when the returned status_code is 404. Limited to the *get_address* and *get_postal_code* methods;
+- `HouseNumberRequiresPostalCodeException`, which occurs when a house_number is given but not a postal_code. Limited to the *get_all_addresses* method;
+- `InvalidPostalCodeException`, which occurs when an invalid postal code is given;
+- `LimitExceededException`, which occurs when there are too many network requests or the limit has been exceeded
+
 ## Documentation
+
 For more information about the data that is returned, please refer to the [official API documentation](https://www.postcodeapi.nu/docs/). It is written in Dutch.
 
 ## Running tests
-To run the tests, make sure you have the dev dependencies installed, and run `pytest` in the root of the project.
+
+To run the tests, make sure you install the dev dependencies by running `pipenv install --dev`, and then run `pytest` in the root of the project.
 
 ## Issues
+
 If you have any issues with the API wrapper, please post them [here](https://github.com/infoklik/postcodeapi/issues). If you have issues with the actual API,
 please post them in the [official issue tracker](https://github.com/postcodeapi/postcodeapi/issues) of Postcode API.

README.rst

@@ -1,7 +1,8 @@
 postcodeapi
 ===========
 
-``postcodeapi`` is a tiny Python wrapper around the Postcode API V2.
+``postcodeapi`` is an unofficial Python wrapper around the Postcode API
+V2.
 
 |PyPI version| |Build Status| |Requirements Status| |Coverage Status|
 
@@ -34,6 +35,7 @@ response converted to a Python dictionary.
    # The number parameter only works together with postal_code
    data = client.get_all_addresses(postal_code="5038EA", number=19)
    addresses = data["results"] # List of addresses
+   next_id = data["next"] # Next ID to search from (used for pagination)
 
    # Fetch a single address
    address = client.get_address(address_id="0855200000046355")
@@ -42,10 +44,29 @@ response converted to a Python dictionary.
    # The area parameter is optional
    data = client.get_all_postal_codes(area="5038")
    postal_codes = data["results"] # List of postal codes
+   next_postal_code = data["next"] # Next postal code to search from (used for pagination)
 
    # Fetch a single postal code
    postal_code = client.get_postal_code("5038EA")
 
+Exceptions
+~~~~~~~~~~
+
+There are 5 exceptions that can occur:
+
+-  ``NoAccessException``, which occurs when the current account does not
+   have the required privileges to perform the action;
+-  ``ResourceNotFoundException``, which occurs when the returned
+   status_code is 404. Limited to the *get_address* and
+   *get_postal_code* methods;
+-  ``HouseNumberRequiresPostalCodeException``, which occurs when a
+   house_number is given but not a postal_code. Limited to the
+   *get_all_addresses* method;
+-  ``InvalidPostalCodeException``, which occurs when an invalid postal
+   code is given;
+-  ``LimitExceededException``, which occurs when there are too many
+   network requests or the limit has been exceeded
+
 Documentation
 -------------
 
@@ -55,19 +76,10 @@ the `official API documentation`_. It is written in Dutch.
 Running tests
 -------------
 
-To run the tests, make sure you have the dev dependencies installed, and
-run ``pytest`` in the root of the project.
-
-Issues
-------
-
-If you have any issues with the API wrapper, please post them `here`_.
-If you have issues with the actual API, please post them in the
-`official issue tracker`_ of Postcode API.
+To run the tests, make sure you install the dev dependencies by running
+``pipenv install --dev``, and then run
 
 .. _official API documentation: https://www.postcodeapi.nu/docs/
-.. _here: https://github.com/infoklik/postcodeapi/issues
-.. _official issue tracker: https://github.com/postcodeapi/postcodeapi/issues
 
 .. |PyPI version| image:: https://badge.fury.io/py/postcodeapi.svg
    :target: https://badge.fury.io/py/postcodeapi

postcodeapi/client.py

@@ -2,6 +2,7 @@
 from urllib.parse import parse_qs, urlencode, urlparse
 
 import requests
+
 from postcodeapi import exceptions
 from postcodeapi.utils import is_valid_postal_code
 
@@ -35,13 +36,13 @@ def generate_list_result(data, identifier="addresses"):
     if next_url:
         parsed_qs = parse_qs(urlparse(next_url).query)
         if identifier == "addresses":
-            next = parsed_qs.get("from[id]", None)
+            next_val = parsed_qs.get("from[id]", None)
         else:
-            next = parsed_qs.get("from[postcode]", None)
+            next_val = parsed_qs.get("from[postcode]", None)
     else:
-        next = None
+        next_val = None
 
-    return {"results": results, "next": next}
+    return {"results": results, "next": next_val}
 
 
 class PostcodeAPIClient:
@@ -78,9 +79,15 @@ def _do_request(self, endpoint, querystring=None):
         )
         data = response.text
         if response.status_code == 403:
-            raise exceptions.NoAccess
+            raise exceptions.NoAccessException(
+                "The current account is not allowed to do this"
+            )
         if response.status_code == 404:
-            raise exceptions.ResourceNotFound
+            raise exceptions.ResourceNotFoundException("Object not found")
+        if response.status_code == 429:
+            raise exceptions.LimitExceededException(
+                "Limit exceeded or too many requests"
+            )
         return json.loads(data)
 
     def get_all_addresses(self, postal_code=None, number=0, from_id=None):
@@ -97,12 +104,16 @@ def get_all_addresses(self, postal_code=None, number=0, from_id=None):
 
         if number:
             if not postal_code:
-                raise exceptions.HouseNumberRequiresPostalCode
+                raise exceptions.HouseNumberRequiresPostalCodeException(
+                    "Filtering on a house number requires a postal code"
+                )
             querystring.update({"number": number})
 
         if postal_code:
             if not is_valid_postal_code(postal_code):
-                raise exceptions.InvalidPostalCode
+                raise exceptions.InvalidPostalCodeException(
+                    "postal_code should be a valid Dutch postal code"
+                )
             querystring.update({"postcode": postal_code})
 
         if from_id:
@@ -129,7 +140,9 @@ def get_all_postal_codes(self, area=None, from_postal_code=None):
         :return: List of postal code dictionaries
         """
         if from_postal_code and not is_valid_postal_code(from_postal_code):
-            raise exceptions.InvalidPostalCode
+            raise exceptions.InvalidPostalCodeException(
+                "from_postal_code should be a valid Dutch postal code"
+            )
 
         querystring = {}
         if area:
@@ -155,5 +168,7 @@ def get_postal_code(self, postal_code):
         :return: Single postal code
         """
         if not is_valid_postal_code(postal_code):
-            raise exceptions.InvalidPostalCode
+            raise exceptions.InvalidPostalCodeException(
+                "postal_code should be a valid Dutch postal code"
+            )
         return self._do_request(POSTCODE_API_POSTAL_CODE.format(postal_code))

postcodeapi/exceptions.py

@@ -1,34 +1,18 @@
-class NoAccess(Exception):
-    """
-    This exception will be raised when a request is made which is not allowed.
-    """
+class NoAccessException(Exception):
+    pass
 
-    def __init__(self):
-        super().__init__("The current account is not allowed to do this")
 
+class ResourceNotFoundException(Exception):
+    pass
 
-class ResourceNotFound(Exception):
-    """
-    This exception will be raised when a requested object cannot be found.
-    """
 
-    def __init__(self):
-        super().__init__("Object not found")
+class HouseNumberRequiresPostalCodeException(Exception):
+    pass
 
 
-class HouseNumberRequiresPostalCode(Exception):
-    """
-    This exception will be raised when attempting to filter on a house number without providing a postal code.
-    """
+class InvalidPostalCodeException(Exception):
+    pass
 
-    def __init__(self):
-        super().__init__("Filtering on a house number requires a postal code")
 
-
-class InvalidPostalCode(Exception):
-    """
-    This exception will be raised when the user provides a value that doesn't pass the Dutch postal code regex.
-    """
-
-    def __init__(self):
-        super().__init__("The given postal code is invalid")
+class LimitExceededException(Exception):
+    pass

setup.py

@@ -2,8 +2,8 @@
 
 setup(
     name="postcodeapi",
-    version="1.1.0",
-    description="A tiny wrapper around the Postcode API v2",
+    version="1.2.0",
+    description="An unofficial Python wrapper around the Postcode API v2",
     long_description=open("README.rst").read(),
     url="http://github.com/roedesh/postcodeapi",
     author="Ruud Schroën",

tests/unit_tests/conftest.py

@@ -1,12 +1,8 @@
 import pytest
+
 from postcodeapi.client import PostcodeAPIClient
 
 
 @pytest.fixture
 def api_client():
     return PostcodeAPIClient(api_key="YOUR_KEY")
-
-
-@pytest.fixture
-def api_client_without_key():
-    return PostcodeAPIClient(api_key="")

tests/unit_tests/helpers.py

@@ -5,3 +5,7 @@ def read_file(file_name, folder="mocks"):
     file = join(dirname(realpath(__file__)), folder, file_name)
     with open(file) as f:
         return f.read()
+
+
+def get_api_url(path):
+    return "https://api.postcodeapi.nu/v2/{}".format(path)