opisense-client 1.0.2

Package to interact with the Opisense API

opisense_client

Python package providing some functions to interact with the Opisense API.
More info about Opisense here: https://www.opinum.com/
Opisense API is described here: https://docs.opinum.com/restapi/index.html

Getting started

These instructions will guide you through the process of getting you ready to use the opisense_client package

Prerequisites

1. Get an Opisense account.

Contact [e-mail] or see www.opinum.com to get an account

2. Get Opisense API credentials.

Contact [e-mail] to get an API secret and API key

3. Install opisense_client package

You can install opisense_client by typing pip install opisense-client in your terminal.

Configuration

Credentials file

Although you can define a dictonary containing your credentials in you script, it is more secure to store them in a separate file.
The file should be a .JSON format and the expected format is the following :

{  
  "user": {
    "username": "xxxxxxx",
    "password": "xxxxxxx"
  },
  "api": {
    "client_secret": "xxxxxx",
    "client_id": "xxxxxx",
    "scope":"opisense-api push-data"
  }
}

The xxxxxx should be replaced by your own credentials (see Prerequisites 1. and 2.)

The following code will read the file and store data in a Python dictionary :

import json
with open('path/to/your/file/credentials.JSON', encoding='utf-8') as file:  
    credentials = json.load(file)  
user_credentials = credentials['user']  
api_credentials = credentials['api']  

path/to/your/file/ is the local path to your credentials file and credentials.JSON is the filename.

Functionalities

objects

• ApiFilter:
  This object contains the API path and a dictionary containing all the filters names and values used to querry Opisense database via an http call to the API. This call is described under http section.
  See Opisense API documentation for details on the path and filters availables for each type of Opisense Entities.
  The __add__ method of this class allows adding filters names and values to the existing ApiFilter object.

• DataPoints: This object contains pairs of datapoints datetimes and values to be used in the StandardData object construction.
  The __add__ method of this class allows adding datapoints datetimes and values to the existing ApiFilter object.

• StandardData: This object contains a DataPoints object and the relevant parameters to identify strictly one Opisense Variable that will store the datapoints. A combinaison of these optionals parameters can be used to identify the variable : sourceId, sourceSerialNumber, meterNumber, sourceEan, mappingConfig. An other option is to use the internal id of the Opisense variable: variableId.
  The POST method of this class takes a bearer token as argument and uploads the StandardData object to Opisense API, using the http POST method.

• OpisenseObject: This object is a generic Opisense Object taking a type string and a dictionary containing all the Opisense parameters related to this kind of object. See Opisense API documentation for more details on Opisense Objects.
  The POST, PUT and DELETE methods of this class takes a bearer token as argument and uploads the StandardData object to Opisense API, using the appropriate http method.
  The json method of this function returns the object contain, serialized in JSON, using the built-in json method.

http

• authorize:
  This function takes user credentials and api credentials dictionnaries as input and returns the OAuth2 bearer token required to interract with Opisense API.
  The optional feedback argument returns in the console the Opisense account name and ID for which you got a token.

• GET:
  This function takes a bearer token and an ApiFilter object as inputs, perform an http call using GET method to Opisense API to get every element matching the filter and returns the response from the server.
  The optionnal json_output argument changes the output to the json content of the server response.
  The optional feedback argument returns the server response code in the console.

• POST:
  This function takes a bearer token and an OpisenseObject as inputs, creates the elements in Opisense database using the API POST method and returns the response from the server.
  The parent_id argument is necessary to create some type of OpisenseObjects. See Opisense API documentation for details.
  The optional feedback argument returns the server response code in the console.
  The optional force_path argument allows to change the default path appended to the url in the POST call.

• PUT:
  This function takes a bearer token and an OpisenseObject as inputs, updates the elements in Opisense database using the API PUT method and returns the response from the server.
  The parent_id argument is necessary to update some type of OpisenseObjects. See Opisense API documentation for details.
  The optional feedback argument returns the server response code in the console. The optional force_path argument allows to change the default path appended to the url in the POST call.

• DELETE:
  This function takes a bearer token and an OpisenseObject as inputs, deletes the elements in Opisense database using the API DELETE method and returns the response from the server.
  The optional feedback argument returns the server response code in the console.
  The optional force_path argument allows to change the default path appended to the url in the POST call.

Objects and Methods description

Every object and method is described with docstrings. You can easily access it by running help(method)

Changelog

1.0.1 :

Fix auth bug linked to oauth lib library update

set auth = None in oauth.fetch_token() in http.py to avoid getting an 'invalid_client' error

1.0.0 :

First stable version

StandardData

Added variableId as unique identifier option

Documentation

Updated README.MD and documented every object and method

0.3 :

force_path

Added force_path optional parameter to http.POST and http.PUT. Overwrites the default OpisenseObject.api_path in the http call.

json_output

Added json_output optional parameter to http.GET If True, Returns the JSON object from the http response if available.