Version 1.1.0

* Improved tests and modified data dictionary

* Added README.rst and updated Pipfile

* Updated setup.py to use README.rst

Author: roedesh

.editorconfig

@@ -1,9 +1,5 @@
-# EditorConfig helps developers define and maintain consistent
-# coding styles between different editors and IDEs
-# editorconfig.org
-
 [*]
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
-insert_final_newline = true
+insert_final_newline = true

.gitignore

@@ -13,4 +13,7 @@ dist/
 
 # Unit test / coverage reports
 htmlcov/
-.coverage
+.coverage
+
+# IDE
+.vscode

.travis.yml

@@ -3,11 +3,18 @@ python:
   - "3.4"
   - "3.5"
   - "3.6"
+# Enable Python 3.7
+matrix:
+  include:
+    - python: 3.7
+      dist: xenial
+      sudo: true
 install:
-  - 'pip install pipenv'
-  - 'pipenv sync --dev'
+  - 'pip install pytest'
+  - 'pip install pytest-cov'
   - 'pip install coveralls'
+  - 'pip install requests-mock'
 script:
-  - 'pipenv run pytest'
+  - 'pytest'
 after_success:
   - 'coveralls'

Pipfile

@@ -7,9 +7,12 @@ name = "pypi"
 requests = "*"
 
 [dev-packages]
-mock = "*"
-pytest = "==4.0.0"
-pytest-mock = "==1.10.0"
-pytest-cov = "==2.6.0"
+pytest = "*"
+pytest-cov = "*"
 "pathlib2" = "*"
 scandir = "*"
+black = "*"
+requests-mock = "*"
+
+[pipenv]
+allow_prereleases = true

Pipfile.lock

@@ -15,8 +15,8 @@
 
 ### Usage
 
