Package: ovbpclient
# ovbpclientA python client to interact with Openergy Virtual Building Platform.## Installationpip install ovbpclient## Documentation### Quickstart[A detailed example with best practices is given here.](doc-users.md)### User guideNote: the following user guide focuses on standard actions.However, is often preferable to use shortcuts, when available, instead of standard actions. Many shortcuts
are given in the quickstart example.#### API documentationTo get a detailed documentation of the API, you may [directly connect to VBP backend](https://data.openergy.fr/api/v2) with your browser, log in, and navigate
using the proposed links. On each page, you will find a ? on the upper right, you may click on it to view
the documentation.#### The clientThe central object is the client. It contains:
- the target url
- the authentication credentials
- a list of all available endpoints (see bellow, chapter endpoints)
- shortcuts to access some records easily (get_organization, get_project, …)To initialize, your must provide credentials :Prepare auth file:login
passwordInitialize client:from ovbpclient import Client# first method (see above for auth file content)
client = Client(auth_path)Instead of a path, you can give a buffer, which may be useful in some cases:with open(auth_path) as f:client = Client(f)#### EndpointsEndpoints are the entry points to resources (comparable to tables in a relational database). They are attached to
the client. For example :
- projects: client.projects
- organizations: client.organizations
- gates: client.gates
- …Each endpoint contains:
- standard actions
- shortcuts to easily perform custom actions (varies for each endpoint)Standard endpoint actions:list(start=0, limit=200, filter_by=None): returns a list of records (paginated).Starting from {start} record, in the limit of {limit} (the backend paginates records).
You may filter these records if you provide a dictionary {filter_by} (filter_variable=filter_value, …).
Available filters are described in the backend API.Example:client.projects.list(filter_by=dict(organization=organization_id), limit=10)iter(filter_by=None): return an iterator of record elements.If you iter the reruned iterator, the client will automatically perform paginated querries until all the table
has been exhausted.
This may for example be usefull if you want to iter records until you find one matching a specific condition,
then stop (which is more efficient than downloading all records).
The filter system is available.Example:for project in client.projects.iter():if “energy” in project.name:breaklist_all(filter_by=None): returns a list of all records.The client performs multiple paginated requests, until all table has been exhausted.
Should only be used when you known that there are not too many records.
Filter system is available.Example:projects = client.projects.list_all(filter_by=dict(organization=organization_id))create(**data): creates and returns a record.You must provide data containing record info.Example:project = client.project.create(organization=organization_id, name=”project_name”, comment=”my comment”)Note: it is easyier here to use the following shortcut:
organization = client.get_organization(“organization_name”)
project = organization.create_project(“project_name”, comment=”my comment”)retrieve(record_id): retrieves a record.You must provide record id.Example:project = client.project.retrieve(“project_id”)Note: it may be easyier here to use a shortcut (although less efficient in terms of number of requests).
organization = client.get_organization(“organization_name”)
project = organization.get_project(“project_name”)list_action(http_method, action_name, params=None, data=None, return_json=True, send_json=True): performs a custom action on enpointThis is an expert use of client, normally using proposed shortcuts should be sufficient.
The available list actions are given in the backend API documentation.#### RecordsRecords are the objects that are returned by endpoints queries.A record contains:
- its data (stored in a dictionary: record.data).The content of this dictionary is also available using getattr syntax (project.name for example, instead of project.data[“name”])- standard record actions
- shortcutsStandard record actions:reload(): performs a request to reload data from apiExample: series.reload()update(**data): updates record dataExample: project.update(comment=”new comment”)delete(): deletes recordExample: unitcleaner.delete()detail_action(http_method, action_name, params=None, data=None, return_json=True, send_json=True):
performs a custom action on recordThis is an expert use of client, normally using proposed shortcuts should be sufficient.
The available detail actions are given in the backend API documentation.