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

Choose one of the following methods below to install the package:

* If you are using Mojito in another project, we suggest to add Mojito as a
  dependency using the project's dedicated environement manager; see :ref:`uv
  <with-uv>` (recommended) or :ref:`pip <pip>` below.
* You can also install :ref:`from source <from-source>` (discouraged).
* If you wish to contribute to Mojito, we suggest to :ref:`setup the Mojito
  developement environement <dev>`.

.. _with-uv:

With uv (recommended)
---------------------

DDPC guidelines suggest to use `uv <https://uv.gitlab.io/>`_ to create a
dedicated virtual environment for each project you are working on, and manage
its dependencies.

First, install uv if you haven't already:

.. code-block:: bash

   curl -LsSf https://astral.sh/uv/install.sh | sh

If you need to create a new dedicated virtual environement (and the directory
structure) for your project, run the follow commands. If you already have
created your project virtual environement, skip this step and simply cd into
your project root directory.

.. code-block:: bash

   # If you need to create a new venv
   uv init my-mojito-env
   cd my-mojito-env

Finally, add Mojito as a project dependency:

.. code-block:: bash

   uv add mojito

.. tip::

   We strongly encourage the creation of isolated, dedicated virtual
   environement for each of your project. Doing so ensures dependencies are
   compartimentalized and prevents dependency hell.

.. _pip:

With pip
--------

Equivalently, you can use pip to create a dedicated environement and install
Mojito.

To create a new virtual environment with pip, run the following commands. If you
already have created your project virtual environement, skip this step and
simply activate it.

.. code-block:: bash

   # If you need to create a new venv
   python3 -m venv my-mojito-env
   # Activate venv
   source my-mojito-env/bin/activate

Then, run the following command to install Mojito in the activated environement,

.. code-block:: bash

   pip install mojito

.. tip::

   A good habit is to freeze a list of dependencies for your project using ``pip
   freeze > requirements.txt``, and to commit it. This will allow you to
   recreate the exact same environement at a later time using ``pip install -r
   requirements.txt``.

.. warning::

   You can also install Mojito in your global system Python environement; simply
   run the above command outside of a venv. Note, however, that this is strongly
   discouraged as it breaks compartimentalization and often results in
   dependency hell.

.. _from-source:

From source code and wheel
--------------------------

If you don't have access to the package registry, you can manually download the
source code or wheel from the `project registry
<https://gitlab.esa.int/lisa-sgs/commons/mojito/-/packages>`_. Select the
desired version, scroll down to the “Assets” section, and download the
``mojito-<VERSION>.tar.gz`` or ``mojito-<VERSION>-py3-none-any.whl`` file.

You can then install it using one of the following commands:

.. code-block:: bash

   # From source code
   pip install mojito-<VERSION>.tar.gz

.. code-block:: bash

   # From wheel
   pip install mojito-<VERSION>-py3-none-any.whl

.. _dev:

Setup the developement environement
-----------------------------------

If you wish to contribute to Mojito as a developer, you need to **setup the
developement environement** using uv.

Using the dedicated developement environement ensures that all developers use the
same environement and therefore prevents incompatibilities issues. This method
also installs the developer toolchain automatically.

First, clone the project:

.. code-block:: bash

   git clone https://gitlab.esa.int/lisa-sgs/commons/mojito.git
   cd mojito

You can now run any command inside the Mojito developement environement using

.. code-block:: bash

   # Run any command inside the dev venv
   uv run my-command

   # For example, run pylint, mypy black and unit tests
   uv run pylint src/mojito
   uv run mypy src/mojito
   uv run black .
   uv run pytest

We recommend setting up pre-commit hooks,

.. code-block:: bash

   # Setup pre-commit hooks
   uv run pre-commit install

   # Run pre-commit hooks on all files
   uv run pre-commit run --all-files

You can also manually activate the uv-managed environement:

.. code-block:: bash

   # Update and activate uv dev venv
   uv sync
   source .venv/bin/activate

   # Now, run any command inside the dev env, e.g.
   pre-commit run --all-files

.. admonition:: VS Code users

   If you are using VS Code, we recommanded to update the dev venv with ``uv
   sync``, then setting it up as the Python interpreter in VS Code:

   1. In VS Code, open the command palette (Cmd + Shift + P)
   2. Choose "Python: Select Interpreter"
   3. Pick the uv-managed environement located in "./.venv/bin/python"

   Any terminal opened in VS Code will now automatically use this environement.