Как развернуть Python проект с poetry на Windows (для новичков)

Автор: Хотенов Артём (GitHub @hotenov)
Версия: 1.0.0 (2024-09-09)

Цели

Данная инструкция поможет начинающему специалисту настроить Python проект на вашем ПК под управлением Windows и менеджером зависимостей poetry.

Инструкция также будет полезна для продвинутых (опытных) пользователей, кто ранее не работал с poetry или с Windows.

Содержание

• Предусловия
• Подготовка окружения и нюансы перед выполнением
• Установка Python
• Установка pipx
• Установка Poetry
• Создание Poetry проекта (создание pyproject.toml)
• Установка виртуального окружения (venv)
• Что дальше?
• Поддержка автора

Предусловия

• Вы должны уметь устанавливать программы из дистрибутива и понимать какой дистрибутив вам нужно скачать с сайта (например, для Windows x64). Соответственно, ваш пользователь операционной системы (ОС) должен иметь права на установку приложений и на изменение некоторых настроек ОС.

• Вы должны уметь запускать и пользоваться консолью (также известная как: командная строка (cmd) / терминал / shell) и выполнять в ней базовые команды (создание папок, переход к папке и т.д.).

  • Чуть-чуть подумать перед выполнением каждой команды :) Приведенные в инструкции команды (пути) могут содержать ошибки / неточности / опечатки. Поэтому не стоит "слепо" их копировать, а адаптировать под ваши нужды и окружение.
  • Также внимательно копируйте текст команды (особенно если она приведена в тексте), т.к. при выделении можно случайно захватить запятую или другой символ.

• Понимать, что такое интерпретатор языка Python, т.к. в тексте он зачастую будет называться просто Python. Если понимания нет, то приравнивать эти термины.

• Вводить и запускать команды в окне Выполнить, которое появляется при нажатии сочетания клавиш Win + R

  

• Windows 10 (в теории должно подойти и для Windows 11, но я не тестировал).

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

У каждого из читателей данной инструкции система (ОС Windows) имеет разное исходное состояние перед выполнением конкретных шагов. Для того, чтобы "всё работало" по итогу, нам необходимо привести систему в некоторое "общее" состояние (относительно Python инструментария).

