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

Supported Python
----------------

``at-py`` requires Python 3.12 or newer. CI currently exercises Python 3.12 and
3.13, which are the recommended development and release targets.

Core Install
------------

The core package keeps the runtime dependency set small:

.. code-block:: bash

   python -m pip install oalib-at-py

The PyPI distribution is named ``oalib-at-py``; the Python import package remains
``at_py``.

Runner Client
-------------

``ATClient`` uses the ``at_runner`` Python gRPC client to talk to an
``at-runner`` service. Install the client from the public, pinned ``at-runner``
tag:

.. code-block:: bash

   python -m pip install "at-runner @ git+https://github.com/jgebbie/at-runner.git@v0.3.0#subdirectory=client/python"

The client pin matches ``at_py.AT_RUNNER_GIT_REF`` and
``at_py.DEFAULT_AT_RUNNER_IMAGE``. It is kept out of public PyPI metadata because
PyPI packages should depend on normal index packages rather than VCS URLs.

From a checkout, create a virtual environment and install development tools:

.. code-block:: bash

   python -m venv .venv
   . .venv/bin/activate
   python -m pip install -U pip
   python -m pip install -e ".[dev]"

Optional Extras
---------------

Install only the extras you need:

.. code-block:: bash

   python -m pip install "oalib-at-py[mat]"  # MATLAB .mat support

``[mat]`` installs SciPy and h5py for classic MAT files and MATLAB v7.3 HDF5
files. Without this extra, MAT helpers raise ``ImportError`` with an install
hint.

From a checkout, use ``python -m pip install -e ".[mat]"`` for the same optional
dependencies.

Development Checks
------------------

Use these checks before opening a pull request or release:

.. code-block:: bash

   ruff check .
   pytest
   sphinx-build -W -b html docs docs/_build
   prek run --all-files

Integration tests require Docker, the pinned ``at_runner`` client, and access to
the pinned runner image:

.. code-block:: bash

   python -m pip install "at-runner @ git+https://github.com/jgebbie/at-runner.git@v0.3.0#subdirectory=client/python"
   pytest -m integration