.. _scripting:

Scripting
*********

.. raw:: html

   <div class="new new-prev">Since 2.2.0</div>

Gaia Sky exposes an API that can be accessed through Python (see below), via an :ref:`HTTP server <rest-server>`, and using the :ref:`in-app console <console>`. In this section we focus on the Python method. The API can be called from Python programs, that must be run with the system Python interpreter. They connect to a server created by a running instance of Gaia Sky.

.. _scripting-environment:

Installing the environment
--------------------------

In order to connect to Gaia Sky from your Python scripts, you need to set up the environment. There are two main steps:

1. Install Python. Any reasonably up-to-date version of Python 3 should do.
2. Install the ``py4j`` package. We recommend using ``pipenv``, or any other virtual environment manager. You can install ``pipenv`` for your user with ``pip install --user pipenv``.

.. code:: console
    
    $  pipenv install py4j

Alternatively, you may use your distribution or operating system package manager to install ``py4j``. Please, refer to its documentation for more information.

Here are the `Py4J homepage <https://www.py4j.org/>`__ and the `Pipenv homepage <https://pipenv.pypa.io/en/latest/>`__.

Running a test script
---------------------

Once Python and ``py4j`` are ready, launch Gaia Sky, download `this script <https://codeberg.org/gaiasky/gaiasky/src/branch/master/assets/scripts/tests/get-cam-state.py>`__, open a terminal window (PowerShell in Windows) and run:

.. code:: console

    $  # If you used pipenv, enter the virtual environment
    $  pipenv shell
    $  # Run the script
    $  python get-cam-state.py


If all goes well, the script should print some information it got from Gaia Sky about the camera. This means that your environment is ready to use.

Debugging
---------

To debug a script in the terminal you can use the module ``pudb``. Once installed, run this:

.. code:: console

    $  python -m pudb gaiasky-script.py

Please refer to the `pudb documentation <https://documen.tician.de/pudb/>`__ for more information.

.. _api-versions:

API versions
------------

.. raw:: html

   <div class="new">Since 3.6.9</div>

As of Gaia Sky 3.6.9, we have two API versions: :ref:`APIv2 <apiv2>` and :ref:`APIv1 <apiv1>`. If you are starting with Gaia Sky scripting, **we strongly recommend using the newer APIv2**. The old APIv1 will be kept around for backwards compatibility. We'll still fix bugs, but it won't be extended and developed further.

.. toctree::
   :maxdepth: 3

   APIv2
   APIv1