Skip to content

Latest commit

 

History

History
393 lines (308 loc) · 27.5 KB

README.rst

File metadata and controls

393 lines (308 loc) · 27.5 KB
Raw

Introduction

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

Table of Contents

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:

Examples:

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:

Examples:

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