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

*oups* requires Python 3.13 or higher and is published on PyPI.

Install from PyPI
-----------------

.. code-block:: bash

    python -m pip install --upgrade pip
    python -m pip install oups

Using Poetry (Recommended)
---------------------------

For development or if you prefer poetry:

.. code-block:: bash

    # Install poetry if you don't have it
    curl -sSL https://install.python-poetry.org | python3 -

    # Clone and install oups
    git clone https://codeberg.org/pierrot/oups
    cd oups
    # Ensure Poetry uses Python 3.13
    poetry env use 3.13
    poetry install

    # Run tests
    poetry run pytest

Using Pip (Development Install)
-------------------------------

For development with editable install:

.. code-block:: bash

    git clone https://codeberg.org/pierrot/oups
    cd oups
    pip install -e .

    # Run tests
    pytest

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

*oups* automatically installs these required dependencies:

* `pandas <https://pandas.pydata.org/>`_ (>=2.2.3) - Data manipulation
* `numpy <https://numpy.org/>`_ (>=2.0) - Numerical computations
* `fastparquet <https://github.com/dask/fastparquet>`_ (>=2023.10.1) - Parquet file handling
* `numba <https://numba.pydata.org/>`_ (>=0.61.2) - JIT compilation for performance
* `sortedcontainers <http://www.grantjenks.com/docs/sortedcontainers/>`_ (>=2.4.0) - Efficient data structures
* `flufl-lock <https://fluflock.readthedocs.io/>`_ (>=8.2.0) - File locking
* `joblib <https://joblib.readthedocs.io/>`_ (>=1.3.2) - Parallel processing
* `cloudpickle <https://github.com/cloudpipe/cloudpickle>`_ (>=3.1.1) - Serialization

Verification
------------

To verify your installation:

.. code-block:: python

    import oups
    print(oups.__version__)

    # Basic functionality test
    from oups.store import toplevel

    @toplevel
    class TestIndex:
        name: str
        version: int

    # Test creating and using the index
    test_idx = TestIndex("example", 1)
    print(f"Index string representation: {test_idx}")
    print("Installation successful!")