postmen 1.2

Python SDK of Postmen API

Introduction

Python SDK for Postmen API. For problems and suggestions please open GitHub issue

Table of Contents

• Installation

• Quick Start

• class Postmen

  • Postmen(api_key, region, **kwargs)

  • create(self, resource, payload, **kwargs)

  • get(self, resource, id_=None, **kwargs)

  • getError()

  • GET(self, path, **kwargs)

  • POST(self, path, **kwargs)

  • PUT(self, path, **kwargs)

  • DELETE(self, path, **kwargs)

• Error Handling

  • class PostmenException

  • Automatic retry on retryable error

• Examples

  • Full list

  • How to run

  • Navigation table

• Testing

• License

• Contributors

Installation

Manual

Download or clone this repo, then run

python setup.py install

PyPI

Run pip install postmen

Quick Start

In order to get API key and choose a region refer to the documentation.

import pprint

pp = pprint.PrettyPrinter(indent=4)

from postmen import Postmen, PostmenException

api_key = 'YOUR_API_KEY'
region = 'sandbox'

# create Postmen API handler object

api = Postmen(api_key, region)

try:
    # as an example we request all the labels

    result = api.get('labels')
    print("RESULT:")
    pp.pprint(result)
except PostmenException as e:
    # if error occurs we can access all
    # the details in following way

    print("ERROR")
    print(e.code())  # error code
    print(e.message())  # error message
    pp.pprint(e.details())  # details

class Postmen

Postmen(api_key, region, **kwargs)

Initiate Postmen SDK object. In order to get API key and choose a region refer to the documentation.

Argument	Required	Type	Default	Description
api_key	YES	String	N / A	API key
region	NO if endpoint is set	String	N / A	API region (sandbox, production)
endpoint	—	String	N / A	Custom URL API endpoint
retry	—	Boolean	True	Automatic retry on retryable errors
rate	—	Boolean	True	Wait before API call if rate limit exceeded or retry on 429 error
safe	—	Boolean	False	Suppress exceptions on errors, None would be returned instead, check Error Handling
raw	—	Boolean	False	To return API response as a raw string
proxy	—	Dictionary	{}	Proxy credentials, handled as in requests library
time	—	Boolean	False	Convert ISO time strings into datetime objects

create(self, resource, payload, **kwargs)

Creates API resource object, returns new object payload as Dictionary.

Argument	Required	Type	Default	Description
resource	YES	String	N / A	Postmen API resourse (‘rates’, ‘labels’, ‘manifests’)
payload	YES	Array or String	N / A	Payload according to API
**kwargs	NO	Named arguments	N / A	Override constructor config

API Docs:

• POST /rates

• POST /labels

• POST /manifests

• POST /cancel-labels

Examples:

• rates_create.py

• labels_create.py

• manifests_create.py

• cancel_labels_create.py

get(self, resource, id_=None, **kwargs)

Gets API $resource objects (list or a single objects).

Argument	Required	Type	Default	Description
resource	YES	String	N / A	Postmen API resourse (‘rates’, ‘labels’, ‘manifests’)
id	NO	String	None	Object ID, if not set ‘list all’ API method is used
query	NO	Dictionary or String	N / A	HTTP GET query (named argument)
**kwargs	NO	Named arguments	N / A	Override constructor config

API Docs:

• GET /rates

• GET /rates/:id

• GET /labels

• GET /labels/:id

• GET /manifests

• GET /manifests/:id

• GET /cancel-labels

• GET /cancel-labels/:id

Examples:

• rates_retrieve.py

• labels_retrieve.py

• manifests_retrieve.py

• cancel_labels_retrieve.py

getError()

Returns SDK error, PostmenException type if named argument safe = True was set.

Check Error Handling for details.

GET(self, path, **kwargs)

Performs HTTP GET request, returns an Dictionary object holding API response.

Argument	Required	Type	Default	Description
path	YES	String	N / A	URL path (e.g. ‘v3/labels’ for https://sandbox-api.postmen.com/v3/labels)
query	NO	Dictionary or String	N / A	HTTP GET query (named argument)
**kwargs	NO	Named arguments	array ()	query, and other values overriding constructor config

POST(self, path, **kwargs)

PUT(self, path, **kwargs)

DELETE(self, path, **kwargs)

Performs HTTP POST/PUT/DELETE request, returns a Dictionary object holding API response.

Argument	Required	Type	Default	Description
path	YES	String	N / A	URL path (e.g. ‘v3/labels’ for https://sandbox-api.postmen.com/v3/labels)
body	NO	Dictionary or String	N / A	HTTP POST/PUT/DELETE request body (named argument)
**kwargs	NO	Named arguments	N / A	Override constructor config

Error Handling

Particular error details are listed in the documentation.

All SDK methods may throw an exception described below.

class PostmenException

Method	Return type	Description
code()	Integer	Error code
retryable( )	Boolean	Indicates if error is retryable
message()	String	Error message (e.g. The request was invalid or cannot be otherwise ser ved)
details()	List	Error details (e.g. Destination country must be RUS or KAZ)

In case of safe = True SDK would not throw exceptions, getError() must be used instead.

Example: error.py

Automatic retry on retryable error

If API error is retryable, SDK will wait for delay and retry. Delay starts from 1 second. After each try, delay time is doubled. Maximum number of attempts is 5.

To disable this option set retry = False

Examples

Full list

All examples avalible listed in the table below.

File	Description
rates_create.py	rates object creation
rates_retrieve.py	rates object(s) retrieve
labels_create.py	labels object creation
labels_retrieve.py	labels object(s) retrieve
manifests_create.py	manifests object creation
manifests_retrieve.py	manifests object(s) retrieve
cancel_labels_create.py	cancel-labels object creation
cancel_labels_retrieve.py	cancel-labels object(s) retrieve
proxy.py	Proxy usage
error.py	Avalible ways to catch/get errors

How to run

Download the source code, go to examples directory.

If you already installed Postmen SDK for Python you can proceed, otherwise install it by running python setup.py install or using PyPI.

Put your API key and region to credentials.py

Check the file you want to run before run. Some require you to set additional variables.

Navigation table

For each API method SDK provides Python wrapper. Use the table below to find SDK method and example that match your need.

Model \ Action	create	get all	get by id
rates	.create(‘rates’, payload)	.get(‘rates’)	.get(‘rates’, id)
labels	.create(‘labels’, payload)	.get(‘labels’)	.get(‘labels’, id)
manifests	.create(‘manifests’, payload)	.get(‘manifests’)	.get(‘manifests’, id)
cancel-labels	.create(‘cancel-labels’, payload)	.get(‘cancel-labels’)	.get(‘cancel-labels’, id)

Testing

If you contribute to SDK, run automated test before you make pull request.

pip install -r requirements.txt
python setup.py test

License

Released under the MIT license. See the LICENSE file for details.

Contributors

• Fedor Korshunov - view contributions

• Marek Narozniak - view contributions