- Как установить Poetry
- Как настроить Poetry
- Как создать первый проект
- Как работать с pyproject.toml
- Как инициализировать виртуальное окружение
- Выводы
Во всех проектах профессии мы предлагаем использовать инструмент poetry — с его помощью можно управлять зависимостями. Сегодня это главный инструмент Python-разработчика.
Poetry — простой и удобный инструмент, который упрощает ведение и разработку проекта. Советуем оформлять каждый учебный эксперимент как poetry-проект, так вы быстрее привыкнете к профессиональным инструментам.
В этом уроке будем разбираться, как работать с Poetry. Пойдем по следующим шагам:
- Установка
- Настройка
- Создание первого poetry-проекта
- Работа с
pyproject.toml
- Инициализация виртуального окружения
Как установить Poetry
Poetry написан на Python, но это не обычная Python-программа, которую устанавливают с помощью pip install
. Во вводном разделе документации к Poetry вы найдете команды для установки программы в вашу операционную систему.
Когда вы установите Poetry, он станет доступен как отдельная команда в shell:
poetry --version
Poetry version …
На этом установка программы заканчивается. Перед тем, как создавать первый проект, настроим инструмент для удобной работы.
Как настроить Poetry
Если сразу после установки запросить перечень настроек Poetry, можно увидеть следующее:
poetry config --list
cache-dir = "/…/…/.cache/pypoetry"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.path = "{cache-dir}/virtualenvs" # /home/astynax/.cache/pypoetry/virtualenvs
Poetry работает с виртуальными окружениями. При этом он изначально настроен так, что у вас будет много разных версий Python. По этой причине инструмент создает виртуальные окружения для проектов в непривычном месте — обратите внимание на настройку virtualenvs.path
.
Можно использовать настройки по умолчанию, но Python-разработчики обычно хранят виртуальное окружение для каждого проекта в директории проекта, а именно в поддиректории .venv
.
Вспомните, как вы создавали окружения командой python3 -m venv .venv
. В Poetry стоит делать так же:
poetry config virtualenvs.in-project true
Теперь у каждого poetry-проекта виртуальное окружение будет при себе. Например, так можно переносить проект с одной машины на другую — достаточно просто скопировать директорию.
Когда мы настроим Poetry, он будет готов для создания первого проекта.
Как создать первый проект
Создадим poetry-проект с помощью команды poetry new ИМЯ
. Перед запуском Poetry убедитесь, что в системе доступна команда python3
.
Предположим, вы ввели команду poetry new first
. Вот как будет выглядеть результат:
poetry new first
Created package first in first
cd first # Переходим в созданную директорию
tree .
.
├── first
│ └── __init__.py
├── pyproject.toml
├── README.md
└── tests
└── __init__.py
2 directories, 4 files
Сообщение Created package first in first
означает, что в проекте first создался одноименный пакет — директория first
с соответствующим __init__.py
. Любой poetry-проект всегда содержит хотя бы один пакет.
Кроме пакета first
в проекте уже есть пакет tests
. Пока он нам не нужен, но стоит знать, что у настоящих проектов всегда есть пакет с тестами.
Еще в реальном проекте у вас будет файл README.md
, в котором вы будете держать описание проекта. У этого файла расширение .md
— это файл формата Markdown. Это очень популярный формат разметки, даже этот урок написан на нем.
Самый важный файл в poetry-проекте — pyproject.toml
. Это файл формата TOML, можете почитать о нем подробнее по ссылке.
Файл pyproject.toml
содержит конфигурацию проекта. Информация из этого файла нужна, чтобы Poetry мог:
- Управлять зависимостями проекта
- Запускать код на исполнение
- Запускать инструменты для разработки
- Собирать дистрибутив и публиковать его на PyPI
Чем больше вы работаете с Poetry, тем лучше вы разбираетесь в публикации проектов. Постепенно вы привыкаете, что в каждом пакете должно быть описание, правильная структура, указанная версия. Мы советуем всегда оформлять проекты по этим стандартам, даже если вы не собираетесь публиковать проект в индекс.
Мы создали первый проект. Теперь нужно разобраться с pyproject.toml
.
Как работать с pyproject.toml
У нового проекта файл конфигурации выглядит примерно так:
[tool.poetry]
name = "first"
version = "0.1.0"
description = ""
authors = ["…"]
readme = "README.md"
[tool.poetry.dependencies]
python = "^3.10"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Строчки вида [tool.poetry]
описывают секции с парами «ключ = значение». Большую часть ключей нельзя помещать не в свои секции. В документации можете подробнее изучить ключи и узнать, каким секциям они принадлежат.
Здесь мы рассмотрим такие строчки:
tool.poetry
— описывает проект с точки зрения Poetry. Здесь хранится версияversion
, описаниеdescription
и название проектаname
tool.poetry.dependencies
— хранит список зависимостей, которые требуются для работы самого кода. Здесь всегда будет указан сам Python — без него код не запустить
Секция build-system
указывает, что перед нами проект, который управляется Poetry. При этом есть и другие инструменты, чтобы управлять проектами. Для них секция build-system
выглядит иначе.
Осталось разобраться с последним шагом — инициализацией виртуального окружения.
Как инициализировать виртуальное окружение
Poetry понимает, что окружение пора создать или обновить. Команду обновления окружения можно вызвать как poetry install
:
poetry install
Updating dependencies
Resolving dependencies...
Writing lock file
…
Installing the current project: first (0.1.0)
Эта команда устанавливает все зависимости в окружение в директорию .venv
внутри проекта. Активируется окружение командой poetry shell
, а завершается командой exit
:
# Выведем список пакетов,установленных в системе
pip list
Package Version
-------------------- ---------------
asciinema 2.2.0
attrs 22.1.0
blinker 1.4
# Тут продолжение большого списка
...
# Как видите, в системе уже стоит немало пакетов
# Поэтому мы можем столкнуться с конфликтом версий при установке нового пакета
# Чтобы этого избежать, мы и используем виртуальные окружения
# Выведем список пакетов в окружении
poetry shell
Spawning shell within /../first/.venv
pip list
# В новом окружении есть только необходимый минимум для работы Poetry
Package Version
---------- -------
pip 22.2.2
setuptools 65.3.0
wheel 0.37.1
Зачастую активация окружения необязательна — Poetry предлагает команду run
, которая исполняет программы уже изнутри окружения. Например, REPL в рамках проекта принято запускать командой poetry run python
.
Так выглядит работа с Poetry. Это удобный инструмент, поэтому мы советуем пользоваться им. Оформляйте даже самые маленькие эксперименты как poetry-проекты — так вы быстрее научитесь работать с инструментом.
Выводы
- Poetry — удобный инструмент, который упрощает ведение и разработку проекта
- Poetry устанавливают не через
pip install
. Для этого используются специальные команды, которые есть в документации к Poetry - Нужно, чтобы у каждого проекта виртуальное окружение было при себе. Для этого Poetry нужно предварительно настроить
- В каждом пакете должно быть описание и правильная структура, а также назначена версия
Самостоятельная работа
- Создайте проект с именем
hello
- Убедитесь, что структура проекта похожа на показанную в примере. Обратите внимание, в чем различия между вашим проектом и примером
- Создайте окружение с помощью команды
poetry install
- Изучите содержимое окружения
Дополнительные материалы
Остались вопросы? Задайте их в разделе «Обсуждение»
Вам ответят команда поддержки Хекслета или другие студенты
Для полного доступа к курсу нужен базовый план
Базовый план откроет полный доступ ко всем курсам, упражнениям и урокам Хекслета, проектам и пожизненный доступ к теории пройденных уроков. Подписку можно отменить в любой момент.