Getting started
===============
Prerequisites
-------------
Your organisation needs an instance of `Divera 24/7`_ and you need an account on there.

.. _`Divera 24/7`: https://www.divera247.com/

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 :code:`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 :code:`"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 :code:`Client.__del__()` is called.

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

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

.. _`keyring`: https://pypi.org/project/keyring/

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 :code:`client.start_polling`, you do not have to use :code:`async` for :code:`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())