Merge pull request #2 from iMicknl/refactor_and_add_endpoints

Expose more endpoints and refactor

Author: iMicknl

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## 0.2 - 2018-01-24
+### Added
+- Basic test function
+- Add function to retrieve letter status
+- Add function to retrieve single letter
+- Add function to retrieve single shipment
+
+### Fixed
+- Fixed the docstring notation
+- Better exception handling & less code duplication
+
 ## 0.1 - 2017-10-21
 ### Added
 - Initial (private) release

postnl_api/postnl_api.py

@@ -1,27 +1,27 @@
-"""
-Python wrapper for the PostNL API
-"""
+""" Python wrapper for the PostNL API """
 
 import logging
-from datetime import datetime
+from datetime import datetime, timedelta
 import requests
 
-_LOGGER = logging.getLogger(__name__)
-
 BASE_URL = 'https://jouw.postnl.nl'
 
 AUTHENTICATE_URL = BASE_URL + '/mobile/token'
 SHIPMENTS_URL = BASE_URL + '/mobile/api/shipments'
 PROFILE_URL = BASE_URL + '/mobile/api/profile'
 LETTERS_URL = BASE_URL + '/mobile/api/letters'
+VALIDATE_LETTERS_URL = BASE_URL + '/mobile/api/letters/validation'
 
-class PostNL_API(object):
+DEFAULT_HEADER = {
+    'api-version': '4.7',
+    'user-agent': 'PostNL/1 CFNetwork/889.3 Darwin/17.2.0',
+}
 
-    """
-    Interface class for the PostNL API
-    """
+class PostNL_API(object):
+    """ Interface class for the PostNL API """
 
     def __init__(self, user, password):
+        """ Constructor """
 
         self._user = user
         self._password = password
@@ -33,58 +33,47 @@ def __init__(self, user, password):
             'password': self._password
         }
 
-        headers = {
-            'api-version': '4.6',
-            'user-agent': 'PostNL/1 CFNetwork/889.3 Darwin/17.2.0',
-            'content-type': "application/x-www-form-urlencoded",
-        }
+        try:
+            response = requests.request(
+                'POST', AUTHENTICATE_URL, data=payload, headers=DEFAULT_HEADER)
+            data = response.json()
 
-        response = requests.request(
-            'POST', AUTHENTICATE_URL, data=payload, headers=headers)
+        except Exception:
+            raise(Exception)
 
-        data = response.json()
+        if 'error' in data:
+            raise Exception(data['error'])
 
         self._access_token = data['access_token']
         self._refresh_token = data['refresh_token']
-        self._token_expires_in = data['expires_in']  # TODO Add logic to refresh on invalidate
+        self._token_expires_in = data['expires_in']
+        self._token_expires_at = datetime.now() + timedelta(0, data['expires_in'])
 
-    """
-    Refresh access_token
-    """
     def refresh_token(self):
+        """ Refresh access_token """
 
         payload = {
             'grant_type': 'refresh_token',
             'client_id': 'pwIOSApp',
             'refresh_token': self._refresh_token
         }
 
-        headers = {
-            'api-version': '4.6',
-            'user-agent': 'PostNL/1 CFNetwork/889.3 Darwin/17.2.0',
-            'content-type': "application/x-www-form-urlencoded",
-        }
-
         response = requests.request(
-            'POST', AUTHENTICATE_URL, data=payload, headers=headers)
+            'POST', AUTHENTICATE_URL, data=payload, headers=DEFAULT_HEADER)
 
         data = response.json()
 
         self._access_token = data['access_token']
 
-    """
-    Retrieve shipments
-    """
     def get_shipments(self):
+        """ Retrieve shipments """
 
         headers = {
-            'api-version': '4.6',
-            'user-agent': 'PostNL/1 CFNetwork/889.3 Darwin/17.2.0',
             'authorization': 'Bearer ' + self._access_token
         }
 
         response = requests.request(
-            'GET', SHIPMENTS_URL, headers=headers)
+            'GET', SHIPMENTS_URL, headers={**headers, **DEFAULT_HEADER})
 
         if response.status_code == 401:
             self.refresh_token()
@@ -94,19 +83,33 @@ def get_shipments(self):
 
         return shipments
 
-    """
-    Retrieve profile
-    """
+    def get_shipment(self, shipment_id):
+        """ Retrieve single shipment by id """
+
+        headers = {
+            'authorization': 'Bearer ' + self._access_token
+        }
+
+        response = requests.request(
+            'GET', SHIPMENTS_URL + '/' + shipment_id, headers={**headers, **DEFAULT_HEADER})
+
+        if response.status_code == 401:
+            self.refresh_token()
+            shipments = self.get_shipment(shipment_id)
+        else:
+            shipments = response.json()
+
+        return shipments
+
     def get_profile(self):
