Сборка Python проекта с uv и Docker

b931cdb86cf2d383432ff09d0646bcf9.png

Привет, Хабр! Меня зовут Денис Савран. Я старший разработчик направления серверной разработки на интерпретируемых языках и работаю в компании «Криптонит». В этой статье я хочу поделиться опытом сборки проектов на Python с использованием самых современных инструментов.

Прочитав эту статью, вы узнаете:

  1. Как сократить количество инструментов локальной разработки.

  2. Как оптимально собрать образ Docker.

  3. Как проверить код проекта хуками pre-commit и запустить тесты в GitLab CI.

Думаю, что вас, как и многих разработчиков, не устраивает текущая ситуация в Python сообществе: есть большое количество инструментов, которые решают похожие задачи, но делают это по-разному. Из-за огромного числа вариантов нужно прилагать дополнительные усилия, чтобы выбрать тот, который лучше всего подходит для решения предстоящих задач. Каждый инструмент нужно отдельно установить и настроить, после чего запомнить его основные команды.

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

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

Рассмотрим возможные цепочки принятия решений при поиске способа установки Python-утилиты командной строки новичком:

  1. Можно установить pip, затем выполнить pip install foo, но в случае Linux дистрибутива это может поломать какой-нибудь системный пакет. В 2023 году в pip появился механизм защиты от подобных проблем (v23.0). Если он не используется в вашей ОС, то вы по-прежнему можете всё сломать. Также его можно принудительно отключить через опцию --break-system-packages. На Stack Overflow есть даже ответ с предложением добавления этой опции в глобальный конфиг.

  2. Можно попробовать установить пакет через pip, но уже с опцией --user. У этого варианта тоже есть потенциальные проблемы, если установить таким способом несколько пакетов. Зависимости одного пакета могут конфликтовать с зависимостями другого пакета.

  3. Представим, что новичок сразу решит установить пакет в отдельном виртуальном окружении, но и тут не всё так просто. В Python есть virtualenv и venv. Что ему стоит выбрать? При поиске ответа на вопрос можно встретить virtualenvwrapper, pyenv, pipenv, и т. д. Можно пожелать ему терпения.

  4. Если ему повезёт, и он найдёт pipx, то сможет сразу установить свой пакет в отдельном виртуальном окружении, но только при условии, что у него установлена необходимая версия интерпретатора Python. Если это не так, то придётся искать способ установки интерпретатора нужной версии. В 2024 году в pipx появилась возможность установки отсутствующей версии интерпретатора через опцию --fetch-missing-python(v1.5.0). Однако вряд ли вы её легко заметите, так как после неудачной команды установки пакета с опцией --python вам про неё не сообщат.

По-моему, я перечислил достаточное количество проблем, с которыми не хотелось бы сталкиваться при разработке.

Дальше речь пойдёт о перспективном инструменте, который появился только в этом году, но уже решает множество проблем.

Пакетный менеджер uv

В феврале 2024 года появился новый пакетный менеджер uv от создателей Ruff.

Мы заметили его где-то полгода назад при просмотре репозиториев организации astral-sh на GitHub. В тот момент в нём ещё не было возможности создания кроссплатформенного файла жёсткой фиксации зависимостей проекта (lock-файла) и удобной установки проекта в режиме «non-editable», но я всё равно поставил ему звезду, чтобы следить за обновлениями, так как очень понравилась задумка.

uv интересен тем, что решает сразу несколько задач:

  • установка разных версий Python;

  • установка и запуск Python утилит командной строки;

  • создание виртуального окружения Python и установка зависимостей;

  • сборка Python проекта.

Также приятно, что uv очень быстро работает.

Для полного счастья uv пока не хватает получения списка устаревших зависимостей и официальной интеграции с IDE.

Если вернуться к установке Python-утилиты из предыдущего раздела, то с uv хватило бы одной команды:

uv tool install foo

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

Рассмотрим пример использования uv в небольшом проекте на Python с фреймворком gRPC.

Дерево директорий и файлов проекта выглядит следующим образом:

.
├── .venv/                   # Директория с виртуальным окружением Python. Игнорируется в Git.
├── etc/                     # Директория c конфигами.
│   └── alembic.ini
├── src/                     # Директория с исходным кодом.
│   └── my_project/          # Python модуль проекта.
│       ├── grpc/
│       ├── migrations/
│       ├── models/
│       ├── scripts/
│       └── __init__.py
├── tests/                   # Директория с тестами.
├── .dockerignore
├── .env                     # Игнорируется в Git.
├── .envrc                   # Игнорируется в Git.
├── .gitignore
├── .gitlab-ci.yml
├── .pre-commit-config.yaml
├── CHANGELOG.md
├── compose.yaml
├── docker-entrypoint.sh
├── Dockerfile
├── pyproject.toml
├── README.md
├── uv.lock
└── VERSION

