Перейти к содержимому
СписокЗадачиПредложения1ОбсужденияАналитика

🧙 Садовник: уточнил шаги, добавил проверки и обоснования. Примите, если полезно.

#1
открыто+11−21предложил gardener · 4 авг. 2026 г. · на основе v1
ОбсуждениеПроверкиПредлагаемые изменения32Итог
Итог · станет v3
1
Проверить установку uv

Выполняй команду во встроенном терминале VS Code, находясь в папке будущего проекта. Если команда не найдена, сначала установи uv и заново открой терминал.

Зачем: Все последующие операции выполняются через uv, поэтому проблему с установкой лучше обнаружить сразу.
$uv --version
  • –Команда напечатала версию uv
  • –Терминал открыт в нужной папке
  • –После установки uv команда доступна в новом терминале
Установка uv
2
Создать пакетный проект

Точка в конце означает «в текущей папке». Флаг --package создаёт устанавливаемый проект с разделом [build-system], необходимым для собственных команд. После запуска проверь pyproject.toml, README.md, .python-version, .gitignore и папку src/ с пакетом.

Зачем: Точки входа из `[project.scripts]` работают после установки проекта как пакета, а не как простого набора скриптов.
$uv init --package .
  • –В папке появился pyproject.toml
  • –В pyproject.toml есть раздел [build-system]
  • –Появилась папка src с пакетом
Создание проектов uv
3
Закрепить Python 3.12

После команды открой .python-version: там должна быть строка 3.12. В pyproject.toml установи requires-python = ">=3.12"; это минимальная поддерживаемая версия, тогда как .python-version задаёт версию по умолчанию для работы с проектом.

Зачем: Явная версия по умолчанию уменьшает расхождения между локальными окружениями и не даёт случайно запустить проект на слишком старом Python.
$uv python pin 3.12
  • –Файл .python-version содержит 3.12
  • –В pyproject.toml указано requires-python = ">=3.12"
  • –Команда uv run python --version показывает Python 3.12
Версии Python в uv
4
Перенести пакеты в корень

Перенеси созданный пакет из src/<имя_проекта>/ в корневую папку app/, затем удали пустую src. Сразу создай папку scripts/ с пустым __init__.py и добавь перед [build-system] настройку сборщика:

toml
1[tool.hatch.build.targets.wheel]
2packages = ["app", "scripts"]
Зачем: После переноса сборщику нужно явно указать новые пути пакетов, иначе установка проекта завершится ошибкой или не включит нужный код.
  • –Папка app находится в корне проекта
  • –Папка scripts содержит __init__.py
  • –В настройках wheel перечислены app и scripts
Настройка сборки Hatch
5
Добавить рабочие зависимости

Команда добавит FastAPI и Uvicorn в dependencies, создаст или обновит uv.lock и синхронизирует .venv. Не копируй версии из примеров: проверь ограничения, которые uv записал для актуальных установленных выпусков.

Зачем: В `pyproject.toml` перечислены прямые требования проекта, а `uv.lock` фиксирует разрешённое дерево прямых и транзитивных зависимостей.
$uv add fastapi uvicorn
  • –В dependencies появились fastapi и uvicorn
  • –Созданы uv.lock и .venv
  • –Команда uv lock --check завершается успешно
Зависимости проектов uv
6
Проверить окружение проекта

Команда должна импортировать FastAPI из окружения проекта и напечатать его версию. Для сравнения можно выполнить ту же проверку без uv run, но результат будет зависеть от Python, который первым найден в PATH.

Зачем: `uv run` синхронизирует окружение проекта и запускает команду с его интерпретатором и зависимостями.
$uv run python -c "import fastapi; print(fastapi.__version__)"
  • –Команда напечатала версию fastapi
  • –uv run python --version соответствует закреплённой версии
  • –Импорт завершается без ModuleNotFoundError
Запуск команд через uv
7
Добавить Ruff для разработки

Флаг --dev помещает Ruff в группу [dependency-groups].dev, а не в основные dependencies. Проверь актуальное ограничение версии, которое uv записал в pyproject.toml.

Зачем: Отдельная группа не смешивает инструменты проверки кода с библиотеками, необходимыми приложению во время работы.
$uv add --dev ruff
  • –ruff находится в группе dev
  • –ruff отсутствует в основных dependencies
  • –Команда uv run ruff --version печатает версию
Документация Ruff
8
Создать и объявить команду lint

Создай scripts/commands.py:

python
1"""Команды проекта, объявленные в pyproject.toml."""
2
3import subprocess
4import sys
5
6
7def lint() -> None:
8 """Проверить код линтером."""
9 result = subprocess.run(["ruff", "check", "."], check=False)
10 sys.exit(result.returncode)

Затем добавь или обнови раздел:

toml
1[project.scripts]
2lint = "scripts.commands:lint"

Слева указано имя команды, справа — путь в формате модуль:функция.

Зачем: Проброс кода возврата через `sys.exit` позволяет терминалу и CI отличить успешную проверку от найденных ошибок.
  • –Создан файл scripts/commands.py
  • –В [project.scripts] объявлена команда lint
  • –Функция завершается кодом Ruff через sys.exit
Точки входа Python-проектов
9
Запустить команду lint

При первом запуске uv может переустановить сам проект в окружение — это нормально. Если появляется Failed to spawn: lint, проверь наличие [build-system], запись в [project.scripts] и включение scripts в настройки wheel.

Зачем: Этот запуск одновременно проверяет сборку пакета, установку точки входа и доступность Ruff в окружении разработки.
$uv run lint
  • –Команда запускается под именем lint
  • –Ruff печатает результат проверки
  • –При ошибках команда возвращает ненулевой код
10
Проверить путь импортируемой команды

Команда печатает файл, из которого Python действительно импортирует модуль. Ожидается путь к scripts/commands.py; рядом не должно быть одноимённых файла и папки, способных запутать импорт.

Зачем: Проверка обнаруживает затенение модулей, при котором Python выполняет не тот код, который разработчик редактирует.
$uv run python -c "import importlib.util as u; print(u.find_spec('scripts.commands').origin)"
  • –Напечатан путь к scripts/commands.py
  • –В scripts нет одноимённых файла и папки
  • –Путь относится к текущему проекту
11
Проверить файлы для коммита

Убедись, что .gitignore содержит .venv/, __pycache__/, *.py[cod] и .env, но не содержит uv.lock. В Git должны попасть pyproject.toml, uv.lock, .python-version, .gitignore, app/ и scripts/; если .venv уже отслеживается, удали её только из индекса командой git rm -r --cached .venv.

Зачем: Lock-файл обеспечивает воспроизводимость, а локальное окружение и секреты не должны раздувать репозиторий или попадать в его историю.
$git status --short && git check-ignore .venv
  • –git check-ignore подтверждает игнорирование .venv
  • –uv.lock и .python-version видны среди новых файлов
  • –В списке нет .env, __pycache__ и содержимого .venv
Документация gitignore