postmen 1.2

Description:

postmen 1.2

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