merge in develop

README.rst

@@ -18,6 +18,17 @@ Royal Mail Rest API
 
 A small helper for integrating python with Royal Mails Rest API
 
+This is to help with getting started integrating Royal Mails shipping and Tracking API's into your project.
+
+They do have an Open API to build this with Swagger-Codegen, but I found there were a few issues with this.
+1. Horrible final code - overly verbose and complicated.
+1. Half the time it would not build (needed beta versions of swagger-codegen) and then it would still not work.
+
+This is cleaner, easier to modify and extend, and a lot lighter weight, only using the standard library.
+
+It is VERY MUCH a work in progress, so help is hugely appreciated, and be careful, it may change as I implement more features / improve and enhance what we already have.
+
+
 
 * Free software: MIT license
 * Documentation: https://royal-mail-rest-api.readthedocs.io.

docs/usage.rst

@@ -2,6 +2,95 @@
 Usage
 =====
 
-To use Royal Mail Rest API in a project::
+To use Royal Mail Rest API in a project:
+
+.. note::
+    (this is from the example.py file which will be updated, its worth looking there)
+
+.. code-block:: python
+    import json
+    from royal_mail_rest_api.tools import RoyalMailBody
+    from royal_mail_rest_api.shipping import ShippingApi
+    from royal_mail_rest_api.tracking import TrackingApi
+    from royal_mail_rest_api.get_credentials import return_credentials
+
+    if __name__ == '__main__':
+        # Get our API credentials (from credentials.ini)
+        creds = return_credentials()
+
+        # make some nice easy to read variables for authenticating with
+        CLIENT_ID = creds['royal_mail']['CLIENT_ID']
+        CLIENT_SECRET = creds['royal_mail']['CLIENT_SECRET']
+        USERNAME = creds['royal_mail']['USERNAME']
+        PASSWORD_HASHED = creds['royal_mail']['PASSWORD_HASHED']
+
+        # Create a new delivery object to make our address etc with
+        body = RoyalMailBody('Delivery')
+
+        # Add our items to it
+        body.add_ship_date(None)
+        body.add_service('P', 1, 'TPN', 'T', True,  ['14'])
+        body.customer_reference = 'D123456'
+        body.department_reference = 'Q123456'
+        body.sender_reference = 'A123456'
+        body.add_items(1, 100, 'g')
+        body.add_receipient_contact('Joe Bloggs', 'joe.bloggs@royalmail.com', None, '07970810000')
+        body.add_receipient_address('Broadgate Circle', 'London', None, 'EC1A 1BB', country='GB', building_number='1',
+                                    address_line2='Add line 2', address_line3='Add line 3', building_name='My building')
+
+        # Request our body to use to request a label from royal mail
+        my_rm_body = body.return_domestic_body()
+
+
+        # Create a shipping object, populate it with our credentials
+        my_shipping = ShippingApi(CLIENT_ID, CLIENT_SECRET, USERNAME, PASSWORD_HASHED)
+        # Request an authentication token
+        my_shipping.get_token()
+        # Post a shipping request
+        post_shipping = my_shipping.post_domestic(my_rm_body)
+
+        # Store our tracking id for use.
+        tracking_ref = post_shipping['completedShipments'][0]['shipmentItems'][0]['shipmentNumber']
+
+        # Get a label ! this is base64 encoded
+        label = my_shipping.put_shipment_label(tracking_ref)
+
+        # Now lets change some info about the receipient
+        body.add_receipient_contact('Alex Hellier', 'alex@me.com', 'Alex S Hellier', '123455')
+        # And get our update body - this is slightly different from the original request
+        new_data = body.return_domestic_update_boy()
+        # Request a change
+        change_name = my_shipping.put_shipment(tracking_ref, new_data)
+        # Request a new label
+        new_label = my_shipping.put_shipment_label(tracking_ref)
+
+        # Lets delete the post request
+        delete_shipping = my_shipping.delete_shipment(tracking_ref)
+
+        # If we have some labels to manifest - request it
+        manifest_info = {'yourReference': '123'}
+        manifest_data = my_shipping.post_manifest(manifest_info)
+        # Get the manifest doumentation - note, you will need the maniefest number to get this
+        manifest_label = my_shipping.put_manifest(manifest_batch_number=5)
+
+
+        # Now, a period of time has passed, we can track those packages
+        tracking_api = TrackingApi(CLIENT_ID, CLIENT_SECRET)
+        try:
+            test_tracking = tracking_api.summary(tracking_ref)
+            print(test_tracking)
+        except Exception as e:
+            print(e)
+
+        try:
+            test_pod = tracking_api.proof_of_delivery(tracking_ref)
+            print(test_pod)
+        except Exception as e:
+            print(e)
+
+        try:
+            history_tracking = tracking_api.history(tracking_ref)
+            print(history_tracking)
+        except Exception as e:
+            print(e)
 
-    import royal_mail_rest_api

royal_mail_rest_api/example.py

@@ -1,13 +1,23 @@
 import json
 from royal_mail_rest_api.tools import RoyalMailBody
 from royal_mail_rest_api.shipping import ShippingApi
