Это адаптированный перевод статьи Modern Python part 1: start a project with pyenv & poetry Фаози Браза, специалиста по Data Engineer. Повествование ведётся от лица автора оригинала.

Перевод был сделан для платформы курсов по программированию Хекслет

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

Процесс создания пакетов и инструментарий для Python часто называют громоздким и сложным. В связи с этим в последние годы появилось несколько проектов с открытым исходным кодом, цель которых — облегчить управление пакетами Python в рамках ваших рабочих проектов. Здесь мы рассмотрим, как использовать два из них: Pyenv — для управления и установки различных версий Python, и Poetry — для управления пакетами и виртуальными окружениями.

Эта статья — первая из цикла, в котором рассказывается о лучших практиках современного Python. В этом цикле статей все примеры основаны на реализации простого проекта — он представляет собой функцию Python, которая суммирует данные, присутствующие в pandas DataFrame. Функция выводит количество строк и столбцов и частоту каждого типа данных, присутствующих в pandas DataFrame.

Подготовка

Установка pyenv

Для установки pyenv вам потребуются некоторые зависимости, специфичные для вашей операционной системы. Они необходимы, поскольку pyenv устанавливает Python через сборку из исходного кода. Чтобы узнать о необходимых зависимостях для вашей ОС, прочитайте эту документацию. После установки зависимостей, вы можете установить pyenv. Для этого лучше использовать pyenv-installer, который автоматизирует процесс.

curl https://pyenv.run | bash

После этого вы уже можете установить на свою систему любые версии Python. Узнать все доступные версии Python вы сможете через специальную команду:

pyenv install --list

В нашем случае мы установим классический CPython версий 3.7.10, 3.8.7, 3.9.2:

pyenv install 3.7.10
Downloading Python-3.7.10.tar.xz...
> https://www.python.org/ftp/python/3.7.10/Python-3.7.10.tar.xz
Installing Python-3.7.10...
Installed Python-3.7.10 to /home/aabur/.pyenv/versions/3.7.10

После установки версий вы можете увидеть их, выполнив команду:

pyenv versions
 system
3.7.10
3.8.7
3.9.2

Видно, что pyenv идентифицировал недавно установленные версии Python, и версию, установленную по умолчанию в вашей системе. Символ  перед system означает, что глобальная версия, используемая сейчас, является системной. pyenv позволяет управлять версиями Python на разных уровнях: глобально и локально. Допустим, мы собираемся установить версию 3.7.10 в качестве глобальной версии.

pyenv global 3.7.10

Давайте еще раз посмотрим наши версии:

pyenv versions
system
* 3.7.10 (set by /home//.pyenv/version)
3.8.7
3.9.2

Вы видите, что pyenv установил 3.7.10 в качестве нашей глобальной версии Python. Это не изменит операции, которые требуют использования системной версии. Путь, который вы можете прочитать между скобками, соответствует пути, который указывает на требуемую версию Python. pyenv перехватывает команды Python с помощью исполняемых файлов, введенных в ваш PATH, определяет, какую версию Python вам нужно использовать, и передает команды нужной версии Python. Не стесняйтесь читать полную документацию, чтобы лучше понять функциональность и возможности pyenv.

Пусть вас не смущает семантика. Изменение глобальной версии не повлияет на вашу системную версию. Системная версия соответствует версии, используемой вашей ОС для выполнения определенных задач или запуска фоновых процессов, которые зависят от этой конкретной версии Python. Не меняйте системную версию на другую, иначе вы можете столкнуться с рядом проблем с вашей операционной системой! Эта версия обычно обновляется вместе с вашей ОС. Глобальная версия — это просто версия, которую pyenv будет использовать для глобального выполнения команд/программ Python.

Установка poetry

poetry позволяет эффективно управлять зависимостями и пакетами в Python. Он выполняет ту же роль, что и setup.py или pipenv, но обладает большей гибкостью и функциональностью. Вы можете указать библиотеки, от которых зависит ваш проект, в файле pyproject.toml. После этого poetry установит или обновит их по вашему запросу. Кроме того, этот инструмент позволяет изолировать ваш рабочий проект в изолированное окружение. Наконец, вы можете использовать poetry для прямой публикации вашего пакета на Pypi.

Последним подготовительным шагом будет установка poetry путем выполнения команды:

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

Создание проекта

Мы рассмотрим, как создать проект и изолировать его внутри окружения Python с помощью pyenv и poetry.

Установка версии Python с помощью pyenv

Сначала создадим каталог с именем my_awesome_project и переместимся в него:

mkdir my_awesome_project && cd $_

Находясь внутри папки проекта, установите локальную версию Python, которую мы будем использовать (мы будем использовать Python 3.8.7). Это укажет poetry использовать локальную версию Python, определенную pyenv:

pyenv local 3.8.7

Это создаст файл .python-version внутри нашего проекта. Этот файл будет прочитан pyenv и заставит его установить определенную локальную версию Python. В результате каждый каталог или файл, созданный после этого, будет зависеть от локальной версии Python, а не от глобальной.

Создание проекта с помощью poetry

Poetry предоставляет надежный CLI, позволяющий создавать, настраивать и обновлять ваш Python-проект и его зависимости. Для создания проекта Python используйте следующую команду:

poetry new <project_name>

Эта команда генерирует проект по умолчанию. Содержание нового проекта следующее:

.
└── summarize_dataframe
├── README.rst
├── pyproject.toml
├── summarize_dataframe
│   └── init.py
└── tests
├── init.py
└── test_summarize_dataframe.py

Обратите внимание на файл pyproject.toml. Здесь мы определяем все метаданные нашего проекта, зависимости, скрипты и многое другое.

[tool.poetry]
name = "summarize_dataframe"
version = "0.1.0"
description = ""
authors = [" "]
[tool.poetry.dependencies]
python = "^3.8"
[tool.poetry.dev-dependencies]
pytest = "^5.2"
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Мы видим несколько разделов в нашем стандартном файле pyproject.toml.

• [tool.poetry]: Этот раздел содержит метаданные о нашем пакете. Вы можете поместить сюда название пакета, краткое описание, данные об авторе, версию вашего проекта и так далее. Все детали здесь необязательны, но будут необходимы, если вы решите опубликовать пакет на Pypi.

• [tool.poetry.dependencies]: Этот раздел содержит все необходимые зависимости для нашего пакета. Вы можете указать конкретные номера версий этих пакетов (packageX = "1.0.0") или использовать условные обозначения. Здесь также задается версия Python, которую мы хотим использовать в проекте. В нашем случае python = "^3.8" определяет минимальную версию, необходимую для работы нашего приложения. Здесь — Python 3.8, это основано нашей локальной версии, определенной с помощью pyenv.

• [tool.poetry.dev-dependencies]: Этот раздел содержит все зависимости необходимые для разработки проекта. Тем не менее, эти зависимости не требуются для запуска приложения и не будут загружены при сборке пакета.

• [build-system]: Не трогайте этот раздел, если вы не обновили версию poetry.

Вы можете посмотреть полный список доступных разделов для файла pyproject.toml здесь.

Установка и активация виртуального окружения

Здесь есть два подхода: либо вы заранее знаете все необходимые вам зависимости и можете напрямую изменить файл pyproject.toml соответствующим образом, либо вы решаете добавить их позже, по мере необходимости. В нашем примере мы собираемся постепенно добавлять зависимости в процессе написания кода. Следовательно, нужно только инициализировать проект и создать виртуальное окружение. Для надо выполнить команду в директории вашего проекта:

poetry install
Creating virtualenv summarize-dataframe in /Users/aabur/Documents/GitHub/AABur/modern_python/summarize_dataframe/.venv
Updating dependencies
Resolving dependencies... (7.3s)
Writing lock file
Package operations: 8 installs, 0 updates, 0 removals
• Installing pyparsing (2.4.7)
• Installing attrs (21.2.0)
• Installing more-itertools (8.11.0)
• Installing packaging (21.2)
• Installing pluggy (0.13.1)
• Installing py (1.11.0)
• Installing wcwidth (0.2.5)
• Installing pytest (5.4.3)
Installing the current project: summarize_dataframe (0.1.0)

Сначала создаётся виртуальное окружение. В нашем случае в папке проекта в директории .venv.

Вы можете создать виртуальное окружение в любых других каталогах. Для этого вам нужно отредактировать конфигурацию poetry. Для получения более подробной информации следуйте этой документации.

Затем, poetry прочитает файл pyproject.toml и установит все зависимости, указанные в этом файле. Если версии зависимостей не определены, poetry загрузит последнюю версию пакетов. В конце операции создается файл poetry.lock. Он содержит все пакеты и их точные версии. Помните, что если файл poetry.lock уже существует, то номера версий, определенные в нем, имеют приоритет над теми, что определены в файле pyproject.toml. Наконец, вы должны сохранить файл poetry.lock в репозитории проекта, чтобы все участники, работающие над проектом, использовали одинаковые версии зависимостей.

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

poetry shell
Spawning shell within /Users/aabur/Documents/GitHub/AABur/modern_python/summarize_dataframe/.venv

Команда создает дочерний процесс, который наследует от родительского Shell, но не изменяет свое окружение. Она изолирует и защищает любые изменения, которые вы будете вносить в среду проекта.

Создание репозитория git

На последнем этапе мы создадим git-репозиторий, добавим файлы README.md и .gitignore и перенесем все в наш удаленный репозиторий.

git init
echo ".*\n!.gitignore" > .gitignore
echo "# Summarize dataframe" > README.md
git add .
git commit -m "build: first commit. Environment built"
git remote add origin git@github.com:AABur/summarize_dataframe.git
git branch -M main
git push -u origin main

Заключение

Здесь мы рассмотрели, как устанавливать и управлять различными версиями Python на нашей машине с помощью pyenv. Мы продемонстрировали, как использовать pyenv local для установки определенной версии Python в вашем проекте, а затем создать виртуальное окружение с помощью poetry. Использование poetry значительно упрощает процесс создания проекта, предлагая простые и разнообразные средства для его настройки. Кроме того, он включает минимальные требования к системе сборки, как определено в PEP 518.

Краткая памятка

pyenv

• Посмотреть все доступные для установки версии Python

pyenv install --list

• Установить глобальную версию Python

pyenv global

• Установить локальную версию Python

pyenv local

poetry

• Создать проект

poetry new

• Установить основные зависимости и создать виртуальное окружение

poetry install

• Активировать виртуальное окружение

poetry shell