1. Проверьте, что ваш пользователь в системе не содержит пробелов и кириллицы. Для этого откройте консоль, выполнив команду cmd в окне Выполнить (Win + R) (по умолчанию консоль должна открыться в вашей Персональной папке, по пути:
   C:\Users\UserName>
   где вместо UserName имя вашего пользователя (без пробелов и кириллицы).

   Если в имени вашего пользователя есть пробелы и кириллица рекомендуется его изменить (как это сделать, обратитесь к поиску в Интернете). НО перед сменой имени пользователя рекомендуется удалить (если есть) все установленные версии Python.

   Если в консоли вы видите стартовое сообщение (prompt) C:\Windows\system32>, значит вы открыли консоль в режиме Администратора. Перезапустите консоль от пользователя (см. выше) или выполните команду cd /d %USERPROFILE%, чтобы перейти в Персональную папку и посмотреть имя пользователя. ☝️ Однако, дальнейшие действия не подразумевают, что вы открыли консоль от Администратора. Поэтому если что-то не сходится (не получается), держите это в голове.

2. (не обязательно, но я бы рекомендовал). Удалите все версии Python установленные ранее либо через дистрибутив, либо через приложение Магазин (Microsoft Store). Разумеется, если они у вас уже НЕ задействованы в проектах / скриптах. Зачем? Чтобы иметь "чистый лист" и избежать некоторых проблем (как новичку), связанных с наличием сразу нескольких версий Python на компьютере.

   Если нет возможности / желания удалять, то вам, возможно, придется самостоятельно настроить переменную окружения Path, чтобы по команде python запускался подходящий интерпретатор (не меньше версии 3.8). А также учитывать, что команды py и pip могут вести к неверной версии Python (например, у вас есть версия 3.11, а если дальше будете следовать инструкции и сверху установите ещё и из дистрибутива версию 3.12.5, то и py и python и pip будут вести к версии 3.12.5, а не 3.11).

3. Необходимо отключить псевдонимы выполнения приложения для Установщика приложений (во избежание проблем в будущем).

   Для этого перейдите в Настройки Windows:

   Параметры -> Приложения -> Псевдонимы выполнения приложения (ссылка справа, под "Приложения и возможности") -> Отключаем два переключателя для "python.exe" и "python3.exe" (оба под "Установщик приложения")

   

   Если они уже отключены, то переходите к следующему шагу.

Установка Python

Перед установкой нам необходимо скачать дистрибутив (установщик). Устанавливать можно последнюю стабильную (stable) 3.12.x, если у вас новый проект и импортируемые библиотеки тоже регулярно обновляются. Но можно установить и 3.11.х (её должны поддерживать уже большинство библиотек). НО не ниже 3.8 (и даже 3.10 уже для некоторых проектов).

1. Перейдите на страницу загрузок python.org и найдите подходящую для вас версию.
   Для ленивых: Прямая ссылка для скачивания 📥 Python 3.12.5 (amd64)

2. Перейдите к скачанному файлу в Проводнике и установите Python.

   В диалоге установки рекомендую:

   • убрать галочку "Use admin privileges when installing py.exe"
   • поставить галочку "Add python.exe to PATH"

   После завершения установки, откройте новое окно консоли (Win + R -> cmd). В консоли выполните команду, которая выведет "активную" версию Python:

   ❗ Важно: Далее я буду использовать только python (не py) в приведённых командах, т.к. большинство из них можно выполнять и на macOS / Linux машинах, а версия Python 2.7 уже не включена в современные версии этих ОС.

   python --version
   

   # Вывод: Python 3.12.5

   💡 Совет: Если отображается не та версия, то для диагностики проблемы можете использовать команду where.exe python. Она выведет вам пути, где система "нашла" исполняемый файл python.exe. Ищет система "сверху" (т.е. чем выше путь, тот и запустится). Как менять порядок путей я описал на вики-странице Configure the order in PATH variable проекта pyenv-win (правда, на английском языке).

   💡 Совет: Рекомендую познакомиться с менеджером версий Python для Windows pyenv-win Этот инструмент позволит максимально упростить установку разных версий Python (причём только интерпретатора, без дополнительных IDLE и документации) и быстрое переключение между ними в консоли.

   pyenv-win это типа "копия" (порт) утилиты pyenv для Linux / macOS, у вас даже команда будет такая же pyenv в консоли. НО учтите, что это разные команды и надо читать документацию, прежде чем запускать команды из туториалов в Интернете. Не забывайте у вас (у нас) Windows и мы должны страдать 😃. Как использовать / настраивать pyenv в данной инструкции не приводится. Но если будет запрос на такую инструкцию у аудитории, а у меня время, то, возможно, она появится в недалёком будущем).

Установка pipx

Note

Для справки (с сайта документации проекта pipx):
pipx - это инструмент который позволяет устанавливать и запускать Python приложения из изолированных окружений. Он чем-то напоминает утилиты: brew на macOS, npx в JavaScript's, и apt на Linux.

В нашем случае pipx нам нужен для лёгкой установки менеджера зависимостей poetry (и последующего его обновления) и не только его. pipx также поможет вам с установкой и других консольных утилит (nox, например).

1. Установите pipx, выполнив команду в консоли:

   python -m pip install --user pipx 
   

   Скорее всего, вы увидите предупреждение (Warning) о том, что ..\Scripts папка не добавлена в PATH. Не пугайтесь! Сейчас всё поправим :)