+from royal_mail_rest_api.tracking import TrackingApi
 from royal_mail_rest_api.get_credentials import return_credentials
 
 if __name__ == '__main__':
-
+    # Get our API credentials (from credentials.ini)
     creds = return_credentials()
 
+    # make some nice easy to read variables for authenticating with
+    CLIENT_ID = creds['royal_mail']['CLIENT_ID']
+    CLIENT_SECRET = creds['royal_mail']['CLIENT_SECRET']
+    USERNAME = creds['royal_mail']['USERNAME']
+    PASSWORD_HASHED = creds['royal_mail']['PASSWORD_HASHED']
+
+    # Create a new delivery object to make our address etc with
     body = RoyalMailBody('Delivery')
+
+    # Add our items to it
     body.add_ship_date(None)
     body.add_service('P', 1, 'TPN', 'T', True,  ['14'])
     body.customer_reference = 'D123456'
@@ -18,42 +28,58 @@
     body.add_receipient_address('Broadgate Circle', 'London', None, 'EC1A 1BB', country='GB', building_number='1',
                                 address_line2='Add line 2', address_line3='Add line 3', building_name='My building')
 
+    # Request our body to use to request a label from royal mail
     my_rm_body = body.return_domestic_body()
 
 
-    print(json.dumps(my_rm_body))
-
-    print(my_rm_body)
-
-
-    CLIENT_ID = creds['royal_mail']['CLIENT_ID']
-    CLIENT_SECRET = creds['royal_mail']['CLIENT_SECRET']
-    USERNAME = creds['royal_mail']['USERNAME']
-    PASSWORD_HASHED = creds['royal_mail']['PASSWORD_HASHED']
+    # Create a shipping object, populate it with our credentials
     my_shipping = ShippingApi(CLIENT_ID, CLIENT_SECRET, USERNAME, PASSWORD_HASHED)
+    # Request an authentication token
     my_shipping.get_token()
-
+    # Post a shipping request
     post_shipping = my_shipping.post_domestic(my_rm_body)
+
+    # Store our tracking id for use.
     tracking_ref = post_shipping['completedShipments'][0]['shipmentItems'][0]['shipmentNumber']
-    label = my_shipping.put_shipment_label(tracking_ref)
 
-    # new_data = {
-    #     'recipientContact': {
-    #         'name': 'Alex Hellier'
-    #     }
-    # }
+    # Get a label ! this is base64 encoded
+    label = my_shipping.put_shipment_label(tracking_ref)
 
+    # Now lets change some info about the receipient
     body.add_receipient_contact('Alex Hellier', 'alex@me.com', 'Alex S Hellier', '123455')
+    # And get our update body - this is slightly different from the original request
     new_data = body.return_domestic_update_boy()
+    # Request a change
     change_name = my_shipping.put_shipment(tracking_ref, new_data)
+    # Request a new label
     new_label = my_shipping.put_shipment_label(tracking_ref)
 
-    # print(tracking_ref)
-    # delete_shipping = my_shipping.delete_shipment(tracking_ref)
+    # Lets delete the post request
+    delete_shipping = my_shipping.delete_shipment(tracking_ref)
+
+    # If we have some labels to manifest - request it
+    manifest_info = {'yourReference': '123'}
+    manifest_data = my_shipping.post_manifest(manifest_info)
+    # Get the manifest doumentation - note, you will need the maniefest number to get this
+    manifest_label = my_shipping.put_manifest(manifest_batch_number=5)
+
+
+    # Now, a period of time has passed, we can track those packages
+    tracking_api = TrackingApi(CLIENT_ID, CLIENT_SECRET)
+    try:
+        test_tracking = tracking_api.summary(tracking_ref)
+        print(test_tracking)
+    except Exception as e:
+        print(e)
+
+    try:
+        test_pod = tracking_api.proof_of_delivery(tracking_ref)
+        print(test_pod)
+    except Exception as e:
+        print(e)
 
-    # print(delete_shipping)
-    # manifest_info = {'yourReference': '123'}
-    # manifest_data = my_shipping.post_manifest(manifest_info)
-    # print(manifest_data)
-    # manifest_label = my_shipping.put_manifest(manifest_batch_number=5)
-    # print(manifest_label)
+    try:
+        history_tracking = tracking_api.history(tracking_ref)
+        print(history_tracking)
+    except Exception as e:
+        print(e)

royal_mail_rest_api/tracking.py

@@ -63,26 +63,4 @@ def history(self, tracking_number):
         return result.json()
 
 
-if __name__ == '__main__':
-    CLIENT_ID = ''
-    CLIENT_SECRET = ''
-    TRACKING_NUMBER = ''
-    tracking_api = TrackingApi(CLIENT_ID, CLIENT_SECRET)
 
-    try:
-        test_tracking = tracking_api.summary(TRACKING_NUMBER)
-        print(test_tracking)
-    except Exception as e:
-        print(e)
-
-    try:
-        test_pod = tracking_api.proof_of_delivery(TRACKING_NUMBER)
-        print(test_pod)
-    except Exception as e:
-        print(e)
-
-    try:
-        history_tracking = tracking_api.history(TRACKING_NUMBER)
-        print(history_tracking)
-    except Exception as e:
-        print(e)