Mopinion Client

The intention of developing a MopinionClient is to make it easy, beautiful and elegant when interacting with our API.

Credentials can be created via the Mopinion Suite at Integrations » Feedback API in the classic interface or in the Raspberry interface, provided your package includes API access.

Take a look at this link with the steps to get a private_key and a public_key.

MopinionClient Specifications

class mopinion.MopinionClient(public_key: str, private_key: str, max_retries: int = 3, backoff_factor: int = 1, version: Optional[str] = None, verbosity: str = 'normal', content_negotiation: str = 'application/json')

Client to interact with Mopinion API.

Provides functionality for authentication, authorization, and requesting resources. Steps during instantiation:

  1. Credential validations.

  2. Instantiation of a session object from requests.Session that will be used in each request.

  3. Retrieval of signature_token from the API for a specific private_key and public_key.

When instantiating, a signature token is retrieved from the API and stored in the signature_token attribute using your private_key and public_key. The signature_token will be used in each request.

In each request, an HMAC signature will be created using SHA256-hashing, and encrypted with your signature_token. This HMAC signature is encoded together with the public_key. After this encryption, the token is set into the headers under the X-Auth-Token key.

Parameters:
  • public_key (str) –

  • private_key (str) –

  • verbosity (str) – Defaults to normal.

  • version (str) – If no version provided, default to latest.

  • content_negotiation (str) – Defaults to application/json.

  • max_retries (int) – Defaults to 3.

  • backoff_factor (int) – Defaults to 1.

build_token(endpoint: EndPoint) bytes

Get token

get_account(**kwargs)

Get your account.

Parameters:

kwargs

  • version (str): API Version. Optional. Defaults to the latest.

  • verbosity (str): normal, quiet or full. Defaults to normal.

  • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

  • query_params (dict): Optional. See documentation.

  • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

get_datasets(dataset_id: int, **kwargs)

Get datasets.

Parameters:
  • dataset_id (int) –

  • kwargs

    • version (str): API Version. Optional. Defaults to the latest.

    • verbosity (str): normal, quiet or full. Defaults to normal.

    • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

    • query_params (dict): Optional. See documentation.

    • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

get_datasets_feedback(dataset_id: int, **kwargs)

Get dataset feedback.

Parameters:
  • dataset_id (int) –

  • kwargs

    • version (str): API Version. Optional. Defaults to the latest.

    • verbosity (str): normal, quiet or full. Defaults to normal.

    • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

    • query_params (dict): Optional. See documentation.

    • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

get_datasets_fields(dataset_id: int, **kwargs)

Get dataset fields.

Parameters:
  • dataset_id (int) –

  • kwargs

    • version (str): API Version. Optional. Defaults to the latest.

    • verbosity (str): normal, quiet or full. Defaults to normal.

    • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

    • query_params (dict): Optional. See documentation.

    • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

get_deployments(deployment_id: Optional[str] = None, **kwargs)

Get deployments.

Parameters:
  • deployment_id (str) –

  • kwargs

    • version (str): API Version. Optional. Defaults to the latest.

    • verbosity (str): normal, quiet or full. Defaults to normal.

    • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

    • query_params (dict): Optional. See documentation.

    • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

get_reports(report_id: int, **kwargs)

Get reports.

Parameters:
  • report_id (int) – Optional.

  • kwargs

    • version (str): API Version. Optional. Defaults to the latest.

    • verbosity (str): normal, quiet or full. Defaults to normal.

    • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

    • query_params (dict): Optional. See documentation.

    • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

get_reports_feedback(report_id: int, **kwargs)

Get reports feedback.

Parameters:
  • report_id (int) –

  • kwargs

    • version (str): API Version. Optional. Defaults to the latest.

    • verbosity (str): normal, quiet or full. Defaults to normal.

    • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

    • query_params (dict): Optional. See documentation.

    • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

get_reports_fields(report_id: int, **kwargs)

Get reports fields.

Parameters:
  • report_id (int) –

  • kwargs

    • version (str): API Version. Optional. Defaults to the latest.

    • verbosity (str): normal, quiet or full. Defaults to normal.

    • content_negotiation (str): application/json or application/x-yaml. Defaults to application/json.

    • query_params (dict): Optional. See documentation.

    • iterator (bool): If sets to True an iterator will be returned.

Returns:

response (requests.models.Response).

is_available(verbose: bool = False) Union[dict, bool]

Test the API’s availability.

It returns a boolean True/False in case the API is available or not. In case we need extra information about the state of the API, we can provide a flag verbose=True.

Examples

>>> from mopinion import MopinionClient
>>> client = MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY)
>>> assert client.is_available()
>>> r = client.is_available(verbose=True)
>>> assert r["code"] == 200 and r["response"] == "pong" and r["version"] == "2.0.0"
request(endpoint: str, query_params: Optional[dict] = None, version: Optional[str] = None, verbosity: str = 'normal', content_negotiation: str = 'application/json') Response