2. Для добавления пути к директории (папки) куда установился pipx.exe в переменную окружения PATH, воспользуйтесь следующей командой:

   %APPDATA%\Python\Python312\Scripts\pipx.exe ensurepath
   

   ❗ Важно: Если у вас активный Python не 3.12.x (то скопируйте название папки из текста предупреждения, т.е. ...\Python311\..., Python310 и т.д.

3. Откройте новую консоль (окно), и проверьте что pipx теперь доступен без полного пути:

   pipx --version
   

   # Вывод: 1.7.1

   💡 Совет: Для обновления самого pipx в будущем, используйте команду:

   python -m pip install --user --upgrade pipx
   

Установка Poetry

poetry - менеджер зависимостей (пакетов / библиотек) для вашего Python приложения. poetry также упрощает (берёт на себя) работу с виртуальным окружением (aka "venv"), сборкой и публикацией пакета Python.

С poetry вы можете забыть про pip install, requirements.txt и постоянную активацию / деактивацию виртуального окружения при добавлении / удалении зависимостей. A его авто-генерируемый файл poetry.lock позволяет быть уверенным, что ваш коллега или CI установят те же версии пакетов на своей машине (компьютере).

1. Установите Poetry командой в консоли:

   pipx install poetry
   

2. Проверьте установку (должно работать даже в том же окне консоли)

   poetry --version
   

   # Вывод: Poetry (version 1.8.3)

   💡 Совет: Для обновления poetry в будущем, используйте команду:

   pipx upgrade poetry
   

Создание Poetry проекта (создание pyproject.toml)

(или инициализация файла pyproject.toml)

Poetry проектом называют директорию (папку) в котором находится файл pyproject.toml, где зависимости и сведения для проекта указаны для менеджера зависимостей poetry (который мы установили на предыдущем шаге).

Файл pyproject.toml может быть создан в любом текстовом редакторе вручную (или скопирован у соседа :) ), но также есть специальная команда poetry init для его создания в интерактивном режиме (т.е. отвечая на вопросы скрипта).

Далее мы создадим новый проект (папку) demo-starter на Рабочем столе, чтобы продемонстрировать работу poetry.

1. Создайте папку на рабочем столе

   Примечание: Вы можете использовать другое расположение (не Рабочий стол). Но главное не забудьте переместиться в эту папку в консоли.

   Следующая команда создаёт папку проекта и перемещается в неё (можете выполнять атомарные команды (до и после символа &) по отдельности):

   md %USERPROFILE%\Desktop\demo-starter & cd /d %USERPROFILE%\Desktop\demo-starter
   

2. Создаёте файл pyproject.toml в интерактивном режиме

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

   poetry init
   

   Для ознакомительных целей можете заполнять значениями по умолчанию (приведены в квадратных скобках [ ]), нажимая клавишу Enter.

   НО, для поля Author укажите ваши имя и емейл в формате
   Artem Hotenov <qa@hotenov.com>
   (т.е. емейл в угловых скобках должен быть)

   НО, на вопрос "Would you like to define your main dependencies interactively? (yes/no)" укажите no

   НО, на вопрос "Would you like to define your development dependencies interactively? (yes/no)" укажите no

   В конце проверьте (глазками) указанные данные и, если всё ОК, подтвердите генерацию файла, ответив yes на вопрос "Do you confirm generation? (yes/no)"

   (по желанию) Для уверенности, можете вывести список файлов в директории, чтобы убедится, что файл создан:
   dir /b
   # Вывод: pyproject.toml

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

Не принципиально, но для единообразия и некого удобства будем создавать виртуальное окружение (venv) внутри нашего poetry проекта (т.е. корневой директории проекта).

poetry создаст папку (виртуальное окружение) с именем .venv

Important

К сожалению, имя .venv пока нельзя изменить в настройках poetry и это может быть проблемой в некоторых случаях (но они все некритичные и решаемые 😃).

1. Настройте (сконфигурируйте) poetry для создания виртуального окружения внутри проекта

   ❗ Важно: Не пропустите эту команду! Иначе намучаетесь потом искать где venv для вашего проекта (конечно, обращение к начинающим)

   poetry config virtualenvs.in-project true
   

   Примечание: Команда "молчаливая" (т.е. результатам её выполнения будет пустая строка ("ничего") и это нормально).

   💡 Совет: Команда выше изменит "глобальную" настройку poetry, т.е. далее во всех проектах виртуальное окружение будет создаваться "внутри проекта". При этом вы можете указать (применить) эту настройку только для текущего проекта (папки), выполнив:
   poetry config virtualenvs.in-project true --local

