trustpilot 7.0.0

trustpilot api client including cli tool

trustpilot

Python HTTP client for Trustpilot.

Features

• Extends the requests.Session class with automatic authentication for public and private endpoints
• GET, POST, PUT, DELETE, HEAD, OPTIONS and PATCH methods are exposed on module level
• Implements session factory and default singleton session
• Provides a simple hook system
• CLI tool with basic HTTP commands

Installation

Install the package from PyPI using pip:

pip install trustpilot

if you wanna install with async support (python>=3.6+) then install with

pip install trustpilot[async]

Getting Started

This client is using the Requests library. Responses are standard requests.Response objects. You can use it as a factory or as a singleton.

Use the singleton session

Use the built-in default session to instantiate a globally accessible session.

from trustpilot import client
client.default_session.setup(
    api_host="https://api.trustpilot.com",
    api_version="v1",
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    username="YOUR_TRUSTPILOT_BUSINESS_USERNAME",
    password="YOUR_TRUSTPILOT_BUSINESS_PASSWORD"
)
response = client.get("/foo/bar")

You can rely on environment variables for the setup of sessions so

$ env
TRUSTPILOT_API_HOST=foobar.com
TRUSTPILOT_API_VERSION=v1
TRUSTPILOT_API_KEY=foo
TRUSTPILOT_API_SECRET=bar
TRUSTPILOT_USERNAME=username
TRUSTPILOT_PASSWORD=password

Will work with the implicit default_session and the TrustpilotSession.setup method.

from trustpilot import client
client.get("/foo/bar")

Instantiate your own session

You can create as many sessions as you like, as long as you pass them around yourself.

from trustpilot import client
session = client.TrustpilotSession(
    api_host="https://api.trustpilot.com",
    api_version="v1",
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    username="YOUR_TRUSTPILOT_BUSINESS_USERNAME",
    password="YOUR_TRUSTPILOT_BUSINESS_PASSWORD"
)
response = session.get("/foo/bar")

Async client

Since version 3.0.0 you are able to use the async_client for asyncio usecases.

To use the default async_client session, using env-vars for settings, import is as following:

import asyncio
from trustpilot import async_client
loop = asyncio.get_event_loop()

async def get_response():
    response = await async_client.get('/foo/bar')
    response_json = await response.json()

loop.run_until_complete(get_response())

Or instantiate the session yourself with:

import asyncio
from trustpilot import async_client
loop = asyncio.get_event_loop()

session = async_client.TrustpilotAsyncSession(
    api_host="https://api.trustpilot.com",
    api_version="v1",
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    username="YOUR_TRUSTPILOT_BUSINESS_USERNAME",
    password="YOUR_TRUSTPILOT_BUSINESS_PASSWORD"
)

async def get_response():
    response = await session.get('/foo/bar')
    response_json = await response.json()

loop.run_until_complete(get_response())

Advanced async usage

The async client uses an asynccontextmanager under the hood to perform the supported request methods. A side effect of the implementation is that it buffers up all the content before returning it to the calling scope.

You can get around this limitation by using the asynccontextmanager directly like in the next example.

Example with stream reading the raw aiohttp response object:

import asyncio
from trustpilot import async_client
loop = asyncio.get_event_loop()

async def get_response():
    async with session.request_context_manager('get', "/v1/foo/bar") as resp:
        result = True
        while True:
            chunk = resp.content.read(8)
            if not chunk:
                break
            result += chunk
    return result

loop.run_until_complete(get_response())

Setup User Agent

A UserAgent header can be specified in two ways:

1. By populating the TRUSTPILOT_USER_AGENT environment var
2. By creating your own (async/sync)-client instance, or calling setup on the default_session, and supplying the kwargs user_agent=foobar

If no user-agent is given it will autopopulate using the function in get_user_agent function in auth.py

CLI

A command line tool trustpilot_api_client is bundled with the module. To invoke it, use:

Usage: trustpilot_api_client [OPTIONS] COMMAND [ARGS]...

