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

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

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

Пример кода до обработки:

def f ():
    return 2+3

Этот же код после автоматического форматирования:

def f():
    return 2 + 3

Так как black это инструмент для написания кода, то он должен устанавливаться как dev зависимость:

uv add --dev black

Следующим шагом его нужно запустить как обычную консольную утилиту. По документации видно, что имя утилиты (имя исполняемого файла) совпадает с именем пакета. Попробуем выполнить запуск:

black .

Запуск кода выше приведет к ошибке: command not found: black. Почему так происходит?

Локальная установка помещает содержимое пакета в директорию .venv текущего проекта. Командные оболочки, например Bash, при запуске утилит ищут их в специальных системных директориях, но они ничего не знают про утилиты, установленные в другие места системы, например, в наш проект. Чтобы решить эту проблему нужно запустить команду из окружения

uv run black .

Как вы увидите дальше, в реальных проектах на Python пакетов-программ достаточно много. И для запуска всех них из окружения нужна команда uv run.

Утилита или зависимость

Многие пакеты, используемые в разработке, поддерживают установку как в виде зависимости - uv add, так и в виде отдельной утилиты - uvx. Когда же какой способ применим? Если пакет требует для использования импортировать код приложения и другие зависимости, и в целом связан с проектом, то его нужно добавлять как зависимость. Например, pytest, библиотеке автотестирования для работы нужно импортировать и запускать тестируемый код, значит ее нужно ставить как зависимость. А, например, ruff, линтеру, для проверки кода не нужно проверяемый код запускать, и потому его можно использовать как утилиту.