Представленная структура поддерживается большинством пакетных менеджеров и систем сборки без необходимости дополнительной настройки. Хранение конфигов в директории etc и исходного кода — в src упрощает последующее копирование файлов в образ Docker.

Ниже приведён пример файла pyproject.toml c пояснениями в комментариях:

pyproject.toml

[project]
name = "my_project"
# Мы храним версию в файле `VERSION`.
# Это позволяет унифицировать логику версионирования разных проектов (например, проектов без файла `pyproject.toml`) и
# чаще переиспользовать Docker-слои, так как не каждое обновление версии сопровождается обновлением зависимостей Python.
version = "0.0.0"
authors = [
    { name = "Ivan Petrov", email = "ipetrov@example.com" },
]
# https://docs.astral.sh/uv/reference/resolver-internals/#requires-python
requires-python = ">=3.12"
# https://docs.astral.sh/uv/concepts/dependencies/#project-dependencies
dependencies = [
    "psycopg2==2.9.*",
    "sqlalchemy==2.0.*",
    "alembic==1.13.*",
    "grpcio==1.66.*",
]

# https://docs.astral.sh/uv/configuration/
# https://docs.astral.sh/uv/reference/settings/
[tool.uv]
# https://docs.astral.sh/uv/concepts/dependencies/#development-dependencies
dev-dependencies = [
    "grpcio-tools==1.66.*",
    "pytest==8.3.*",
]

# Здесь перечислены утилиты командной строки, которые станут доступны после установки проекта.
[project.scripts]
run_server = "my_project.scripts.run_server:cli"
do_something = "my_project.scripts.do_something:cli"

# https://docs.astral.sh/uv/concepts/projects/#build-systems
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Теперь можно создать виртуальное окружение, установить в него все зависимости и закрепить их в lock-файле следующей командой:

uv sync

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

Ниже приведён пример файла .envrc для direnv:

.envrc

# https://direnv.net/man/direnv-stdlib.1.html
dotenv_if_exists
uv sync --frozen
source .venv/bin/activate
# https://github.com/direnv/direnv/wiki/PS1
unset PS1

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

Dockerfile с двухэтапной сборкой

При создании Docker-образа нужно учитывать следующие важные моменты:

  • для получения компактного образа без лишних зависимостей нужно использовать многоэтапную (multi-stage) сборку;

  • для переиспользования слоёв инструкции должны быть упорядочены от редко меняющихся к часто меняющимся;

  • для быстрого запуска приложения файлы Python нужно предварительно компилировать в байт-код.

Можно выделить ещё один довольно важный момент касательно переиспользования Docker-слоёв: права доступа у файлов и директорий на ПК должны совпадать с теми, что используются на сервере сборки Docker-образов. Если они будут отличаться, то при локальной сборке образа c опцией --cache-from все слои инструкций COPY будут создаваться повторно.

Ниже приведён пример Dockerfile с пояснениями в комментариях:

Dockerfile

# syntax=docker/dockerfile:1
# Сборочный этап.
# В качестве базового образа используем Ubuntu, так как в основном разработка у нас ведётся на этой ОС.
# При этом ничто не мешает использовать официальные образы Python от Docker.
FROM ubuntu:noble AS build

ARG python_version=3.12

# Переопределяем стандартную команду запуска шелла для выполнения команд в форме "shell".
# https://docs.docker.com/reference/dockerfile/#shell-and-exec-form
# Опция `-e` включает мгновенный выход после ошибки для любой непроверенной команды.
#   Команда считается проверенной, если она используется в условии оператора ветвления (например, `if`)
#   или является левым операндом `&&` либо `||` оператора.
# Опция `-x` включает печать каждой команды в поток stderr перед её выполнением. Она очень полезна при отладке.
# https://manpages.ubuntu.com/manpages/noble/en/man1/sh.1.html
SHELL ["/bin/sh", "-exc"]

# Устанавливаем системные пакеты для сборки проекта.
# Используем команду `apt-get`, а не `apt`, так как у последней нестабильный интерфейс.
# `libpq-dev` — это зависимость `psycopg2` — пакета Python для работы с БД, который будет компилироваться при установке.
RUN <

Возможно, у некоторых читателей возник вопрос по поводу создания виртуального окружения в Docker-образе. Зачем что-то усложнять, если можно взять Docker-образ python:3.12 в качестве базового и установить все зависимости в директории системного интерпретатора?

Ниже перечислены преимущества виртуального окружения:

  • позволяет использовать разные базовые образы, так как нет конфликта с системными пакетами;

  • структура директорий в виртуальном окружении контейнера схожа со структурой директорий при локальной разработке, а единообразие упрощает восприятие и поддержку проектов.

Создаём Docker-образ:

docker buildx build --tag my_image:latest .

В этом разделе мы создали Docker-образ, но перед тем, как отправить его клиенту, хотелось бы дополнительно убедиться, что код соответствует принятым стандартам, и тесты успешно проходят. Рассмотрим, как это можно сделать на примере GitLab CI.