+        """ Retrieve profile """
 
         headers = {
-            'api-version': '4.6',
-            'user-agent': 'PostNL/1 CFNetwork/889.3 Darwin/17.2.0',
             'authorization': 'Bearer ' + self._access_token
         }
 
         response = requests.request(
-            'GET', PROFILE_URL, headers=headers)
+            'GET', PROFILE_URL, headers={**headers, **DEFAULT_HEADER})
 
         if response.status_code == 401:
             self.refresh_token()
@@ -116,36 +119,69 @@ def get_profile(self):
 
         return profile
 
-    """
-    Retrieve letters
-    """
-    def get_letters(self):
+    def validate_letters(self):
+        """ Retrieve letter validation status """
 
         headers = {
-            'api-version': '4.6',
-            'user-agent': 'PostNL/1 CFNetwork/889.3 Darwin/17.2.0',
             'authorization': 'Bearer ' + self._access_token
         }
 
         response = requests.request(
-            'GET', LETTERS_URL, headers=headers)
+            'GET', VALIDATE_LETTERS_URL, headers={**headers, **DEFAULT_HEADER})
 
+        if response.status_code == 401:
+            self.refresh_token()
+            validation = self.validate_letters()
+        else:
+            validation = response.json()
+
+        return validation
+
+    def get_letters(self):
+        """ Retrieve letters """
+
+        headers = {
+            'authorization': 'Bearer ' + self._access_token
+        }
+
+        response = requests.request(
+            'GET', LETTERS_URL, headers={**headers, **DEFAULT_HEADER})
+            
         if response.status_code == 401:
             self.refresh_token()
             letters = self.get_letters()
         else:
             letters = response.json()
 
-        if letters['type'] == 'ProfileValidationFeatureMissing':
-            _LOGGER.error(letters['message'])
-            return []
+        # TODO Add validation / exception handling
+        # if letters['type'] == 'ProfileValidationFeatureMissing':
+        #     _LOGGER.error(letters['message'])
+        #     return []
 
         return letters
 
-    """
-    Retrieve relevant shipments
-    """
+    def get_letter(self, letter_id):
+        """ Retrieve single letter by id """
+
+        headers = {
+            'authorization': 'Bearer ' + self._access_token
+        }
+
+        response = requests.request(
+            'GET', LETTERS_URL + '/' + letter_id, headers={**headers, **DEFAULT_HEADER})
+
+        if response.status_code == 200:
+            letter = response.json()
+        elif response.status_code == 401:
+            self.refresh_token()
+            letter = self.get_letter(letter_id)
+        else: 
+            raise Exception('Unknown Error')
+
+        return letter
+
     def get_relevant_shipments(self):
+        """ Retrieve not delivered shipments and shipments delivered today """
 
         shipments = self.get_shipments()
         relevant_shipments = []
@@ -159,10 +195,28 @@ def get_relevant_shipments(self):
 
             # Check if package has been delivered today
             if shipment['status']['delivery']:
-                delivery_date = datetime.strptime( shipment['status']['delivery']['deliveryDate'][:19], "%Y-%m-%dT%H:%M:%S" )
+                delivery_date = datetime.strptime(
+                    shipment['status']['delivery']['deliveryDate'][:19], "%Y-%m-%dT%H:%M:%S")
 
                 if delivery_date.date() == datetime.today().date():
                     relevant_shipments.append(shipment)
-                    continue
 
-        return relevant_shipments
+        return relevant_shipments
+
+    def get_relevant_letters(self):
+        """ Retrieve letters with a future delivery date """
+
+        letters = self.get_letters()
+        relevant_letters = []
+
+        for letter in letters:
+
+            # Check if letter is scheduled for delivery in the future
+            if letter['expectedDeliveryDate']:
+                expected_delivery_date = datetime.strptime(
+                    letter['expectedDeliveryDate'][:19], "%Y-%m-%dT%H:%M:%S")
+
+                if expected_delivery_date.date() == datetime.today().date():
+                    relevant_letters.append(letter)
+
+        return relevant_letters

setup.py

@@ -1,9 +1,9 @@
 from setuptools import setup, find_packages
 
 setup(name='postnl_api',
-      version='0.1',
+      version='0.2',
       description='Python wrapper for the PostNL API, a way to track packages using their online portal',
-      url='http://github.com/imicknl/python-postnl-api',
+      url='https://github.com/imicknl/python-postnl-api',
       author='Mick Vleeshouwer',
       author_email='mick@imick.nl',
       license='MIT',