Skip to content
This repository was archived by the owner on Mar 17, 2026. It is now read-only.

development.md

Latest commit

 

History

History
125 lines (106 loc) · 7.47 KB

development.md

File metadata and controls

125 lines (106 loc) · 7.47 KB

Разработка в репозитории

Обзор репозитория

├── .dvc                     Конфигурация DVC
├── data                     Данные и иные артефакты ML
├── docs                     Документация
├── model                    Файлы обученной модели
├── notebooks                Интерактивные скрипты Jupyter
├── reports                  Отчёты, графики и метрики
├── scripts                  Скрипты для регулярных задач
├── tests                    Тесты проекта
├── yoric                    Основной код Python-пакета
├── .dvcignore               Файл исключений DVC
├── .flake8                  Конфигурация линтера Flake8
├── .gitignore               Файл исключений Git
├── .pre-commit-config.yaml  Конфигурация автопроверок при commit и push
├── .pylintrc                Конфигурация линтера Pylint
├── Makefile                 Конфигурация GNU Make для быстрых команд
├── dvc.lock                 Сохраненное состояние пайплайна DVC
├── dvc.yaml                 Конфигурация пайплайна DVC
├── params.yaml              Конфигурация гиперпараметров для пайплайна DVC
├── pyproject.toml           Прочие настройки Python-проекта
├── readme-en.md             Описание проекта EN (TODO)
├── readme-ru.md             Описание проекта RU
├── requirements.txt         Python-зависимости проекта
└── setup.py                 Скрипт сборки Python-пакета

Используемые инструменты

  • Хранение артефактов и метрик: DVC
  • Качество кода: Mypy, Pylint, Flake8
  • Форматирование: Black, iSort, Unify, Pyupgrade
  • Прототипирование: Jupyter Notebook
  • Прочее: Pre-commit, GNU Make

Быстрые команды

Для удобства разработки регулярные команды вынесены в Makefile (GNU Make). Утилита Make, как правило предостановлена на дистрибутивах Linux, но, если необходимо, её можно установить:

sudo apt install make -y

С помощью Make рекомендуется делать локальные проверки перед коммитами и форматировать код. Подробнее о доступных командах можно посмотреть в справке (выполняя из корня проекта):

make help  # или просто make

При разработке на Windows (без WSL) эти команды работать не будут и их нужно будет запускать вручную, копируя из Makefile.

В целом текущая версия репозитория не расчитана под разработку на Windows.

Автоматические проверки

В репозиториии настроены pre-commit хуки на действия commit, push и checkout. В нашем случае хуки проверяют:

  • согласованность версий файлов в удаленном хранилище, кеше DVC и самом репозитории
  • отсутствие ошибок в используемых типах
  • отсутствие логических и стилевых ошибок
  • прохождение тестов
  • отсутствие больших файлов в коммитах и прочие мелкие проверки

И дополнительно:

  • автоформатируют код, чтобы он был консистентен и единообразен
  • очищают файлы кешей, сборки, мусор, оставленные при работе инструментов

Основные шаги pre-commit переиспользуют соответствующие команды Make.

Создание окружения

В проекте предполагается использование версии Python >=3.9!

  1. Создать виртуальное окружение Python с помощью Make:

    make venv

    Или вручную:

    python -m venv venv && \
source /venv/bin/activate && \
pip install --upgrade setuptools wheel pip && \
pip install -e . && \
pre-commit install

  2. Выгрузить данные из DVC.

    Команды выполняются из корня проекта! Если по какой-то причине DVC не подхватывает корень, достаточно установить переменную окружения PYTHONPATH=$(pwd).

    Посмотреть каких данных не хватает:

    dvc status

    Выгрузить недостающие данные или все:

    dvc pull -R

Данные для обучения и тестирования

Данные взяты из русской Википедии с помощью библиотеки corus. Хранение и версионирование реализовано с помощью DVC:

  • Скрипты для получения данных находятся в директории scripts

  • Пайплайн вызова соответствующих скриптов доступен в dvc.yaml

  • Параметры для вызова скриптов подставляются DVC из файла params.yaml автоматически

  • Датасет можно пересобрать заново при необходимости (или изменении параметров):

    dvc repro

    Подробнее о работе с пайплайнами DVC можно ознакомиться в документации.

Общий процесс

  1. Внести правки в репозитории или добавить новый эксперимент.
  2. Добавить тесты в tests и проверить их работу: 
    pytest [tests/path/to/concrete/test.py]
  3. Проверить, что ваши правки не внесли регресс, запустив все тесты: 
    make tests
  4. Опционально, проверить себя до коммита: вручную запустить линтер, форматтер, статический анализ с помощью Make: 
    make all  # [style|types|...] см. справку: make help
  5. Сделать коммит и отправить в репозиторий
  6. Оформить PR по завершению работ