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.

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

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

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).

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.

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.

Error Handling

Particular error details are listed in the documentation.

All SDK methods may throw an exception described below.

class PostmenException

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.

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.

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