Options:
  --host TEXT               host name
  --version TEST            api version
  --key TEXT                api key
  --secret TEXT             api secret
  --token_issuer_host TEXT  token issuer host name
  --username TEXT           Trustpilot username
  --password TEXT           Trustpilot password
  -c TEXT                   json config file name
  -v, --verbose             verbosity level
  --help                    Show this message and exit.

Commands:
  create_access_token  Get an access token
  delete               Send a DELETE request
  get                  Send a GET request
  post                 Send a POST request with specified data
  put                  Send a PUT request with specified data

In order to use the -c option please supply the filename of a JSON in the following format:

{
  "TRUSTPILOT_API_HOST": "foo",
  "TRUSTPILOT_API_VERSION": "v1",
  "TRUSTPILOT_API_KEY": "bar",
  "TRUSTPILOT_API_SECRET": "baz",
  "TRUSTPILOT_USERNAME": "username",
  "TRUSTPILOT_PASSWORD": "password"
}

Tests

You can use pytest to run tests against your current Python version.

See setup.py for test dependencies.

History

0.1.0 (2016-11-09)

• First release on gemfury

0.1.1 (2016-11-09)

• change names

0.1.2 (2016-11-09)

• fix issue with 401-retry

0.1.3 (2016-11-10)

• add dependencies to setup.py

0.1.4 (2016-11-11)

• cli tool

0.1.5 (2016-11-11)

• fix apikey url query param error

0.1.6 (2016-11-11)

• introduce different token_issuer_host thatn api_host

0.1.7 (2016-12-06)

• Introduce context_getter on session object, defaulted to holding CorrelationId=random_uuid

1.0.0 (2017-02-01)

• first release as oss, major refactoring of inner machinery (session objects, retry policies, cli, tests etc)

1.1.0 (2017-06-12)

• fixed logging so it does not use root logger. according to best practices mentioned in http://pythonsweetness.tumblr.com/post/67394619015/use-of-logging-package-from-within-a-library
• removed dependency on httpretty since it is not supporting py3

2.0.0 (2017-09-29)

• DEPRECATED: create_session is getting deprecated, use trustpilot.client.default_session.setup instead
• now able to query public endpoints without being authenticated

2.1.0 (2017-10-05)

• fixed issue in cli.post & cli.put where 'content_type' should be 'content-type'

3.0.0 (2018-01-18)

DELETED DO NOT USE!!

• add async-client

3.0.1 (2018-01-18)

• removed prints
• made async_client retry on unauthorized

4.0.0 (2018-06-06)

• drop support for Python 3.3

4.0.1 (2018-06-06)

• Switch to non-deprecated session object for utility method calls

4.0.2 (2018-10-30)

• Upgrade requests to 2.20.0

5.0.0 (2019-01-04)

• Update to authentication methods

5.0.1 (2019-02-04)

• Fix documentation formatting

6.0.0 (2019-02-06)

• reorganize code
• add user-agent header
• get access_token with async call in async_client

6.0.3 (2019-08-15)

• Added support for 'API Version' parameter for Client initialisation.

6.0.4 (2019-08-15)

• Remove auto-deploy to travis

6.0.5 (2019-08-15)

• allow newer version of requests dependency

6.0.6 (2019-09-18)

• specify user agent through env-var or kwarg

6.0.8 (2019-09-19)

• pass user_agent property down to session correctly
• handle duplicate api version properly

6.0.9 (2019-09-19)

• fix: transmit user-agent on all requests

6.0.10 (2019-09-20)

• fix: handle duplicate api version for both sync and async clients

6.1.0 (2020-01-06)

• dependencies: github security upgrade of requests and urllib

7.0.0 (2020-01-13)

breaking changes:

• python 2.7 support now gone since it reached end of-life
• now only supporting async_client for 3.6+
• now depending on async_generator for asynccontextmanager support in 3.6+

new features:

• advanced mode using the request_context_manager directly