Installation
============

Requirements
------------

gtagora-connector requires **Python 3.6** or higher. It has been tested with Python 3.6 – 3.11.

Install with pip
----------------

The recommended way to install the connector is via `pip <https://pip.pypa.io>`_:

.. code-block:: bash

   pip install gtagora-connector

To install a specific version:

.. code-block:: bash

   pip install gtagora-connector==1.7.7

Upgrade an existing installation
---------------------------------

.. code-block:: bash

   pip install --upgrade gtagora-connector

Install from source
-------------------

If you need the latest unreleased code you can install directly from GitHub:

.. code-block:: bash

   git clone https://github.com/gyrotools/gtagora-connector-py.git
   cd gtagora-connector-py
   pip install .

Dependencies
------------

The following packages are installed automatically:

* `requests <https://requests.readthedocs.io>`_ >= 2.0
* `packaging <https://packaging.pypa.io>`_ >= 20.0
* `numpy <https://numpy.org>`_

Authentication
--------------

gtagora-connector supports three authentication methods.

API key (recommended)
~~~~~~~~~~~~~~~~~~~~~

An API key is a random UUID that can be generated in your Agora user profile.
It can be withdrawn or regenerated at any time, making it safer than using your
password in scripts.

.. code-block:: python

   from gtagora import Agora

   agora = Agora.create('https://agora.mycompany.com', api_key='<YOUR_API_KEY>')

Username & password
~~~~~~~~~~~~~~~~~~~

.. warning::

   Never hard-code passwords in scripts. Use the API key approach instead,
   or read the password from an environment variable.

.. code-block:: python

   import os
   from gtagora import Agora

   agora = Agora.create(
       'https://agora.mycompany.com',
       user=os.environ['AGORA_USER'],
       password=os.environ['AGORA_PASSWORD'],
   )

Token
~~~~~

If you already hold a bearer token (e.g. from a login flow in your own
application) you can pass it directly:

.. code-block:: python

   from gtagora import Agora

   agora = Agora.create('https://agora.mycompany.com', token='<BEARER_TOKEN>')

Minimum Agora server version
-----------------------------

This version of gtagora-connector requires **Agora ≥ 7.14.0** on the server
side. An :class:`~gtagora.exception.AgoraException` is raised if the server
version does not meet the requirement.