2. Создайте виртуальное окружение

   poetry install --no-root
   

   Будет создана папка .venv (с копией интерпретатора Python) и файл poetry.lock. Вы можете проверить себя вновь командой:
   dir /b
   # Вывод столбиком: .venv poetry.lock pyproject.toml

   Самостоятельно: Чтобы не писать опцию (флаг) --no-root можно отредактировать файл pyproject.toml и добавить строчку package-mode = false
   Собственно, об этом вам выскочит предупреждение, если забудете указать --no-root. При этом виртуальное окружение создаётся (пока разработчики poetry не поменяют это на ошибку).
   И, разумеется, как только у вас будет сконфигурирован ваш пакет (приложение) в pyproject.toml и вам надо будет устанавливать его с другими зависимостями, то --no-root вам больше будет не нужен.

3. Добавьте нужные зависимости (пакеты / библиотеки)

   poetry add selene --allow-prereleases
poetry add pytest
   и т.д.

   💡 Совет: Подробнее об установке зависимостей и ограничениях версий вы можете почитать на сайте с документацией Poetry. Но они на английском.

4. (бонус) Запускайте консольные утилиты внутри вашего виртуального окружения

   poetry run pytest
   

   Что равнозначно последовательности команд:

   .\.venv\Scripts\activate
   pytest
   deactivate
   

Что дальше?

Надеюсь, у вас всё получилось с первого раза и теперь вы умеете разворачивать Python проект "с нуля" довольно продвинутым способом на Windows. Ведь до сих пор есть программисты, которые используют pip и даже не используют venv, устанавливая все зависимости "глобально".

Теперь посоветовал бы вам познакомиться с IDE (интегрированной средой разработки), где некоторые вещи можно делать в несколько кликов или не делать совсем 😃, т.к. они делаются автоматически. Например, активация виртуального окружения (если оно есть) во встроенном (интегрированном) Терминале при его открытии.

Я сам использую VS Code (т.к. мне зачастую нужен не только Python, но и для Python VS Code тоже прекрасно подходит). Есть ещё узконаправленный PyCharm (если вы фанат продуктов JetBrains или вам навязали его на работе / курсах / в метро 😃).

Развивайтесь (двигайтесь) дальше по этому нелегкому пути. Вот лишь несколько направлений, которые вы можете освоить, чтобы стать ещё более эффективным и продуктивным:

• Детальнее изучить возможности задействованных инструментов pipx и poetry
• Перейти на pyenv (проект pyenv-win) для управления версиями Python.
• Перейти на современный PowerShell 7 и сделать его своим основным шеллом (консолью) как в системе, так и во встроенном Терминале IDE.
• Установить Windows Terminal и ознакомиться с его возможностями.
• Настроить себе oh-my-posh и радоваться не "серой" командной строке.

Поддержка автора

Вы можете поддержать автора этого туториала @hotenov как морально, так и материально (ссылки ниже).

Ставьте "звёзды" 🌟 этому документу и ваши реакции. Пишите комментарии и делитесь ссылкой с коллегами.

Финансовая помощь ещё больше приветствуется 😃 Так вы сможете подтолкнуть меня написать ещё инструкций в подобном стиле (где "всё разжёвано"), если вам понравилась эта и вы уже купили все курсы в Интернете 😃.

• Закинуть через T-Банк (ранее Тинькофф Банк) -> Перевод в Т-Банк
• Через сервис Юmoney

Сам курсов пока не виду и не произвожу (видео), но могу провести частные консультации (если они вам нужны и вы не бедствуете). Буду честен, я далеко не гуру (и сам постоянно учусь), но прочитаю за вас необходимую документацию и приложу свой многолетний опыт в решении ваших проблем. Пишите в Телеграме или на почту qa@hotenov.com

А я, в свою очередь, хочу сказать спасибо:

• Участникам чата Selene.py на русском, которые поддержали мою идею по написанию данной инструкции.
• Ксении Севостьяновой, за мотивацию и самый первый фидбек.
• **Ваше имя может оказаться здесь, если поддержите финансово и пожелаете быть упомянутым**

© 2024 by Artem Hotenov is licensed under CC BY 4.0