Skip to main content

Python SDK of Postmen API

Project description

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.

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

postmen-1.2.tar.gz (16.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page