К содержимому
Войти

Python Road Map

📁 Проект, зависимости и uv

У любого Python-сервиса на работе есть три файла рядом с кодом: pyproject.toml описывает проект и диапазоны зависимостей, uv.lock фиксирует точные версии всего дерева, а .venv хранит установленные пакеты отдельно от системного Python. Выпадет одно звено — и у коллеги и в проде окажутся другие версии библиотек, а с ними баг «у меня работает». На собеседовании спрашивают, зачем виртуальное окружение, чем lock-файл отличается от requirements.txt, почему uv, а не poetry, и как разложить сервис на FastAPI по слоям

🧠 Как это устроено

pyproject.toml как центр проекта

setup.py, setup.cfg, requirements-dev.txt, .flake8 и .isort.cfg сейчас заменяет один pyproject.toml:

  • [project] по PEP 621 — имя, версия, requires-python и dependencies. Этот раздел читают все современные инструменты: uv, poetry 2, pip, hatch
  • [build-system] — чем собирать пакет. uv init --package ставит свой бэкенд uv_build
  • [dependency-groups] по PEP 735 — зависимости для разработки: pytest, ruff, mypy. В собранный пакет они не попадают
  • [tool.*] — настройки инструментов: [tool.ruff], [tool.mypy], [tool.pytest.ini_options]

requires-python ограничивает резолвер. uv подбирает зависимости так, чтобы они подходили ко всем версиям из диапазона: при >=3.11 он не возьмёт версию библиотеки, которой нужен 3.12. Конкретную версию для локальной разработки задаёт файл .python-version

В uv группа dev особенная: uv add --dev pytest пишет её в [dependency-groups], и uv sync с uv run ставят её по умолчанию. --dev, --no-dev и --only-dev — сокращения для --group dev и соседей. Другие группы заводят явно: uv add --group lint ruff. Старое поле tool.uv.dev-dependencies ещё работает, но документация uv обещает его убрать

Что на самом деле лежит в .venv

Виртуальное окружение — каталог со своим site-packages и ссылкой на интерпретатор, который уже стоит в системе. Копии Python там нет. Вот что создал uv для проекта из примера ниже:

.venv/
├── pyvenv.cfg
├── bin/
│   ├── python -> /opt/homebrew/opt/python@3.13/bin/python3.13
│   ├── python3 -> python
│   ├── pytest, ruff, fastapi     # скрипты пакетов
│   └── activate, activate.fish, ...
└── lib/python3.13/site-packages/   # fastapi, pydantic, starlette...
home = /opt/homebrew/opt/python@3.13/bin
include-system-site-packages = false
version_info = 3.13.5

При старте интерпретатор ищет pyvenv.cfg рядом со своим бинарником или уровнем выше. Нашёл — значит, он в окружении: sys.prefix указывает на .venv, а sys.base_prefix на установку, откуда взят интерпретатор. Пути поиска пакетов строятся от sys.prefix, поэтому import fastapi находит пакет из .venv, а не из системы. include-system-site-packages = false отрезает системный site-packages целиком

$ uv run python -c "import sys; print(sys.prefix); print(sys.base_prefix)"
.../orders/.venv
/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13

Отсюда два следствия. Активировать окружение не обязательно: activate только дописывает .venv/bin в начало PATH, а .venv/bin/python app.py работает и без него. И переносить окружение нельзя: в shebang скриптов прописаны абсолютные пути. Его удаляют и создают заново, в git не кладут

Нужно оно потому, что двум сервисам на одной машине бывают нужны несовместимые версии одной библиотеки, а системный Python в Linux-дистрибутиве принадлежит ОС. Как Python ищет модули по sys.path, разобрано на странице про модули, пакеты и импорты

Диапазоны в pyproject и точные версии в lock-файле

В pyproject.toml пишут, с какими версиями проект совместим: fastapi>=0.162.4. Под такой диапазон сегодня подходит одна версия, через месяц другая. К тому же там только прямые зависимости: FastAPI сам тянет starlette, pydantic, anyio и ещё семь пакетов, и их версий в pyproject нет вообще

Lock-файл отвечает на другой вопрос: что именно ставить. В uv.lock записано всё дерево, включая транзитивные зависимости, и для каждого пакета указаны версия, источник, URL файла и его хеш:

[[package]]
name = "starlette"
version = "1.10.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "anyio" },
]
sdist = { url = "https://files.pythonhosted.org/.../starlette-1.10.0.tar.gz", hash = "sha256:b8399098d4c1...", size = 2734356 }
wheels = [
    { url = "https://files.pythonhosted.org/.../starlette-1.10.0-py3-none-any.whl", hash = "sha256:478c0ab3b4ce...", size = 80571 },
]

Хеш защищает от подмены: если файл в индексе или зеркале изменился, установка упадёт. uv.lock кроссплатформенный, в нём сразу колёса под Linux, macOS и Windows, поэтому lock, собранный на Mac, ставит те же версии в Linux-контейнере. Lock-файл сервиса коммитят в git. Потребителям библиотеки он не передаётся, им достаются диапазоны из [project]

🛠️ На практике

Проект на uv с нуля

uv от Astral написан на Rust и заменяет pip, pip-tools, pipx, virtualenv, pyenv и poetry одним бинарником. Прогон на uv 0.13.7 и Python 3.13.5, пути сокращены:

uv init --package orders --python 3.13
cd orders
uv add fastapi
uv add --dev pytest ruff
Creating virtual environment at: .venv
Resolved 12 packages in 1.09s
Installed 12 packages in 18ms
 + anyio==4.16.0
 + fastapi==0.162.4
 + pydantic==2.14.3
 + pydantic-core==2.50.4
 + starlette==1.10.0
 ...

uv init --package создал src-layout с src/orders/__init__.py, .python-version и git-репозиторий. Первый uv add сам завёл .venv, записал зависимость, построил uv.lock и поставил пакеты. В pyproject после этого:

[project]
name = "orders"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "fastapi>=0.162.4",
]

[dependency-groups]
dev = [
    "pytest>=9.2.0",
    "ruff>=0.17.4",
]

uv пишет нижнюю границу >= на текущую версию, точная живёт в lock-файле. Остальное на каждый день:

КомандаЧто делает
uv lockпересобирает uv.lock по pyproject, ничего не ставит
uv lock --upgrade-package fastapiподнимает одну зависимость, остальные версии не трогает
uv syncприводит .venv в точное соответствие с lock-файлом
uv run pytestпроверяет lock и окружение, при нужде обновляет их и запускает команду в .venv
uv exportвыгружает lock в requirements.txt с хешами или в pylock.toml по PEP 751

uv sync точный по умолчанию: всё, чего нет в lock-файле, он удаляет. Поставил руками uv pip install six — следующий uv sync пишет - six==1.17.0. uv sync --no-dev снёс pytest, ruff и их зависимости, всего 6 пакетов: так ставят в проде

--locked против --frozen

Оба флага не дают uv переписать lock-файл, но проверяют разное. Добавил в pyproject httpx руками и не запустил uv lock:

$ uv sync --locked
Resolved 23 packages in 998ms
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.

$ uv sync --frozen
Installed 1 package in 2ms
$ uv run --frozen python -c "import httpx"
ModuleNotFoundError: No module named 'httpx'

--locked сверяет lock с pyproject и падает, если они разошлись. --frozen в pyproject не смотрит: ставит записанное в lock и молча пропускает новую зависимость. В CI нужен --locked, он ловит коммит, где поменяли pyproject и забыли lock. --frozen уместен, когда сверка уже прошла на предыдущем шаге. Как uv sync встраивают в Dockerfile, разобрано на странице про Python в контейнере

uvx, uv tool и uv python

uvx ruff check . (полное имя uv tool run) запускает утилиту во временном окружении из кэша uv, не трогая проект. uv tool install ruff ставит её насовсем в отдельное окружение и кладёт бинарник в PATH, как pipx

uv python install 3.13 скачивает сборку CPython из проекта python-build-standalone: официальных переносимых бинарников у Python нет. Заранее ставить не обязательно, недостающую версию uv скачает сам. Это задача pyenv

pip, poetry и uv

pip + requirements.txtpoetryuv
Описание проектаrequirements.txt, часто без pyproject.tomlpyproject.toml, с версии 2.0 в стандартном [project]pyproject.toml, [project]
Lock-файлнет. Его роль играет pip freeze или pip-compile с хешамиpoetry.lockuv.lock, кроссплатформенный
Окружениесоздаёшь сам через python -m venvсоздаёт самсоздаёт сам в .venv
Dev-зависимостиотдельный файл requirements-dev.txt[tool.poetry.group.*] или PEP 735PEP 735, группа dev по умолчанию
Версии Pythonнет, нужен pyenvнет, нужен pyenvuv python install
Утилиты вроде ruffpipxнетuvx, uv tool
Скоростьбазоваясопоставима с pipпо документации uv в 10–100 раз быстрее pip

