Экосистема Python традиционно полагалась на инструменты типа pip и virtualenv для управления зависимостями и окружениями проекта. Хотя эти инструменты хорошо нам служили, они часто приводят к конфликтам зависимостей, ручному управлению окружением и несогласованным настройкам проектов в командах.
Python Poetry решает эти проблемы, предоставляя современный, унифицированный инструмент управления зависимостями и окружениями. Он заботится обо всем, начиная от виртуальных сред до публикации пакетов, все это обеспечивая воспроизводимые сборки благодаря интеллектуальному разрешению зависимостей.
Это руководство покажет вам, как использовать Poetry для оптимизации вашего рабочего процесса разработки на Python и избежать распространенных проблем с зависимостями.
Python Poetry против PIP
Poetry и pip выполняют разные функции в экосистеме Python. В то время как pip в основном является инструментом для установки пакетов, Poetry – это полноценный инструмент управления зависимостями и проектами. Вот основные различия:
1. Разрешение зависимостей
- Pip: Простое линейное разрешение зависимостей, которое может привести к конфликтам
- Поэзия: Расширенный средство разрешения зависимостей, предотвращающее конфликты перед установкой
2. Управление виртуальной средой
- PIP: Требует отдельных инструментов (virtualenv, venv) и ручной активации
- Поэзия: Автоматически создает и управляет виртуальными средами для каждого проекта
3. Конфигурация проекта
- PIP: Использует requirements.txt для зависимостей, setup.py для метаданных проекта
- Поэзия: Один файл pyproject.toml для всех конфигурационных потребностей
4. Файлы блокировки
- Pip: Нет встроенной поддержки файлов блокировки
- Poetry: Генерирует poetry.lock для воспроизводимых сборок в различных средах
5. Публикация пакетов
- Pip: Требуется дополнительные инструменты (twine, setuptools) для публикации
- Poetry: Встроенные команды для сборки и публикации пакетов
Когда использовать Poetry вместо pip
Выбирайте Poetry, когда:
- Работаете над командными проектами, требующими воспроизводимых сред
- Создаете пакеты, которые будут опубликованы на PyPI
- Управляете сложными деревьями зависимостей с потенциальными конфликтами
- Нужно автоматизированное управление виртуальными средами
- Хотите использовать один инструмент для всего рабочего процесса разработки
Используйте pip, когда:
- Работа с простыми скриптами с минимальными зависимостями
- Изучение Python впервые
- Необходимо быстро установить один пакет
- Работа в средах, где невозможна установка Poetry
- Поддержка устаревших проектов, которые уже настроены с помощью pip
Общее правило: использовать Poetry для любого проекта, который будет распространен, развернут или поддерживаться в долгосрочной перспективе. Используйте pip для быстрых экспериментов или учебных упражнений.
С этим сказанным, давайте приступим к использованию Poetry.
Настройка Python Poetry
Вы будете в основном взаимодействовать с Poetry как с инструментом командной строки (CLI), поэтому имеет смысл установить его системно на вашем компьютере. Этот раздел охватывает этот важный первый шаг и как настроить некоторые параметры по умолчанию для Poetry в соответствии с вашими потребностями.
Установка Poetry
Вы можете установить Poetry, используя официальный скрипт установщика, который можно загрузить и запустить одной командой.
Для macOS, Linux и WSL2:
$ curl -sSL https://install.python-poetry.org | sudo python3 -
Для Windows Powershell (запустите с правами администратора):
$ (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
Если у вас установлен Python из Магазина Microsoft (по какой-то странной причине) на Windows, замените py на python в указанной выше команде.
После завершения установки скрипт выводит сообщение с просьбой добавить Poetry в ваш PATH, чтобы команда poetry была доступна везде.
Для macOS, Linux и WSL2 добавьте следующую строку в ваш скрипт оболочки, такой как .bashrc или .zshrc:
$ export PATH="/Users/bexgboost/.local/bin:$PATH"
Для Windows вы можете следовать инструкциям по выводу.
После этого проверьте вашу установку, запустив poetry --version.
Настройка Poetry
Большая часть конфигурации Poetry связана с созданием виртуальных окружений и установкой пакетов. Вы можете вывести (почти) полный список конфигураций Poetry с помощью:
$ poetry config --list
Вывод будет выглядеть примерно так:
cache-dir = "/Users/bexgboost/Library/Caches/pypoetry" experimental.system-git-client = false installer.max-workers = null installer.modern-installation = true installer.no-binary = null installer.parallel = true keyring.enabled = true solver.lazy-wheel = true virtualenvs.create = true virtualenvs.in-project = null virtualenvs.options.always-copy = false virtualenvs.options.no-pip = false virtualenvs.options.no-setuptools = false virtualenvs.options.system-site-packages = false virtualenvs.path = "{cache-dir}/virtualenvs" # /Users/bexgboost/Library/Caches/pypoetry/virtualenvs virtualenvs.prefer-active-python = false virtualenvs.prompt = "{project_name}-py{python_version}" warnings.export = true
На первой строке мы видим путь к кэшу Poetry. Он используется в основном для хранения загруженных пакетов и виртуальных сред. Любые виртуальные окружения, которые вы создаете, хранятся здесь по умолчанию. Если вы хотите изменить это, вы можете выполнить следующую команду:
$ poetry config virtualenvs.path path/to/new/virtualenv/dir
Еще одним важным параметром конфигурации является количество ядер, используемых во время установки. По умолчанию установлено четыре ядра, но мы можем ускорить процесс, используя все ядра ЦП. Сначала определите количество ядер вашего устройства, запустив os.cpu_count() в интерпретаторе Python. Затем установите вывод:
$ poetry config installer.max-workers = 10
Один из необязательных параметров – это создание виртуальных сред в вашем рабочем каталоге или кэше. Это управляется с помощью опции virtualenvs.in-project. Если установлено значение True, .venv каталог всегда будет создаваться в вашем рабочем каталоге:
$ poetry config virtualenvs.in-project true
Создание нового проекта с помощью Poetry
Давайте рассмотрим основные шаги создания нового проекта с использованием Poetry и понимания его основного файла конфигурации.
Инициализация нового проекта Poetry
Использование Poetry обычно начинается с создания нового проекта с помощью poetry new команды:
$ poetry new explore-poetry $ cd explore-poetry
Команда создает каталог explore-poetry, предварительно заполненный следующими файлами и каталогами:
explore-poetry ├── pyproject.toml ├── README.md ├── explore-poetry │ └── __init__.py └── tests └── __init__.py
Эта структура каталогов соответствует лучшим практикам Python:
pyproject.toml: Основной конфигурационный файл, определяющий метаданные проекта и зависимостиREADME.md: Файл документации, объясняющий проектexplore-poetry/: Каталог исходного кода, содержащий основной код пакета, с__init__.pyдля превращения его в пакетtests/: Директория для тестовых файлов, с__init__.pyдля того, чтобы сделать его пакетом (импортируемым)
Понимание файла pyproject.toml
Здесь файл pyproject.toml требует тщательного внимания, так как это единственный непустой файл, созданный Poetry:
[tool.poetry] name = "explore-poetry" version = "0.1.0" description = "" authors = ["BexTuychiev <[email protected]>"] readme = "README.md" [tool.poetry.dependencies] python = "^3.8" [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api"
Этот файл оркестрирует ваш проект и его зависимости. Он использует Tom’s Obvious, Minimal Language, который был принят в качестве стандартного языка конфигурации для пакетов Python в PEP 518.
Все pyproject.toml файлы разделены на разделы, называемые таблицами с использованием скобок, например tool.poetry или build-system. Poetry использует эти таблицы для управления зависимостями, требованиями к сборке проекта или выполнения других задач.
При выполнении команд Poetry, описанных в следующих разделах, файл pyproject.toml будет автоматически обновлен.
Работа с виртуальными средами в Poetry
В этом разделе вы узнаете о тонкостях управления виртуальными средами в Poetry после ее настройки. Вы узнаете, почему виртуальные среды важны, как Poetry автоматически управляет ими, а также основные команды для их управления, такие как создание, активация и переключение. Вы также узнаете, как управлять версиями Python с помощью Poetry.
Создание и активация виртуальной среды
Когда вы устанавливаете Poetry впервые, в нем нет встроенных сред, как видно из пустого вывода при запускеpoetry env list:
$ poetry env list # нет вывода
Но как только вы начнете добавлять зависимости (об этом позже) с помощью poetry add package-name, он автоматически создает среду в каталоге кэша для проекта. Например, давайте попробуем добавить requests в качестве зависимости:
$ poetry add requests
Вы должны получить вывод, аналогичный следующему:
Creating virtualenv explore-poetry--I9GJYUn-py3.8 in /Users/bexgboost/Library/Caches/pypoetry/virtualenvs Using version ^2.32.3 for requests Updating dependencies Resolving dependencies... (2.5s) Package operations: 5 installs, 0 updates, 0 removals - Installing certifi (2024.8.30) - Installing charset-normalizer (3.4.0) - Installing idna (3.10) - Installing urllib3 (2.2.3) - Installing requests (2.32.3) Writing lock file
Первая строка указывает, что поэзия создала окружение в кеше. Следующие строки информируют, что зависимости для requests успешно разрешены, и создан файл блокировки (о нем поговорим позже).
Обратите внимание на имя окружения: explore-poetry--I9GJYUn-py3.8. Имя включает имя каталога проекта, за которым следует уникальный идентификатор, а затем версия Python, которую использует это окружение.
В следующий раз, когда вы добавляете зависимость, Poetry автоматически использует это окружение для установки пакетов:
$ poetry add beautifulsoup4 Using version ^4.12.3 for beautifulsoup4 Updating dependencies Resolving dependencies... (1.1s) Package operations: 2 installs, 0 updates, 0 removals - Installing soupsieve (2.6) - Installing beautifulsoup4 (4.12.3) Writing lock file
Когда вы используете Poetry, ваш терминал не показывает, какое виртуальное окружение Poetry активно. Чтобы увидеть эту информацию, вам нужно выполнить poetry env list:
$ poetry env list explore-poetry--I9GJYUn-py3.8 (Activated)
Для взаимодействия с активным окружением Poetry вы можете выполнить poetry shell:
$ poetry shell
Команда открывает новую оболочку внутри текущей, и вы можете выполнять команды, такие как python или pytest.
Например, для выполнения скриптов на Python:
$ poetry shell $ python script.py
Для запуска фреймворков разработки, таких как Streamlit:
# Внутри оболочки $ streamlit run app.py
После этого вы можете выйти из оболочки, вызвав exit.
Кроме того, вы можете выполнять команды в оболочке Poetry, не заходя в нее, с помощью poetry run:
$ poetry run python script.py $ poetry run streamlit run app.py
Настройка версии Python
Когда вы запускаете poetry add или poetry install, Poetry автоматически использует версию Python, указанную в вашем файле pyproject.toml. Чтобы указать другую версию Python, вы можете выполнить команду env use:
$ poetry env use python3.11
Обратите внимание, что для работы команды необходимо установить Python 3.11 системно на вашем компьютере.
Проверьте, что Poetry использует среду с новой версией Python:
$ poetry env list explore-poetry--I9GJYUn-py3.11 (Activated) explore-poetry--I9GJYUn-py3.8
Обратите внимание, как новая среда автоматически привязывается к нашему проекту (идентификаторы остаются теми же). После настройки версии Python вы можете удалить среды с другими версиями, чтобы освободить дисковое пространство:
$ poetry env remove python3.8
При удалении среды вам нужно указать только версию Python. Вы также можете удалить все среды и начать с чистого листа:
$ poetry env remove --all
Обратите внимание, что тег --all удаляет все среды, связанные с текущим проектом, а не среды других проектов.
Если вы работаете над командными проектами, часто лучше держать виртуальную среду в каталоге проекта:
$ poetry config virtualenvs.in-project true
Эта команда не будет иметь никакого эффекта, если у вас уже есть среда для проекта в кэше. Чтобы создать локальную среду, сначала удалите все существующие из кэша.
Это создает папку .venv в вашем рабочем каталоге, которую вы должны добавить в свой .gitignore файл.
Управление зависимостями с помощью Poetry
Управление зависимостями – это то, в чем сильна Poetry. Он предоставляет полный спектр функций для указания, установки и управления зависимостями, чтобы вы никогда не столкнулись с адскими конфликтами зависимостей.
В этом разделе вы узнаете о добавлении и установке зависимостей, создании групп зависимостей, синтаксисе спецификации зависимостей в pyproject.toml и файлах блокировки.
Добавление зависимостей в Poetry
При использовании Poetry вы будете использовать poetry add package-name команду для установки пакетов из PyPI вместо pip install. Это имеет несколько преимуществ:
- Автоматически добавляет пакет в
pyproject.tomlс правильным ограничением версии - Обновляет файл блокировки для обеспечения воспроизводимости сборок
- Разрешает зависимости для избежания конфликтов
- Устанавливает пакет и все его зависимости в виртуальное окружение
Например, давайте сначала добавим Numpy в качестве зависимости:
$ poetry add numpy
Сразу же вы должны получить сообщение об ошибке разрешения зависимостей, которое говорит о том, что версия Numpy, которая устанавливается, несовместима с вашей версией Python. Причина в том, что при переходе в среду Python 3.11 мы не обновили pyproject.toml файл. Сейчас он выглядит так:
[tool.poetry.dependencies] python = "^3.8" requests = "^2.32.3" beautifulsoup4 = "^4.12.3"
Символ каретки ^ используется для указания, что наш explore-poetry проект совместим со всеми версиями Python до Python 4, но диапазон версий Numpy поддерживает только версии Python между 3.8 и 3.12, что представляет собой более узкий диапазон. Конфликт ошибки происходит от этого факта.
Итак, чтобы исправить ошибку, вам следует обновить диапазон версий Python на следующий:
python = ">=3.8, <3.12"
После внесения этого изменения, poetry add numpy команда должна работать ожидаемым образом.
Вы только что заметили одну из лучших особенностей Poetry – обнаружение конфликтов версий перед установкой каких-либо пакетов, вместо информирования вас об несовместимостях версий после этого, как это делает pip.
Синтаксис для указания версий зависимостей
Поэзия использует мощный синтаксис для указания широкого спектра версий для наилучшей синхронизации между зависимостями. Вот наиболее часто используемые символы:
- Каретка (^): Позволяет обновления патчей и минорных версий, но не мажорных. Пример:
^1.2.3позволяет обновления с 1.2.3 до 1.9.9, но не до 2.0.0. - Тильда (~): Позволяет только обновления патчей. Пример:
~1.2.3позволяет обновления с 1.2.3 до 1.2.9, но не до 1.3.0. - Точная версия: Указывает точный номер версии. Пример:
1.2.3разрешает только версию 1.2.3 - Больше чем (>): Позволяет любую версию выше указанной. Пример:
>1.2.3разрешает 1.2.4, 1.3.0, 2.0.0 и т. д. - Менее чем (<): Позволяет использовать любую версию ниже указанной. Пример:
<2.0.0позволяет использовать любую версию ниже 2.0.0. - Больше или равно (>=): Позволяет использовать указанную версию и выше. Пример:
>=1.2.3позволяет использовать версию 1.2.3 и любую более новую версию. - Меньше или равно (<=): Позволяет указанную версию и ниже. Пример:
<=2.0.0позволяет версию 2.0.0 и любую более низкую версию. - Диапазон версий: Сочетает ограничения с помощью запятых. Пример:
>=1.2.3,<2.0.0позволяет версии с 1.2.3 по 1.9.9. - Маска (*): Соответствует любой версии. Пример:
1.2.*соответствует любой версии, начинающейся с 1.2
Конечно же, вы можете комбинировать их по своему усмотрению.
Создание групп зависимостей в Poetry
В сложных проектах с большим количеством подвижных компонентов часто имеют дело с различными категориями зависимостей.
Например, в проекте машинного обучения часто создаются различные конвейеры и компоненты для загрузки данных, их очистки, создания признаков, обучения модели, развертывания и мониторинга. Не говоря уже о необходимости завершить документацию и запустить тесты. Все эти шаги имеют свои средства, и смешивание их зависимостей раздувает ваш финальный дистрибутивный пакет.
С помощью Poetry вы можете создавать группы зависимостей с произвольными именами, чтобы устанавливать их только при необходимости. Или самое лучшее — пользователи вашего пакета также могут выбирать, какие части им устанавливать.
$ poetry add --group ui streamlit plotly dash $ poetry add --group dev black flake8 isort mypy pylint
Вышеприведенные команды создают две группы зависимостей, ui и dev (если они еще не существуют), а также две подтаблицы в pyproject.toml:
[tool.poetry.dependencies] python = "^3.11" requests = "^2.32.3" beautifulsoup4 = "^4.12.3" numpy = "^2.1.3" [tool.poetry.group.ui.dependencies] streamlit = "^1.39.0" plotly = "^5.24.1" dash = "^2.18.2" [tool.poetry.group.dev.dependencies] black = "^24.10.0" flake8 = "^7.1.1" isort = "^5.13.2" mypy = "^1.13.0" pylint = "^3.3.1"
Несмотря на то, что группы зависимостей разделены, они все равно разрешаются друг против друга. Другими словами, если есть dev зависимость, конфликтующая с пакетом в ui, Poetry не выполнит установку.
В некоторых случаях вы можете создать группы необязательных зависимостей или сделать существующие группы необязательными, чтобы они не устанавливались по умолчанию при повторном создании среды вашего проекта. Для этого вам необходимо создать новую подтаблицу в файле pyproject.toml. Например, мы сделаем группу ui необязательной:
[tool.poetry.group.ui] optional = true [tool.poetry.group.ui.dependencies] streamlit = "^1.39.0" plotly = "^5.24.1" dash = "^2.18.2"
Это делается путем установки опционального параметра в true перед объявлением зависимостей группы.
Воспроизведение проекта Poetry с файлом poetry.lock
Если кто-то клонирует ваш репозиторий GitHub, содержащий проект Poetry, они могут создать идеальную копию виртуальной среды для вашего проекта, запустив одну команду: poetry install.
Команда install использует более полный poetry.lock файл. В отличие от pyproject.toml, в файле блокировки перечислены:
- Точные версии основных зависимостей перечислены в pyproject.toml
- Точные версии зависимостей основных зависимостей (транзитивные зависимости)
Например, requests зависит от urllib3, certifi, charset-normalizer и idna. Без файла блокировки эти суб-зависимости могут быть разрешены на разные версии на разных машинах.
Файл блокировки гарантирует, что все участники вашей команды используют одинаковые версии зависимостей, предотвращая проблему “на моей машине все работает”.
Разница между poetry add и poetry install
Мы объясним разницу между add и install командами в Poetry на примере использования.
Предположим, вы работаете над проектом по обнаружению мошенничества. Вы добавляете начальные зависимости:
$ poetry add pandas scikit-learn
Это добавляет пакеты в файлы блокировки и pyproject.toml. Затем ваш коллега клонирует репозиторий:
$ git clone fraud-detection-repo-link $ cd fraud-detection $ poetry install
Они запускают команду install для установки всего, что перечислено в файле блокировки.
Позже вам нужно добавить новый пакет:
$ poetry add xgboost
Ваш коллега забирает изменения:
$ git pull $ poetry install
Они запускают install команду для установки нового пакета. Так что,
- Используйте
poetryadd при добавлении новых зависимостей - Используйте
poetry install, когда вам нужно настроить существующий проект - Всегда фиксируйте
pyproject.tomlиpoetry.lockв системе контроля версий
Установка групп зависимостей с помощью команды poetry install
Ранее мы узнали, как группировать зависимости в Poetry. Когда вы запускаете poetry install, он устанавливает все невыбранные группы по умолчанию, что может быть не то, что вам нужно во всех случаях.
Например, вы можете клонировать репозиторий только для работы над документацией. Или вы хотите работать над основным кодом репозитория, за исключением аспектов документации и тестирования. Команда install достаточно гибкая, чтобы охватить все эти случаи:
Исключение определенных групп:
$ poetry install --without ui,dev
Установка дополнительных групп:
# Установка дополнительной документации $ poetry install --with docs
Установка только определенных групп:
$ poetry install --only ui
Установка только зависимостей времени выполнения проекта (зависимости, упомянутые вне групп, добавленные с помощью простых poetry add package команд):
$ poetry install --only main
Удаление зависимостей в Poetry
Удаление зависимости просто с помощью remove команды:
$ poetry remove requests
Это удаляет requests из основных зависимостей проекта. Чтобы удалить пакет из групповой зависимости, вы можете снова использовать тег --group:
$ poetry remove streamlit --group ui
Команда remove чисто удаляет пакет вместе с его транзитивными зависимостями.
Публикация проекта с помощью Poetry на PyPI
Если ваш проект готов к распространению, его публикация на PyPI (Python Package Index) позволяет другим разработчикам легко устанавливать и использовать ваш код через pip. Poetry делает этот процесс легким с помощью всего двух команд:
$ poetry build # Построить дистрибутивы $ poetry publish # Опубликовать на PyPI
Однако, прежде чем запустить эти команды, вам следует правильно настроить ваши учетные данные PyPI. Сначала создайте свои учетные записи на:
Настройте Poetry с вашими учетными данными:
$ poetry config pypi-token.pypi your-pypi-token $ poetry config pypi-token.testpypi your-test-pypi-token
Теперь сначала протестируйте свой пакет:
# Настройте репозиторий TestPyPI $ poetry config repositories.testpypi https://test.pypi.org/legacy/ # Опубликуйте на TestPyPI $ poetry build $ poetry publish -r testpypi
После публикации на TestPyPI вы можете попробовать установить свой пакет, чтобы проверить, что все работает хорошо:
$ pip install --index-url https://test.pypi.org/simple/ your-package-name
Если все в порядке, вы можете опубликовать его на самом PyPI:
$ poetry publish
Лучшие практики при работе с Poetry
Существует много подводных камней и лучших практик при использовании Poetry, и, конечно же, мы не можем упомянуть их все в одной статье. Но вот несколько распространенных, которые можно применить прямо сейчас:
- Всегда используйте виртуальные окружения – Poetry создает их автоматически для каждого проекта
- Держите ваш
pyproject.tomlфайл в системе контроля версий, исключитеpoetry.lockдля библиотек - Включите
poetry.lockв систему контроля версий для приложений, чтобы обеспечить воспроизводимость сборок - Используйте семантическое версионирование для версий вашего пакета (major.minor.patch). Вы можете использовать
команды poetry version patch/minor/majorдля увеличения версий пакета на один. Например,команда poetry version majorизменяет 0.2.0 на 1.0.0 в вашем файлеpyproject.toml. - Тщательно укажите ограничения версий зависимостей, чтобы избежать конфликтов
- Регулярно обновляйте зависимости с помощью
поэзия обновление, но тщательно тестируйте после обновлений - Используйте
поэзия добавить --group devдля разработочных зависимостей, чтобы держать их отдельно - Документировать все цели зависимостей в pyproject.toml с использованием комментариев
- Запустите
poetry checkперед коммитами для проверки синтаксиса pyproject.toml. Также можно рассмотреть хуки pre-commit. - Используйте
poetry exportдля созданияrequirements.txt, когда это необходимо для других инструментов. - Держите минимальный набор продуктовых зависимостей – перемещайте дополнительные функции в дополнения
- Проверьте установку вашего пакета в чистой среде перед публикацией
- Используйте TestPyPI перед публикацией в основной репозиторий PyPI
- Ведите четкий
CHANGELOG.mdдля отслеживания изменений версий - Используйте
poetry runдля выполнения скриптов для обеспечения правильного использования среды
Заключение и следующие шаги
Поэзия революционизировала управление зависимостями Python, предоставив надежное, интуитивно понятное решение для решения общих проблем управления пакетами. Его мощные функции для разрешения зависимостей, управления виртуальной средой и публикации проектов делают его бесценным инструментом для современной разработки на Python.
Для продолжения вашего пути развития на Python рассмотрите изучение следующих комплексных образовательных программ:
- Трек по программированию на Python — Освоение основ Python и продвинутых концепций
- Промежуточный Python— Улучшите свои навыки Python
- Основы данных в Python— Изучите основные навыки манипулирования данными
- Ассоциированный специалист по данным на Python— Погружение в науку о данных с помощью Python
Помните, эффективное управление зависимостями – всего лишь один аспект профессиональной разработки на Python. По мере вашего роста в качестве разработчика, инструменты, такие как Poetry, помогут вам создавать более поддерживаемые и надежные проекты на Python.