Getting started
#################

Installation
***************
The dace-query package lets easily query DACE and access public and private data using a simple utility tool.
The dace-query package is available on PyPi and can be installed using `pip <https://pypi.org/project/pip/>`_ or `conda <https://www.anaconda.com>`_ :


.. code-block:: bash

    # Install using pip
    pip install dace-query

    # Update using pip
    pip install dace-query --upgrade

.. code-block:: bash

    # Install using conda
    # First, create a conda environment
    conda create -n <env_name> python=3.9 # python version equal or upper than 3.9
    # Second, activate the environment
    conda activate <env_name>
    # Finally, install using anaconda pip
    pip install dace-query

Make sure the package is installed correctly :

.. code-block:: python

    # Import dace
    import dace_query

    # List content of the dace package
    help(dace_query)

Authentication
***************

In order to access the private data of DACE, an authentication system has been implemented.
This one works very simply, it just requires three things detailed in the following subsections:


- :ref:`A DACE account <create-account>`
- :ref:`An API key <api-key>`
- :ref:`A local .dacerc file <dacerc>`


.. _create-account:

Create an account
=================
Register on the `DACE web portal <https://dace.unige.ch/createAccount/>`_ with the university email address.

.. image:: _static/create-account.png

.. _api-key:

Generate the DACE API key
=========================
To obtain an API key:

    1.  Login on DACE (https://dace.unige.ch)
    2.  Go to the user profile
    3.  Click on [Generate a new API key]

        .. image:: _static/generate-api-key.png

    4.  Copy this new API key into the .dacerc file


.. _dacerc:

The .dacerc file
=========================
The **.dacerc** file, (**you have to create it**), located by default in the home directory (~/.dacerc) and in TOML
format, defines a user section with a key-value pair specifying the user's API key (see below).

.. code-block:: cfg

    [user]
    key = apiKey:<xxx-xxx-xxx>

For example, if your API key is 12345678-1234-5678-1234-567812345678, then the .dacerc file will be :

.. code-block:: cfg

    [user]
    key = apiKey:12345678-1234-5678-1234-567812345678

To create the .dacerc file on Linux or macOs, open a terminal window and type :

.. code-block:: bash

    printf '[user]\nkey = apiKey:%s\n' "your-api-key-here" > ~/.dacerc

Example usage
**************

.. code-block:: python

    # Import the ready-to-use exoplanet instance
    from dace_query.exoplanet import Exoplanet

    # Retrieve data from the exoplanet database
    result: dict = Exoplanet.query_database(limit=10, output_format='dict')

    # Get the planet names
    planet_names: list = result.get('obj_id_catname')

    # Print the planet names
    print(planet_names)


For more examples of uses, such as **filtering bad quality data** (see :doc:`usage_examples`)

Contact
********

In case of questions, proposals or problems, feel free to contact the `DACE support <mailto:dace-support@unige.ch>`_ .

Links
********
* `DACE website <https://dace.unige.ch>`_
* :doc:`changelogs`