Package: opisense-client
opisense_clientPython 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.htmlGetting startedThese instructions will guide you through the process of getting you ready to use the opisense_client packagePrerequisites1. Get an Opisense account.Contactinfo@opinum.comor seewww.opinum.comto get an account2. Get Opisense API credentials.Contactsupport@opinum.comto get an API secret and API key3. Install opisense_client packageYou can install opisense_client by typingpip install opisense-clientin your terminal.ConfigurationCredentials fileAlthough 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"}}Thexxxxxxshould 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 :importjsonwithopen('path/to/your/file/credentials.JSON',encoding='utf-8')asfile:credentials=json.load(file)user_credentials=credentials['user']api_credentials=credentials['api']path/to/your/file/is the local path to your credentials file andcredentials.JSONis the filename.Functionalitiesrootchange_urls:This function adapts the API URLs.The optionalapi_urlsets a new API URL
The optionalauthorization_urlsets a new AUTHORIZATION URL
The optionalstandard_push_data_urlsets a new STANDARD PUSH DATA URLobjectsApiFilter: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 underhttpsection.This is only used is input for thehttp.GET()method.
SeeOpisense API documentationfor 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 theStandardDataobject construction.The__add__method of this class allows adding datapoints datetimes and values to the existing ApiFilter object.StandardData:
This object contains aDataPointsobject 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.ThePOSTmethod 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. SeeOpisense API documentationfor more details on Opisense Objects.ThePOST,PUTandDELETEmethods of this class take a bearer token as argument and uploads the StandardData object to Opisense API, using the appropriate http method.Thejsonmethod of this function returns the object contain, serialized in JSON, using the built-injsonmethod.httpauthorize:This function takes user credentials and api credentials dictionaries as input and returns the OAuth2 bearer token required to interract with Opisense API.The optionalfeedbackargument returns in the console the Opisense account name and ID for which you got a token.NEWThe optionalaccount_idargument 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 optionaljson_outputargument changes the output to the json content of the server response.The optionalfeedbackargument returns the server response code in the console.
The optionalopisense_objectargument 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.Theparent_idargument is necessary to create some type of OpisenseObjects. SeeOpisense API documentationfor details.The optionalfeedbackargument returns the server response code in the console.The optionalpathargument allows to change the default path appended to the url in the POST call.
The optionalforce_pathargument 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.Theparent_idargument is necessary to update some type of OpisenseObjects. SeeOpisense API documentationfor details.The optionalfeedbackargument returns the server response code in the console.
The optionalpathargument allows to change the default path appended to the url in the POST call.
The optionalforce_pathargument 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 optionalfeedbackargument returns the server response code in the console.The optionalpathargument allows to change the default path appended to the url in the POST call.
The optionalforce_pathargument allows to use a path not in the default list.Objects and Methods descriptionEvery object and method is described with docstrings. You can easily access it by runninghelp(method)TestsThe tests are located in.\opisense_client\tests\tests.py. To run the tets, do the following:Install pytest:pip install pytestFrom the root folder of this repos, runpytest .\opisense_client\tests\tests.py -vvChangelog1.5.0:Features:Allow to use other URLs than default ones1.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 thepathargument added in v1.3.0 as it was leading to some new errors.force_pathfromPUT(),POST()andDELETE()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'])Makeopisense_objectoptional forPOSTandDELETEfunctions. Addidargument toDELETEfunction to enter the Opisense internal Id to delete.1.3.0:Fixes:Add a rule to allowfromandtofilters inApiFilterwithout interfering with pythonfromreserved word. The argumentsdate_fromanddate_toare automatically converted tofromandtofilters in the object initialization.Add apathargument and update theforce_pathargument toPUT(),POST()andDELETE()functions, to allow the usage of non-standard paths.1.2.1:Fixes:Fix import problem1.2.0:Features:Addopisense_objectoption tohttp.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 updatesetauth = Noneinoauth.fetch_token()in http.py to avoid getting an 'invalid_client' error1.0.0:First stable versionStandardDataAdded variableId as unique identifier optionDocumentationUpdated README.MD and documented every object and method0.3:force_pathAdded force_path optional parameter to http.POST and http.PUT.
Overwrites the default OpisenseObject.api_path in the http call.json_outputAdded json_output optional parameter to http.GET
If True, Returns the JSON object from the http response if available.