Posted on April 12, 2019· Updated on July 3, 2022

Проекты на Python с Poetry и VSCode. Часть 1: Шпаргалка по Python.

#python #intermediate #vscode #packaging

Виртуальное окружение — это изолированная установка Python, предназначенная для того, чтобы избежать заполнения нашей базовой установки библиотеками, которые мы можем использовать только для одного проекта. Оно также позволяет нам управлять несколькими версиями одного и того же пакета в разных проектах. Например, нам может понадобиться Django 4.1 для одного проекта и 1.9 для другого.

Python Poetry

Poetry — это инструмент для обработки установки зависимостей, а также для сборки и упаковки пакетов Python. Для всего этого ему нужен только один файл: новый, стандартизированный pyproject.toml. Другими словами, poetry использует pyproject.toml для замены setup.py, requirements.txt, setup.cfg, MANIFEST.in и недавно добавленного Pipfile.

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

В этой первой части мы:

Начнем новый проект.
Создадим Виртуальное окружение.
Управлять зависимостями.

Во второй статье мы:

Добавим наше виртуальное окружение в VSCode.
Интегрируем наши dev-зависимости:
- Flake8
- Black
- Pytest

И, наконец, в третьей статье мы:

Напишем пример библиотеки.
Соберем наш проект с помощью Poetry.
Опубликуем его на PyPI.

Установка Poetry

Самый простой способ — использовать pip:

pip install poetry

Но мы будем использовать собственный установщик Poetry, чтобы изолировать его от остальной системы, используя vendorizing его зависимостей. Это рекомендуемый способ установки poetry:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

Таким образом, позже мы сможем обновить poetry до последней стабильной версии с помощью команды poetry self update.

Запуск нового проекта

Теперь мы можем начать новый проект Python, используя команду poetry new [project_name]. Я назову его how-long, и это будет простая библиотека для измерения времени выполнения функции:

poetry new how-long

Примечание: Для существующих проектов вы можете использовать команду poetry init и интерактивно создать pyproject.toml.

Создается каталог how-long, и внутри него находится базовая структура проекта:

how-long
├── README.rst
├── how_long
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_how_long.py

Для получения исчерпывающего руководства по работе с путями к файлам и каталогам, что важно для управления структурами проектов, см. страницу Пути к файлам и каталогам.

Примечание: Чтобы иметь возможность опубликовать свой проект, вам нужно доступное имя. Используйте для этого поиск PyPI.

Файл pyproject.toml

Файл pyproject.toml будет управлять деталями и зависимостями проекта:

[tool.poetry]
name = "how-long"
version = "0.1.0"
description = "A simple decorator to measure a function execution time."
authors = ["wilfredinni <carlos.w.montecinos@gmail.com>"]

[tool.poetry.dependencies]
python = "^3.7"

[tool.poetry.dev-dependencies]
pytest = "^3.0"

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

[tool.poetry]

Детали. Добавление лицензии и README может быть хорошей идеей:

[tool.poetry]
...
license = "MIT"
readme = "README.rst"

[tool.poetry.dependencies]

Сначала идет версия Python. В основном, этот проект будет совместим с Python 3.7 и выше. Кроме того, с этого момента каждый пакет, который мы устанавливаем и который предназначен для использования в production, будет перечислен здесь.

[tool.poetry.dev-dependencies]

Эти пакеты предназначены только для разработки и не будут включены, когда мы опубликуем наш проект. По умолчанию Poetry включает Pytest, поэтому мы будем использовать его для тестирования нашего проекта позже.

Создание Виртуального окружения

Чтобы создать Виртуальное окружение и установить Pytest, мы будем использовать команду poetry install:

poetry install

poetry-install-command

После завершения будет создан новый файл poetry.lock.

Когда Poetry завершит установку, он записывает все пакеты и их точные версии, которые он загрузил, в файл poetry.lock, фиксируя проект на этих конкретных версиях. Вы должны зафиксировать файл poetry.lock в репозитории вашего проекта, чтобы все люди, работающие над проектом, были зафиксированы на одних и тех же версиях зависимостей.

Управление зависимостями

Один из способов добавить или удалить зависимости — это напрямую отредактировать pyproject.toml, а затем запустить poetry install, чтобы применить изменения. Вместо этого мы будем использовать команды add и remove, чтобы избежать ручных изменений.

Добавление зависимостей

Давайте добавим два пакета в проект, pendulum и coo:

poetry add pendulum coo

poetry-add-command

Откройте pyproject.toml и poetry.lock и посмотрите, как они обновились.

Добавление Dev-зависимостей

Эти зависимости будут доступны только во время разработки, Poetry не будет включать их при сборке и публикации проекта.

Мы уже установили Pytest, но мы также будем использовать flake8 для линтинга и mypy для статической типизации:

poetry add -D flake8 mypy

Теперь, когда я думаю об этом, я забыл добавить форматер. Мы выберем black:

poetry add -D black
[ValueError]
Could not find a matching version of package black

add [-D|--dev] [--git GIT] [--path PATH] [-E|--extras EXTRAS] [--optional] [--python PYTHON] [--platform PLATFORM] [--allow-prereleases] [--dry-run] [--] <name> (<name>)...

Эта ошибка возникает потому, что black находится в состоянии предварительного выпуска, поэтому Poetry не может найти для нас стабильную версию. Но я действительно хочу его, поэтому давайте установим его в любом случае с флагом --allow-prereleases:

poetry add -D black --allow-prereleases

poetry-add-dev-command

Удаление зависимостей

Знаете что, я передумал, этот проект не будет использовать ни coo, ни mypy. Начнем с удаления coo, обычной зависимости нашего проекта:

poetry remove coo

Теперь mypy, которая является dev-зависимостью:

poetry remove -D mypy

Заключение

В этой первой части мы запустили новый проект, создали Виртуальное окружение, а также добавили и удалили зависимости, используя следующие команды:

Команда	Описание
`poetry new [package-name]`	Запустить новый проект Python.
`poetry init`	Интерактивно создать файл pyproject.toml.
`poetry install`	Установить пакеты внутри файла pyproject.toml.
`poetry add [package-name]`	Добавить пакет в Виртуальное окружение.
`poetry add -D [package-name]`	Добавить dev-пакет в Виртуальное окружение.
`poetry remove [package-name]`	Удалить пакет из Виртуального окружения.
`poetry remove -D [package-name]`	Удалить dev-пакет из Виртуального окружения.
`poetry self:update`	Обновить poetry до последней стабильной версии.

Во второй статье мы рассмотрим больше команд Poetry, добавим наше Виртуальное окружение в VSCode и используем установленные нами dev-пакеты для линтинга (Flake8), форматирования (Black) и тестирования (Pytest) нашего кода внутри редактора. Наконец, в третьей статье мы напишем и опубликуем пример библиотеки на PyPI.

Есть сомнения или предложения? Пожалуйста, оставьте комментарий.