CoreConnect - Python helper class to communicate with InoCore
This PIP package provides the CoreConnect
class to easily communicate with an InoCore installation.
Requirements
- Python 3.8 or newer
Installation
Make sure your PIP is up-to-date:
python -m install --upgrade pip
To install it:
python -m pip install core_connect
Usage
Basic
The usage is pretty straight forward. Make sure to import the class:
>>> from core_connect import CoreConnect
Now you can create a CoreConnect
object with the InoCore URL, your InoCore credentials and the current project id:
>>> cc = CoreConnect(url, username, password, project_id)
With that you can easily make InoCore API request with the according HTTP method. The methods will return the deserialized content of the response body. For example:
>>> cc.get('v1/ping')
{'data': {'PONG': 1691587400.685406}, 'statusCode': 200}
# data has to be a JSON-serializable object like a dict or a list.
>>> data = {
'project_id': 'nice_project',
'bus_type': 'MODBUS',
'hostname': '192.168.1.2',
'port': 502,
'name': 'high end DDC'
}
>>> cc.post('v1/bus_config', data=data)
{
'data': {
'object': {
'bus_type': 'MODBUS',
'hostname': '192.168.1.2',
'id': 160,
'is_offline': False,
'name': 'high end DDC',
'node_id': -1,
'packet_size': 0,
'port': 502,
'project_id': 'nice_project',
'protocol': 'tcp',
'ref_user_id': 1,
'status': 1
},
'status': 'OK'
},
'statusCode': 200
}
Per default the methods will return the deserialized content of the response body on success. On failure an Exception will be raised. The kind of Exception raised can give a hint where the error might have happened:
-
InvalidUrlException:
The InoCore URL or the URL resulting from adding the endpoint in a call is not valid. -
AuthorizationError:
You provided wrong credentials or your user does not have access on specified API endpoint. -
InvalidResponseException:
The client received an invalid response from InoCore. That might be the case when we received malformed JSON for example, but also more commonly when we received a response with a HTTP status code that is not 2xx. In that case the HTTP status code will be printed as well as the error message from InoCore if there is any.
Advanced
Response object
Instead of returning the deserialized response body, you can also receive the whole requests.Response
object from the call. That gives you more flexibility. To do so, you just need to set the parameter return_object=True
when initializing the CoreConnect
object.
Self-signed TLS
You can also allow connections to InoCore instances that use self-signed TLS certificates. To do that you just need to set the parameter verify_peer=False
when initializing the CoreConnect
object. ONLY do that if you are in a secure network and you know what you are doing!
Class methods
The following methods are implemented:
get(endpoint, params=None)
post(endpoint, data=None, params=None)
put(endpoint, data=None, params=None)
delete(endpoint, data=None, params=None)
Whereas data
has to be JSON-serializable. For filtering, sorting limiting and using offset you can use params
in that form:
params = {
'filter': [
{'property': 'project_id', 'expression': 'ilike', 'value': 'nice_project'},
{'property': 'project_id', 'expression': 'ilike', 'value': 'nice_project_2'},
],
'sort': [
{'property': 'id', 'direction': 'asc'},
{'property': 'name', 'direction': 'desc'},
],
'limit': 10,
'offset': 5,
}
As you can see, you can filter and sort by multiple properties.