Проектный инструментарий

Poetry

Инструмент для управления зависимостями в Python проектах, с управлением виртуальными окружениями (аналог pip, conda), сборкой и публикацией проектов. Поддерживает воспроизводимые конфигурации среды. Настройки в файле pyproject.toml. Установка пакетов:

poetry add <package_name>
poetry add <package_name> --group=<groupname>

Pre-commit

Инструмент командной строки для валидации файлов проекта, в соответствии со сделанными настройками и хуками в .pre-commit-config.yaml. Используется “перед коммитом” в репозиторий или в любой другой момент, когда нужно валидировать файлы проекта. Использование:

pre-commit

Ruff

Универсальный линтер/форматтер. Установлен как расширение для VS Code. Выполнена настройка settings.json в VS Code с тем, чтобы Python файлы (.py и .ipynb) автоматически проверялись, форматировались и приводились к стандарту PEP8 при сохранении. Также установлен как пакет среды выполнения, использование:

poetry run ruff .

Mypy

Cтатический анализатор типов для Python, который позволяет находить ошибки несоответствия типов в коде. Установлен как пакет среды выполнения, использование:

poetry run mypy .

Pytest

Среда тестирования кода (фреймворк) на Pyton. Установлен как пакет среды выполнения, использование:

poetry run pytest .

GitKraken

Мультифункциональный десктопный GUI клиент для удобного управления репозиториями, включая управление сложными проектами при совместной работе. Альтернатива плагину GitLens для VS Code.

Quarto

Система публикации и рендеринга отчетов и статей с поддержкой markdown.

Установка

Стандартная установка через PyPi и conda-forge, соответственно:

pip install -U quarto-cli jupyter
conda install -c conda-forge quarto jupyter

Установка для poetry (в группу “doc”):

poetry add jupyter --group=doc
poetry add quarto-cli --group=doc

Также Quarto можно установить как desktop приложение quarto-cli - в этом случае префикс poetry run в последующих командах можно опустить.

Инициализация и сборка проекта

После экспериментов с настройками выглядит оптимальным инициализировать Quarto в корневой папке проекта (вместо предложенной /doc), поскольку из корня документация проекта собирается наиболее полно и правильно включает все вложенные ссылки.

poetry run quarto create project website --no-open

Запуск сервера, чтобы видеть превью изменений моментально:

poetry run quarto preview

Сборка проекта целиком. Первая команда формирует главную страницу сайта из файла README.md репозитория (опционально).

cp README.md index.qmd
poetry run quarto render

Snakemake

Фреймворк для написания сложных сценариев обработки экспериментальных данных и распределенного запуска этих сценариев в вычислительной среде.

Рекомендуемая установка с одновременным созданием среды conda/mamba:

mamba create -c conda-forge -c bioconda -n snakemake snakemake

В рамках задачи запускался пайплайн обработки данных с использованием виртуальной среды conda, содержащей ML-пакеты Scikit-learn, Tensorflow и зависимости для тренировки ML-модели внутри пайплайна Snakemake. Команды подготовки среды и запуска:

conda env export -n ml -f .envs/ml.yml
snakemake --use-conda --conda-prefix ./.envs --cores 4

Hydra

Легкий фреймворк для разработки Python приложений с функционалом составления и переопределения конфигураций. Фокус инструмента в том, чтобы упростить добавление функционала и внедрения новых юзкейсов в приложение. Hydra удобен для использования в ML-проектах, в которых обычно используется перебор и/или подбор параметров для тренировки ML-моделей.

Типичный пример использования состоит из файла конфигурации yaml и декоратора для Python-функции main:

cs = ConfigStore.instance()
cs.store(name="trees_config", node=TreesConfig)

@hydra.main(config_path="hydra", config_name="config", version_base=None)
def main(cfg: TreesConfig) -> None:
    ...

К хорошей практике следует отнести явное определения типа конфига при передаче в функцию main def main(cfg: TreesConfig) через описание Dataclasses.

DVC

DVC является подсистемой версионирования данных с открытым исходным кодом. DVC предназначена для совместного использования моделей машинного обучения, воспроизводимости экспериментов, версионирования моделей, данных и конвейеров. Имеются плагины для работы с большинством популярных облачных хранилищ.

DVC использует git like интерфейс и включает такие инструменты как утилита командной строки CLI, функциональный плагин для VS Code, SaaS-приложение DVC Studio. Основной принцип работы заключается в том, что хэши данных хранятся в обычном git-репозитории, в то время как сами данные размещаются в подходящем локальном или облачном хранилище.

Пример установки вместе с плагином для Google Disk:

poetry add dvc dvc-gdrive

Типичный пример использования в текущем проекте:

  1. Инициализация репозитория DVC
  2. Добавление удаленного хранилища
  3. Добавление файла данных (смысловой аналог git add)
  4. Отправка в хранилище (смысловой аналог git push)
  5. Запуск пайплайна из dvc.yaml

В том же порядке в командах:

dvc init
dvc remote add -d --project gdrive gdrive://<URL>
dvc add path/filename.ext
dvc push
dvc repro

Это очень приблизительный пример, т.к. DVC представляет собой весьма объемный инструмент и его подробное рассмотрение выходит за рамки данного документа.

LakeFS

LakeFS - это инструмент с открытым исходным кодом, который предлагает возможность версионирования данных и превращает объектное хранилище в Git-подобный репозиторий. Это позволяет управлять озером данных подобно git-управлению кодом, и создавать повторяющиеся, атомарные и версионные операции с данными. LakeFS реализует новый уровень абстрации над данными, притом сам не является хранилищем. В качестве базового сервиса хранения поддерживются AWS S3 (с совместимостью по API S3), Azure Blob Storage и Google Cloud Storage.

LakeFS управляется двумя консольными утилитами, а также поддерживает несколько библиотек для Python. Пример установки в Linux:

mkdir /bin/lakefs && cd /bin/lakefs
wget https://github.com/treeverse/lakeFS/releases/download/v1.22.0/lakeFS_1.22.0_Linux_x86_64.tar.gz
tar -xvf lakeFS_1.22.0_Linux_x86_64.tar.gz
ln -s /bin/lakefs/lakefs /usr/local/bin/lakefs
ln -s /bin/lakefs/lakectl /usr/local/bin/lakectl

Пример простого запуска в Docker (НЕ для production):

docker run --pull always \
           --name lakefs \
           -p 8000:8000 \
           treeverse/lakefs:latest \
           run --quickstart

Через несколько секунд контейнер lakeFS будет готов к использованию:

lakeFS running in quickstart mode.
    Login at http://127.0.0.1:8000/

    Access Key ID    : AKIAIOSFOLQUICKSTART
    Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Следует сохранить показанные на экране секреты. Локально развернутый сервис LakeFS будет доступен по адресу http://127.0.0.1:8000/