.. index::
    package
    dependencies
    pip
    uv

    
..
    `...  <ex:...>`



.. _`sec:uv`:

Package management
==================



Prerequisite
------------

Install ``uv`` on your machine.

Project management tool, especially **dependencies**, build distributions etc. See the git `repo <https://github.com/astral-sh/uv>`_  
and the `docs <https://docs.astral.sh/uv/guides/projects/>`_. 
The dependencies (the external package that your code uses) are installed in a **virtual environnement** (in the ``.venv`` folder). 
The role a virtual environment is to isolate every dependency of a given project because dependencies can differ between projects. 

Installation
------------

.. After download

.. .. code-block:: console

..     $ pip install uv

if ``uv`` not found, it might be missing from the path, on linux:

.. code-block:: console

    $ export PATH="$HOME/.local/bin:$PATH"


Typical structure
------------------

.. code-block:: console

    .
    ├── docs
    ├── .git
    ├── .gitignore
    ├── pyproject.toml
    ├── .python-version
    ├── README.md
    ├── src
    │   └── package
    │       ├── __init__.py
    │       └── module.py
    ├── tests
    ├── uv.lock
    ├── .venv
    └── .vscode

Other packages can live in a folder under ``src``. 

Basic usage
-----------

Initialize a project and open the folder (check the ``pyproject.toml``), with ``PACKAGE`` and ``PROJECT`` being 
restpectively the package name and the project name.

.. code-block:: console

    $  uv init PROJECT --name PACKAGE

Install the latest python:

.. code-block:: console

    $  uv python install

To open a python console:

.. code-block:: console

    $  uv run python 

Add a dependency for development

.. code-block:: console

    $ uv add --dev pytest

Add a dependency (check the ``pyproject.toml``)

.. code-block:: console

    $ uv add FOO

Remove a dependency (check the ``pyproject.toml``)

.. code-block:: console

    $ uv remove FOO

Run a python module with ``PATH`` being the path to sources:

.. code-block:: console

    $ uv run PATH/FILE.py

Run tests (the tests will be covered in more details during a future session)

.. code-block:: console

    $ uv run pytest

.. To rebuild the same virtual environment elsewhere, after cloning the project:

.. .. code-block:: console

..     $ uv sync

.. Install the developed package in editable mode (any changes you make to the source code immediately 
.. affect the installed package—you do not need to reinstall it every time you edit a file). 
.. It will for example allow importing packages in the python interpreter. 
.. At the project root folder:

.. .. code-block:: console

..     $ uv pip install -e .


Basic usage
-----------

Demo



.. code-block:: python

    # init a project, add a module

    # add / remove dependecies

    # run a python file and a test