-Here is an example of how to use the API client. First you initialize a client with your API key, after that you use 
-one of the four getter methods to fetch the data you need. They all return the actual JSON response converted to a 
+Here is an example of how to use the API client. First you initialize a client with your API key, after that you use
+one of the four getter methods to fetch the data you need. They all return the actual JSON response converted to a
 Python dictionary.
 
 ```python
@@ -30,15 +30,15 @@ client = PostcodeAPIClient(api_key="YOUR_API_KEY")
 # The postal_code and number parameters are optional
 # The number parameter only works together with postal_code
 data = client.get_all_addresses(postal_code="5038EA", number=19)
-addresses = data["_embedded"]["addresses"] # List of addresses
+addresses = data["results"] # List of addresses
 
 # Fetch a single address
 address = client.get_address(address_id="0855200000046355")
 
-# Fetch a list of postal codes (within a specific area) 
+# Fetch a list of postal codes (within a specific area)
 # The area parameter is optional
 data = client.get_all_postal_codes(area="5038")
-postal_codes = data['_embedded']['postcodes'] # List of postal codes
+postal_codes = data["results"] # List of postal codes
 
 # Fetch a single postal code
 postal_code = client.get_postal_code("5038EA")
@@ -51,5 +51,5 @@ For more information about the data that is returned, please refer to the [offic
 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](https://github.com/infoklik/postcodeapi/issues). If you have issues with the actual API, 
+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.md

@@ -0,0 +1,79 @@
+postcodeapi
+===========
+
+``postcodeapi`` is a tiny Python wrapper around the Postcode API V2.
+
+|PyPI version| |Build Status| |Requirements Status| |Coverage Status|
+
+Installation and usage
+----------------------
+
+Installation
+~~~~~~~~~~~~
+
+*postcodeapi* can be installed by running ``pip install postcodeapi``.
+
+Usage
+~~~~~
+
+Here is an example of how to use the API client. First you initialize a
+client with your API key, after that you use one of the four getter
+methods to fetch the data you need. They all return the actual JSON
+response converted to a Python dictionary.
+
+.. code:: python
+
+   # Import the PostcodeAPIClient
+   from postcodeapi.client import PostcodeAPIClient
+
+   # Initialize a client with your API key
+   client = PostcodeAPIClient(api_key="YOUR_API_KEY")
+
+   # Fetch a list of addresses (for a given postal_code and number)
+   # The postal_code and number parameters are optional
+   # 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
+
+   # Fetch a single address
+   address = client.get_address(address_id="0855200000046355")
+
+   # Fetch a list of postal codes (within a specific area)
+   # The area parameter is optional
+   data = client.get_all_postal_codes(area="5038")
+   postal_codes = data["results"] # List of postal codes
+
+   # Fetch a single postal code
+   postal_code = client.get_postal_code("5038EA")
+
+Documentation
+-------------
+
+For more information about the data that is returned, please refer to
+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.
+
+.. _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
+.. |Build Status| image:: https://travis-ci.org/roedesh/postcodeapi.svg?branch=master
+   :target: https://travis-ci.org/roedesh/postcodeapi
+.. |Requirements Status| image:: https://requires.io/github/roedesh/postcodeapi/requirements.svg?branch=master
+   :target: https://requires.io/github/roedesh/postcodeapi/requirements/?branch=master
+.. |Coverage Status| image:: https://coveralls.io/repos/github/roedesh/postcodeapi/badge.svg?branch=master
+   :target: https://coveralls.io/github/roedesh/postcodeapi?branch=master

README.rst

@@ -1,8 +1,7 @@
 import json
-from urllib.parse import urlencode
+from urllib.parse import parse_qs, urlencode, urlparse
 
 import requests
-
 from postcodeapi import exceptions
 from postcodeapi.utils import is_valid_postal_code
 
@@ -13,25 +12,56 @@
 POSTCODE_API_POSTAL_CODE = "postcodes/{}"
 
 
+def generate_list_result(data, identifier="addresses"):
+    """Generate a dictionary with the results and the next id or
+    postal code if it's available.
+
+
+    Arguments:
+        data {dict} -- Data dictionary
+
+    Keyword Arguments:
+        identifier {str} -- Dictionary key which holds the results (default: {"addresses"})
+
+    Returns:
+        dict -- Dictionary with the results and the next id or
+                postal code
+    """
+
+    results = data.get("_embedded", {}).get(identifier, {})
+    next_url = data.get("_links", {}).get("next", {}).get("href", "")
+
+    # Extract the id or postal code from the "next" url querystring
+    if next_url:
+        parsed_qs = parse_qs(urlparse(next_url).query)
+        if identifier == "addresses":
+            next = parsed_qs.get("from[id]", None)
+        else:
+            next = parsed_qs.get("from[postcode]", None)
+    else:
+        next = None
+
+    return {"results": results, "next": next}
+
+
 class PostcodeAPIClient:
     """
     A wrapper around the Postcode API V2.
-    It allows to filter trough addresses and postal codes.
+    It allows for filtering trough addresses and postal codes.
 
-    All getter methods return JSON data as a Python object.
+    All getter methods return JSON data as a Python dictionary.
 
     Full documentation can be found on https://www.postcodeapi.nu/docs/
     """
 
-    def __init__(self, api_key, compact=False):
+    def __init__(self, api_key):
         """
         Initializes a new API client for the Postcode API v2. Requires an API key.
         Upon initialization the required headers will be pre-set for later use.
 
         :param api_key: Postcode API V2 key
         """
         self._headers = {"x-api-key": api_key, "accept": "application/hal+json"}
-        self.compact = compact
 
     def _do_request(self, endpoint, querystring=None):
         """
@@ -53,22 +83,33 @@ def _do_request(self, endpoint, querystring=None):
             raise exceptions.ResourceNotFound
         return json.loads(data)
 
-    def get_all_addresses(self, postal_code=None, number=0, from_id=""):
+    def get_all_addresses(self, postal_code=None, number=0, from_id=None):
         """
-        Return a list of addresses. Can be filtered by providing a postal code and/or house number.
+        Return a list of addresses. Can be filtered by providing a postal code and house number.
         Filtering on a house number requires a postal code
 
-        :param postal_code: Postal code to filter on
+        :param postal_code: (Optional) Postal code to filter on
         :param number: (Optional) House number to filter on
         :param from_id: (Optional) The address ID to start from
         :return: List of address dictionaries
         """
-        if number and not postal_code:
-            raise exceptions.HouseNumberRequiresPostalCode
-        if postal_code and not is_valid_postal_code(postal_code):
-            raise exceptions.InvalidPostalCode
-        querystring = {"postcode": postal_code, "number": number, "from[id]": from_id}
-        return self._do_request(POSTCODE_API_ALL_ADDRESSES, querystring)
+        querystring = {}
+
+        if number:
+            if not postal_code:
+                raise exceptions.HouseNumberRequiresPostalCode
+            querystring.update({"number": number})
+
+        if postal_code:
+            if not is_valid_postal_code(postal_code):
+                raise exceptions.InvalidPostalCode
+            querystring.update({"postcode": postal_code})
+
+        if from_id:
+            querystring.update({"from[id]": from_id})
+
+        data = self._do_request(POSTCODE_API_ALL_ADDRESSES, querystring)
+        return generate_list_result(data, "addresses")
 
     def get_address(self, address_id):
         """
@@ -77,10 +118,9 @@ def get_address(self, address_id):
         :param address_id: ID of the address
         :return: Single address based on ID
         """
-        data = self._do_request(POSTCODE_API_ADDRESS.format(address_id))
-        return data
+        return self._do_request(POSTCODE_API_ADDRESS.format(address_id))
 
-    def get_all_postal_codes(self, area=None, from_postal_code=""):
+    def get_all_postal_codes(self, area=None, from_postal_code=None):
         """
         Return a list of postal codes. Can be filtered based on a given postal area.
 
@@ -90,14 +130,22 @@ def get_all_postal_codes(self, area=None, from_postal_code=""):
         """
         if from_postal_code and not is_valid_postal_code(from_postal_code):
             raise exceptions.InvalidPostalCode
-        querystring = {
-            "postcodeArea": area,
-            "from[postcode]": from_postal_code,
-            # We need to provide both from[postcode] and from[postcodeArea] in order for pagination to work
-            # So we use the four numbers from the postal code as the area code
-            "from[postcodeArea]": from_postal_code[:4],
-        }
-        return self._do_request(POSTCODE_API_ALL_POSTAL_CODES, querystring)
+
+        querystring = {}
+        if area:
+            querystring.update({"postcodeArea": area})
+
+        if from_postal_code:
+            querystring.update(
+                {
+                    "from[postcode]": from_postal_code,
+                    # We need to provide both from[postcode] and from[postcodeArea] in order for pagination to work
+                    # So we use the four numbers from the postal code as the area code
+                    "from[postcodeArea]": from_postal_code[:4],
+                }
+            )
+        data = self._do_request(POSTCODE_API_ALL_POSTAL_CODES, querystring)
+        return generate_list_result(data, "postcodes")
 
     def get_postal_code(self, postal_code):
         """

postcodeapi/client.py

@@ -2,9 +2,9 @@
 
 setup(
     name="postcodeapi",
-    version="1.0.2",
+    version="1.1.0",
     description="A tiny wrapper around the Postcode API v2",
-    long_description=open("README.md").read(),
+    long_description=open("README.rst").read(),
     url="http://github.com/roedesh/postcodeapi",
     author="Ruud Schroën",
     author_email="schroenruud@gmail.com",