Ruff, pre-commit и mypy в CI

Ruff заменяет flake8 с плагинами, isort, pyupgrade и black: в нём больше 900 правил, а форматтер на больших проектах вроде Django совпадает с black больше чем в 99,9% строк. Правила включают кодами в pyproject:

[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"]   # pycodestyle, pyflakes, isort, bugbear, pyupgrade

На файле с import sys и import os, json, где нужен только json, ruff check нашёл 4 ошибки: I001 (импорты не отсортированы), E401 (два импорта в строке) и два F401 (импорт не используется), и все исправил через --fix. Форматтер импорты не сортирует, это правило линтера I. Поэтому сначала ruff check --fix, потом ruff format

pre-commit запускает то же самое перед каждым коммитом:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.17.4
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format        # после линтера: фиксы могут сломать форматирование
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.13.7
    hooks:
      - id: uv-lock            # пересобирает uv.lock, если поменялся pyproject

Хук пропускается через git commit --no-verify, поэтому в CI те же проверки повторяют: uv sync --locked, затем uv run ruff check ., uv run ruff format --check ., uv run mypy src и uv run pytest. ruff format --check ничего не меняет и возвращает код 1, если файл надо переформатировать. Что ловит mypy и как включать strict постепенно, разобрано на странице про аннотации типов и mypy

Структура сервиса: src-layout и слои

Flat layout кладёт пакет в корень репозитория рядом с pyproject.toml, src-layout прячет его в src/. Python ставит текущий каталог первым в путь поиска модулей, поэтому при flat layout import orders из корня берёт исходники напрямую, даже если пакет не установлен или собирается без части файлов. Тесты зелёные, а собранный пакет падает на ModuleNotFoundError. В src-layout импорт работает только после установки, и тесты проверяют то, что поедет в прод. uv ставит проект как editable: в site-packages лежит orders.pth со строкой .../orders/src, и правки видны без переустановки

Цена в том, что без установки проект не запустить: python src/orders/main.py упадёт на импортах, нужен uv run. Flat оправдан для скрипта или учебного проекта

Внутри пакета сервис на FastAPI обычно режут на три слоя:

orders/
├── pyproject.toml
├── uv.lock
├── .python-version
├── src/orders/
│   ├── main.py              # create_app: lifespan, middleware, include_router
│   ├── api/
│   │   ├── deps.py          # Depends: сессия БД, текущий пользователь
│   │   └── orders.py        # роутер: HTTP-запрос → схема → сервис
│   ├── schemas/order.py     # Pydantic-модели запросов и ответов
│   ├── services/orders.py   # бизнес-правила, транзакция
│   ├── repositories/orders.py  # запросы через SQLAlchemy
│   └── models/order.py      # ORM-модели
└── tests/
  • Роутер знает про HTTP: схема запроса, вызов сервиса, статус ответа. Бизнес-логики и SQL в нём нет
  • Сервис держит правила вроде «заказ нельзя отменить после отгрузки» и ничего не импортирует из FastAPI, поэтому его зовут и из воркера очереди
  • Репозиторий прячет SQL за get(order_id) и add(order). Сервис получает его через конструктор, в тесте его легко подменить
# api/orders.py
@router.post("/orders/{order_id}/cancel", response_model=OrderOut)
async def cancel(order_id: int, service: Annotated[OrderService, Depends(get_order_service)]):
    try:
        return await service.cancel(order_id)
    except OrderAlreadyShipped:
        raise HTTPException(status.HTTP_409_CONFLICT, "Заказ уже отгружен")

# services/orders.py
class OrderService:
    def __init__(self, repo: OrderRepository) -> None:
        self.repo = repo

    async def cancel(self, order_id: int) -> Order:
        order = await self.repo.get(order_id)
        if order.status == "shipped":
            raise OrderAlreadyShipped(order_id)
        order.status = "cancelled"
        return order

Раскладка по слоям хороша, пока фич немного. Когда их десяток, режут по доменам: orders/router.py, orders/service.py, orders/repository.py, рядом payments/. Сборка зависимостей через Depends разобрана на странице про FastAPI, сессии и транзакции на странице про SQLAlchemy

⚠️ Где ошибаются

Не коммитят lock-файл. В проде ставятся версии, свежие на день сборки. Выходит минорный релиз транзитивной зависимости с другим поведением, и сервис ломается без единой строки нового кода

Ставят в CI с --frozen вместо --locked. Забытый uv lock после правки pyproject не ловится: сборка зелёная, а новой зависимости в образе нет, и сервис падает на импорте уже после деплоя

Ставят пакеты в системный Python. sudo pip install в Linux перезаписывает пакеты, от которых зависят утилиты ОС, поэтому свежие Debian и Ubuntu отвечают externally-managed-environment и не ставят. Нужно окружение, а для утилит uv tool install

Кладут .venv в git или копируют между машинами. В окружении абсолютные пути и колёса под конкретную ОС и архитектуру, скопированное с Mac на Linux оно не заработает. Переносят lock-файл, окружение пересоздают через uv sync

Бизнес-логика в роутере. SQL и проверки прямо в эндпоинте работают, пока ту же операцию не понадобится вызвать из консьюмера Kafka или крона. Логику копируют, и копии расходятся

🎯 Вопросы с собеседований

Зачем виртуальное окружение и как оно устроено

Чтобы у каждого проекта был свой набор пакетов, не конфликтующий с другими проектами и с системным Python, который нужен ОС. Внутри это каталог с pyvenv.cfg, ссылкой на базовый интерпретатор в bin/ и своим site-packages. Интерпретатор при старте находит pyvenv.cfg рядом с собой и ставит sys.prefix на окружение, а sys.base_prefix оставляет на базовой установке, и пакеты ищутся от sys.prefix. Активация только меняет PATH. Переносить окружение нельзя, в нём абсолютные пути

requirements.txt против pyproject.toml и lock-файла

pyproject.toml описывает проект и диапазоны прямых зависимостей, с которыми он совместим: это стандарт PEP 621, его читают все современные инструменты. Lock-файл фиксирует точные версии всего дерева, включая транзитивные, с хешами файлов, и отвечает на вопрос «что именно ставить». requirements.txt — формат pip, в нём бывает что угодно: от списка диапазонов до полной заморозки с хешами из pip-compile, а после pip freeze там смешаны прямые, транзитивные и случайные пакеты. Сейчас его чаще генерируют из lock-файла через uv export для систем, которые понимают только pip

uv или poetry: чем отличаются

Оба ведут проект через pyproject.toml, сами создают окружение и пишут lock-файл, а poetry с версии 2.0 тоже пишет зависимости в стандартный [project]. Разница в скорости и охвате: uv написан на Rust, ставит пакеты параллельно из глобального кэша и заодно заменяет pyenv (uv python install) и pipx (uvx). У poetry зрелее публикация пакетов и экосистема плагинов

Как зафиксировать версии, чтобы в проде стояло то же, что у тебя локально

Коммитить lock-файл и ставить строго из него: uv sync --locked --no-dev. --locked упадёт, если lock разошёлся с pyproject, тогда как --frozen молча поставил бы старый набор. --no-dev не потащит в прод pytest и ruff. Версию Python фиксируют в .python-version и в базовом образе. Хеши в lock-файле гарантируют те же файлы, а не только те же номера версий. Обновляют зависимости отдельным коммитом через uv lock --upgrade-package имя с прогоном тестов

Как бы ты структурировал сервис на FastAPI

Три слоя. Роутер отвечает за HTTP: разбирает запрос в Pydantic-схему, зовёт сервис и превращает результат и доменные исключения в ответ со статусом. Сервис держит бизнес-правила и не знает про FastAPI, поэтому его вызывают из воркера и тестируют без HTTP. Репозиторий прячет SQL за методами вроде get и add, сервис получает его через конструктор, а собирается всё через Depends. Отдельно лежат схемы, ORM-модели и main.py с lifespan. В маленьком сервисе каталоги по слоям, в большом по доменам

Зачем src-layout

Чтобы тесты проверяли установленный пакет, а не исходники из текущего каталога. Python ставит текущую директорию первой в путь поиска, и при flat layout import orders из корня находит код напрямую, даже если пакет собирается без части файлов: тесты проходят, а в проде ModuleNotFoundError. В src-layout импорт работает только после установки, и лишние файлы корня в путь не попадают. Цена в том, что без установки проект не запустить, но uv и так ставит его как editable

📚 Что почитать