Проверка кода проекта хуками pre-commit и запуск тестов в GitLab CI

Для осуществления целей нам понадобится немного другой Docker-образ:

ci.Dockerfile

# syntax=docker/dockerfile:1
FROM ubuntu:noble AS final

ARG python_version=3.12

SHELL ["/bin/sh", "-exc"]

# Устанавливаем системные пакеты для сборки проекта и фреймворка pre-commit.
RUN <

В предыдущем Dockerfile нет копирования директории проекта. Контейнер будет получать доступ к коду через Docker-том (Docker volume) со сборками, который автоматически монтируется в GitLab CI. Это позволяет экономить место в Docker-реестре (Docker registry), так как мы не создаём дополнительный слой с кодом проекта.

Далее приведены примеры трёх GitLab CI job:

  1. build_docker_image-ci — собирает Docker-образ и загружает его в Docker-реестр.

build_docker_image-ci:
  image: docker
  variables:
    # https://docs.gitlab.com/runner/configuration/feature-flags.html
    FF_DISABLE_UMASK_FOR_DOCKER_EXECUTOR: 1
    DOCKER_IMAGE: $CI_PROJECT_PATH/ci
  script:
    # Аутентифицируемся в Docker-реестре.
    - echo -n $DOCKER_PASS | docker login --username $DOCKER_USER --password-stdin $DOCKER_REGISTRY
    # Создаём нового сборщика.
    - docker buildx create --name my_builder --driver docker-container --bootstrap --use
    # Создаём Docker-образ и загружаем его в реестр.
    - |
      docker buildx build \
        --file ci.Dockerfile \
        --cache-from type=registry,ref=$DOCKER_REGISTRY/$DOCKER_IMAGE:cache \
        --cache-to type=registry,ref=$DOCKER_REGISTRY/$DOCKER_IMAGE:cache,mode=max \
        --pull \
        --tag $DOCKER_REGISTRY/$DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA \
        --tag $DOCKER_REGISTRY/$DOCKER_IMAGE:latest \
        --push \
        .

Дополнительно нужно добавить периодическую задачу для удаления старых CI образов из реестра. Например, удалять все образы старше одного дня, кроме образов с тегами latest и cache.

  2. run_pre_commit_hooks — запускает pre-commit хуки.

run_pre_commit_hooks:
  image: $DOCKER_REGISTRY/$CI_PROJECT_PATH/ci:$CI_COMMIT_SHORT_SHA
  script:
    - uv tool run pre-commit run --all-files

  3. run_tests — запускает тесты.

run_tests:
  services:
    - name: postgres:15
      variables:
        POSTGRES_USER: my_user
        POSTGRES_PASSWORD: my_password
  image: $DOCKER_REGISTRY/$CI_PROJECT_PATH/ci:$CI_COMMIT_SHORT_SHA
  variables:
    # https://docs.gitlab.com/ee/ci/services/#connecting-services
    FF_NETWORK_PER_BUILD: 1
  script:
    # uv автоматически установит проект в "editable" режиме.
    - uv run --frozen pytest

Создание отдельного Docker-образа для GitLab CI позволяет упростить и ускорить задачи проверки кода. В этом варианте не нужно использовать GitLab CI кэширование и запускать дочерний Docker-контейнер из основного Docker-контейнера.

Вариант с Docker в Docker (Docker-in-Docker) мог бы выглядеть примерно так:

my_job:
  ...
  image: docker
  script:
    - |
      docker buildx build \
        --file ci.Dockerfile \
        --tag $DOCKER_IMAGE \
        .
    - container_id=$(docker ps --filter "label=com.gitlab.gitlab-runner.job.id=$CI_JOB_ID" --filter "label=com.gitlab.gitlab-runner.type=build" --quiet)
    - volume_name=$(docker inspect --format '{{ range .Mounts }}{{ if eq .Destination "/builds" }}{{ .Name }}{{end}}{{end}}' $container_id)
    - network_name=$(docker inspect --format '{{ range $network_name, $_ := .NetworkSettings.Networks }}{{ $network_name }}{{ end }}' $container_id)
    - |
      docker run \
        --mount type=volume,source=$volume_name,destination=/builds \
        --network $network_name \
        --workdir $CI_PROJECT_DIR \
        $DOCKER_IMAGE \
        my_command

Однако по моему опыту людям обычно сложнее понять что-то подобное.

Заключение

Мы рассмотрели один из вариантов использования связки uv и Docker для удобной локальной разработки и создания Docker-образа конечного продукта. В нашем случае один инструмент заменил сразу четыре: pip, pyenv, pipx и Poetry, а многоэтапная сборка позволила уменьшить размер Docker-образа в три раза в одном из проектов. Надеюсь, что в будущем пакетный менеджер uv продолжит развиваться, изменит ситуацию с Python-инструментами в лучшую сторону и не подведёт своих пользователей!

© Habrahabr.ru