Getting started

Prerequisites

Your organisation needs an instance of Divera 24/7 and you need an account on there.

Installation

Install this library using:

pip install git+https://codeberg.org/fabbecker/divera_python.git

Write your program

Basic code structure

The basic code structure consists of an asynchronous function that should be called main

import asyncio
import divera

async def main():
    # Set the location of the config file to ./project_configuration_folder/divera.json
    client = divera.Client("project_configuration_folder/")

if __name__ == '__main__':
    asyncio.run(main())

You can also leave out the "project_configuration_folder/" part. In this case the config is not written to any file and the access token is removed after the code finishes.

Login

If you have not created a config file before, you might want to login:

import asyncio
import getpass
import divera

async def main():
    # Set the location of the config file to ./project_configuration_folder/divera.json
    client = divera.Client("project_configuration_folder/")

    if not client.is_logged_in():
        await client.login(
            username=input("Username: "),
            password=getpass.getpass("Password: "),  # Use getpass to hide your password
            domain="https://" + input("Domain: https://").lstrip("https://").rstrip("/") + "/",
        )
        client.store_config()

if __name__ == '__main__':
    asyncio.run(main())

When logging in, you request an access token for your client. Your password is not stored anywhere and you access token (which you need to be equally careful about) is stored using keyring. When using no configuration folder, your access token is still stored, but will automatically be deleted when Client.__del__() is called.

You can also log in without asking the user for their password but their access token using client.login_with_access_token instead.

You can delete the stored access token by calling client.logout().

Have divera_python do the main loop

If you want to only react on events that are triggered by divera, you can use callbacks. If you use client.start_polling, you do not have to use async for main.

import asyncio
import divera
import divera.triggers

def turn_lights_on(change: divera.triggers.Trigger, client: divera.Client):
    # Put your code here
    pass

# It is recommended to use async functionality for faster code execution in some situations
async def publish_summary_on_website(change: divera.triggers.Trigger, client: divera.Client):
    # Put your code here
    pass

async def main():
    # Set the location of the config file to ./project_configuration_folder/divera.json
    client = divera.Client("project_configuration_folder/")

    client.add_callback(
        callback=turn_lights_on,
        filter_=divera.triggers.ObjectCreated,
        model=divera.Alarm,
    )
    client.add_callback(
        callback=publish_summary_on_website,
        filter_=divera.triggers.ObjectRemoved,
        model=[divera.Alarm, divera.Event],
    )

    await client.listen()

if __name__ == '__main__':
    asyncio.run(main())

Use your own main loop

You can also use your own main loop.:

import asyncio
import divera

async def main():
    client = divera.Client("project_configuration_folder/")

    while True:
        alarms = await client.request(
            divera.Alarm.get_all(),
        )
        print(alarms)

if __name__ == '__main__':
    asyncio.run(main())