Generic method to send requests to our API.

Wrapper on top of requests.Session.request method adding token encryption on headers. Every time we call request five steps are applied:

  1. Validation of arguments.

  2. Token creation - token depends on the endpoint argument and signature_token.

  3. Preparation of parameter dictionary. Add token to headers.

  4. Make a request.

  5. Return a response.

Parameters:
  • endpoint (str) – API endpoint.

  • version (str) – API Version. Optional. Defaults to the latest.

  • verbosity (str) – normal, quiet or full. Defaults to normal.

  • content_negotiation (str) – application/json or application/x-yaml. Defaults to application/json.

  • body (dict) – Optional.

  • query_params (dict) – Optional.

Returns:

response (requests.models.Response).

Examples

>>> from mopinion import MopinionClient
>>> client = MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY)
>>> response = client.request("/account")
>>> assert response.json()["_meta"]["code"] == 200
>>> response = client.request(endpoint="/deployments")
>>> assert response.json()["_meta"]["code"] == 200
>>>
>>> with MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY) as client:
...     response = client.request("/account")
...     assert response.json()["_meta"]["code"] == 200
...     response = client.request(endpoint="/deployments")
...     assert response.json()["_meta"]["code"] == 200
>>>
>>> mopinion_client = MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY)
>>> with mopinion_client as client:
...     response = client.request("/account")
...     assert response.json()["_meta"]["code"] == 200
...     response = client.request(endpoint="/deployments")
...     assert response.json()["_meta"]["code"] == 200
resource(resource_name: str, resource_id: Optional[Union[str, int]] = None, sub_resource_name: Optional[str] = None, query_params: Optional[dict] = None, version: Optional[str] = None, verbosity: str = 'normal', content_negotiation: str = 'application/json', iterator: bool = False) Union[Response, Iterator]

Method to send requests to our API.

Abstraction of mopinion_api.MopinionClient.request. Interacts with the API in term of resources and subresources, and also, enables iterator protocol when requesting large resources.

Parameters:
  • resource_name (str) –

  • resource_id (str/int) – Optional.

  • sub_resource_name (str) – Optional.

  • version (str) – API Version. Optional. Defaults to the latest.

  • verbosity (str) – normal, quiet or full. Defaults to normal.

  • content_negotiation (str) – application/json or application/x-yaml. Defaults to application/json.

  • body (dict) – Optional.

  • query_params (dict) – Optional.

  • iterator (bool) – If sets to True an iterator will be returned.

Returns:

response (requests.models.Response) or iterator (collections.abc.Iterator)

The endpoint is built from mopinion_api.dataclasses.ResourceUri and the parameters are:
  • resource_name (str) Required

  • resource_id (int/str) Optional

  • subresource_name (str) Optional

Resources and sub-resources options:
  • The resource_name options are: “account”, “deployments”, “datasets”, “reports”.

  • The subresource_name options are: “fields”, “feedback”.

You can also use the constants defined in the mopinion_api.MopinionClient class.
  • The resource_name options are: RESOURCE_ACCOUNT, RESOURCE_DEPLOYMENTS, RESOURCE_DATASETS, RESOURCE_REPORTS.

  • The subresource_name options are: SUBRESOURCE_FIELDS, SUBRESOURCE_FEEDBACK.

Examples

>>> from mopinion import MopinionClient
>>> client = MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY)
>>> response = client.resource("account")
>>> assert response.json()["_meta"]["code"] == 200
>>> response = client.resource(resource_name=client.RESOURCE_ACCOUNT)  # same as above
>>> assert response.json()["_meta"]["code"] == 200
>>>
>>> with MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY) as client:
...     response = client.resource("account")
...     assert response.json()["_meta"]["code"] == 200
...     response = client.resource(resource_name=client.RESOURCE_ACCOUNT)
...     assert response.json()["_meta"]["code"] == 200

When working with the API there is a limit of elements retrieved. The limit parameters default to 10. You can increase the limit, or you can request resources using the flag generator=True. This returns a Generator which traverses these pages for you and yields each result on the current page before retrieving the next page.

Examples

>>> from mopinion import MopinionClient
>>> client = MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY)
>>> iterator = client.resource("account", iterator=True)
>>> response = next(iterator)
>>> assert response.json()["_meta"]["code"] == 200

Below some more examples.

Examples

>>> from mopinion import MopinionClient
>>> client = MopinionClient(public_key=PUBLICKEY, private_key=PRIVATEKEY)
>>> response = client.resource("account")
>>> assert response.json()["_meta"]["code"] == 200
>>> response = client.resource("deployments")
>>> assert response.json()["_meta"]["code"] == 200