opisense-client 1.5.1

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

root

• change_urls:
  This function adapts the API URLs.
  The optional api_url sets a new API URL The optional authorization_url sets a new AUTHORIZATION URL The optional standard_push_data_url sets a new STANDARD PUSH DATA URL

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.
  This is only used is input for the http.GET() method. 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 take 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 dictionaries 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. NEW The optional account_id argument allows account switching in multi-account environment (administrators only)

• 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 optional 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. The optional opisense_object argument changes the output to a list of Opisense Objects created from the json response.

• 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 path argument allows to change the default path appended to the url in the POST call. The optional force_path argument allows to use a path not in the default list.

• 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 path argument allows to change the default path appended to the url in the POST call. The optional force_path argument allows to use a path not in the default list.

• 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 path argument allows to change the default path appended to the url in the POST call. The optional force_path argument allows to use a path not in the default list.

Objects and Methods description

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

Tests

The tests are located in .\opisense_client\tests\tests.py. To run the tets, do the following:

1. Install pytest: pip install pytest
2. From the root folder of this repos, run pytest .\opisense_client\tests\tests.py -vv

Changelog

1.5.0:

Features:

• Allow to use other URLs than default ones

1.4.0:

Fixes:

• Remove the header "X-Opisense-Api-Version": "1.1" from http calls, to allow using the last version of the Opisense API.
• Remove the path argument added in v1.3.0 as it was leading to some new errors. force_path from PUT(),POST() and DELETE() functions now accepts strings overriding default path.

Features:

• Add getter and setter to OpisenseObjects to allows getting and setting objects attributes by dot notation. (i.e.: source.siteId give the same result as source.content['siteId'])
• Make opisense_object optional for POST and DELETE functions. Add id argument to DELETE function to enter the Opisense internal Id to delete.

1.3.0:

Fixes:

• Add a rule to allow from and to filters in ApiFilter without interfering with python from reserved word. The arguments date_from and date_to are automatically converted to from and to filters in the object initialization.
• Add a path argument and update the force_path argument to PUT(),POST() and DELETE() functions, to allow the usage of non-standard paths.

1.2.1:

Fixes:

Fix import problem

1.2.0:

Features:

Add opisense_object option to http.GET() function. This option changes the output to a list of Opisense Objects created from the json response.

1.1.2:

Fixes:

Fix StandardData object bug, using mapping_config instead of variableId to build the object.

1.1.0:

Features:

Add datapoints_list as optional input for DataPoints Objects. Allows to create a DataPoints object from a list of dictionaries [{'date':datetime,'value':float}]

1.0.2:

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.