Metadata-Version: 1.1
Name: postmen
Version: 1.2
Summary: Python SDK of Postmen API
Home-page: https://github.com/postmen/sdk-python
Author: Postmen
Author-email: support@postmen.com
License: MIT
Download-URL: https://github.com/postmen/sdk-python/tarball/1.2
Description-Content-Type: UNKNOWN
Description: Introduction
        ------------
        
        Python SDK for `Postmen API <https://docs.postmen.com/>`__. For problems
        and suggestions please open `GitHub
        issue <https://github.com/postmen/postmen-sdk-python/issues>`__
        
        **Table of Contents**
        
        -  `Installation <#installation>`__
        -  `Quick Start <#quick-start>`__
        -  `class Postmen <#class-postmen>`__
        
           -  `Postmen(api_key, region, **kwargs) <#postmenapi_key-region-kwargs>`__
           -  `create(self, resource, payload, **kwargs) <#createself-resource-payload-kwargs>`__
           -  `get(self, resource, id_=None, **kwargs) <#getself-resource-id_none-kwargs>`__
           -  `getError() <#geterror>`__
           -  `GET(self, path, **kwargs) <#getself-path-kwargs>`__
           -  `POST(self, path, **kwargs) <#postself-path-kwargs>`__
           -  `PUT(self, path, **kwargs) <#putself-path-kwargs>`__
           -  `DELETE(self, path, **kwargs) <#deleteself-path-kwargs>`__
        
        -  `Error Handling <#error-handling>`__
        
           -  `class PostmenException <#class-postmenexception>`__
           -  `Automatic retry on retryable
              error <#automatic-retry-on-retryable-error>`__
        
        -  `Examples <#examples>`__
        
           -  `Full list <#full-list>`__
           -  `How to run <#how-to-run>`__
           -  `Navigation table <#navigation-table>`__
        
        -  `Testing <#testing>`__
        -  `License <#license>`__
        -  `Contributors <#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 <https://docs.postmen.com/>`__.
        
        .. code:: python
        
            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 <https://docs.postmen.com/>`__.
        
        +------------------+---------------------+------------+----------+---------------------------------------------------------------------------------+
        | Argument         | Required            | Type       | Default  | Description                                                                     |
        +==================+=====================+============+==========+=================================================================================+
        | ``api_key``      | YES                 | String     | N / A    | API key                                                                         |
        +------------------+---------------------+------------+----------+---------------------------------------------------------------------------------+
        | ``region``       | NO if ``endpoint``  | String     | N / A    | API region (``sandbox``,                                                        |
        |                  | is set              |            |          | ``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 <#error-handling>`__                                            |
        +------------------+---------------------+------------+----------+---------------------------------------------------------------------------------+
        | ``raw``          | —                   | Boolean    | ``False``| To return API response as a raw string                                          |
        +------------------+---------------------+------------+----------+---------------------------------------------------------------------------------+
        | ``proxy``        | —                   | Dictionary | ``{}``   | Proxy credentials,                                                              |
        |                  |                     |            |          | handled as in `requests                                                         |
        |                  |                     |            |          | library <http://docs.python-requests.org/en/latest/user/advanced/#proxies>`__   |
        |                  |                     |            |          |                                                                                 |
        |                  |                     |            |          |                                                                                 |
        |                  |                     |            |          |                                                                                 |
        +------------------+---------------------+------------+----------+---------------------------------------------------------------------------------+
        | ``time``         | —                   | Boolean    | ``False``| Convert ISO time strings                                                        |
        |                  |                     |            |          | into                                                                            |
        |                  |                     |            |          | `datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__ |
        |                  |                     |            |          | 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    | N / A   | Payload according to API                          |
        |              |         | String      |         |                                                   |
        +--------------+---------+-------------+---------+---------------------------------------------------+
        | ``**kwargs`` | NO      | Named       | N / A   | Override constructor                              |
        |              |         | arguments   |         | `config <#postmenapi_key-region-kwargs>`__        |
        +--------------+---------+-------------+---------+---------------------------------------------------+
        
        **API Docs:**
        
        - `POST /rates <https://docs.postmen.com/#rates-calculate-rates>`__
        - `POST /labels <https://docs.postmen.com/#labels-create-a-label>`__
        - `POST /manifests <https://docs.postmen.com/#manifests-create-a-manifest>`__
        - `POST /cancel-labels <https://docs.postmen.com/#cancel-labels-cancel-a-label>`__
        
        **Examples:**
        
        - `rates\_create.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/rates_create.py>`__
        - `labels\_create.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_create.py>`__
        - `manifests\_create.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/manifests_create.py>`__
        - `cancel\_labels\_create.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/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  | N / A   | HTTP GET query (named argument)                   |
        |              |         | String         |         |                                                   |
        +--------------+---------+----------------+---------+---------------------------------------------------+
        | ``**kwargs`` | NO      | Named          | N / A   | Override constructor                              |
        |              |         | arguments      |         | `config <#postmenapi_key-region-kwargs>`__        |
        +--------------+---------+----------------+---------+---------------------------------------------------+
        
        **API Docs:**
        
        - `GET /rates <https://docs.postmen.com/#rates-list-all-rates>`__
        - `GET /rates/:id <https://docs.postmen.com/#rates-retrieve-rates>`__
        - `GET /labels <https://docs.postmen.com/#labels-list-all-labels>`__
        - `GET /labels/:id <https://docs.postmen.com/#labels-retrieve-a-label>`__
        - `GET /manifests <https://docs.postmen.com/#manifests-list-all-manifests>`__
        - `GET /manifests/:id <https://docs.postmen.com/#manifests-retrieve-a-manifest>`__
        - `GET /cancel-labels <https://docs.postmen.com/#cancel-labels-list-all-cancel-labels>`__
        - `GET /cancel-labels/:id <https://docs.postmen.com/#cancel-labels-retrieve-a-cancel-label>`__
        
        **Examples:**
        
        - `rates\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/rates_retrieve.py>`__
        - `labels\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_retrieve.py>`__
        - `manifests\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/manifests_retrieve.py>`__
        - `cancel\_labels\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/cancel_labels_retrieve.py>`__
        
        getError()
        ^^^^^^^^^^
        
        Returns SDK error, `PostmenException type <#class-postmenexception>`__
        if named argument ``safe = True`` was set.
        
        Check `Error Handling <#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  | N / A   | HTTP GET query (named argument)                   |
        |              |         | String         |         |                                                   |
        +--------------+---------+----------------+---------+---------------------------------------------------+
        | ``**kwargs`` | NO      | Named          | ``array | ``query``, and other values                       |
        |              |         | arguments      | ()``    | overriding constructor                            |
        |              |         |                |         | `config <#postmenapi_key-region-kwargs>`__        |
        +--------------+---------+----------------+---------+---------------------------------------------------+
        
        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  | N / A   | HTTP POST/PUT/DELETE request body                 |
        |              |         | String         |         | (named argument)                                  |
        +--------------+---------+----------------+---------+---------------------------------------------------+
        | ``**kwargs`` | NO      | Named          | N / A   | Override constructor                              |
        |              |         | arguments      |         | `config <#postmenapi_key-region-kwargs>`__        |
        |              |         |                |         |                                                   |
        +--------------+---------+----------------+---------+---------------------------------------------------+
        
        Error Handling
        --------------
        
        Particular error details are listed in the
        `documentation <https://docs.postmen.com/errors.html>`__.
        
        All SDK methods may throw an exception described below.
        
        class PostmenException
        ^^^^^^^^^^^^^^^^^^^^^^
        
        +------------+-----------+------------------------------------------------------+
        | Method     | Return    | Description                                          |
        |            | type      |                                                      |
        +============+===========+======================================================+
        | 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() <#geterror>`__ must be used instead.
        
        Example:
        `error.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/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 <https://github.com/postmen/postmen-sdk-python/blob/master/examples/rates_create.py>`__                        | ``rates`` object creation              |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `rates\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/rates_retrieve.py>`__                    | ``rates`` object(s) retrieve           |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `labels\_create.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_create.py>`__                      | ``labels`` object creation             |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `labels\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_retrieve.py>`__                  | ``labels`` object(s) retrieve          |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `manifests\_create.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/manifests_create.py>`__                | ``manifests`` object creation          |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `manifests\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/manifests_retrieve.py>`__            | ``manifests`` object(s) retrieve       |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `cancel\_labels\_create.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/cancel_labels_create.py>`__       | ``cancel-labels`` object creation      |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `cancel\_labels\_retrieve.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/cancel_labels_retrieve.py>`__   | ``cancel-labels`` object(s) retrieve   |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `proxy.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/proxy.py>`__                                       | Proxy usage                            |
        +----------------------------------------------------------------------------------------------------------------------------------+----------------------------------------+
        | `error.py <https://github.com/postmen/postmen-sdk-python/blob/master/examples/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 <https://github.com/postmen/postmen-sdk-python/blob/master/examples/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) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/rates_create.py>`__                | `.get('rates') <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_retrieve.py>`__                | `.get('rates', id) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/rates_retrieve.py>`__                 |
        +-----------------+-----------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
        | labels          | `.create('labels', payload) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_create.py>`__              | `.get('labels') <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_retrieve.py>`__               | `.get('labels', id) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/labels_retrieve.py>`__               |
        +-----------------+-----------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
        | manifests       | `.create('manifests', payload) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/manifests_create.py>`__        | `.get('manifests') <https://github.com/postmen/postmen-sdk-python/blob/master/examples/manifests_retrieve.py>`__         | `.get('manifests', id) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/manifests_retrieve.py>`__         |
        +-----------------+-----------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
        | cancel-labels   | `.create('cancel-labels', payload) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/cancel_labels_create.py>`__| `.get('cancel-labels') <https://github.com/postmen/postmen-sdk-python/blob/master/examples/cancel_labels_retrieve.py>`__ | `.get('cancel-labels', id) <https://github.com/postmen/postmen-sdk-python/blob/master/examples/cancel_labels_retrieve.py>`__ |
        +-----------------+-----------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
        
        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 <https://github.com/postmen/sdk-python/commits?author=fedor>`__
        -  Marek Narozniak - `view
           contributions <https://github.com/postmen/sdk-python/commits?author=marekyggdrasil>`__
        
Keywords: postmen api binding post mail airmail logistics shipping label rate rates
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
