Руководство для Python-проекта

Python — великолепный язык, используемый для всего, начиная с создания веб-сайтов и заканчивая сложными научными исследованиями. Однако настройка проекта может быть непростой задачей. И вот в этом месте на помощь приходит это руководство для Python-проекта! В этой статье я покажу, как организовать свой проект, создать виртуальные окружения, управлять зависимостями, форматировать свой код, тестировать его и многое другое. Я расскажу вам все, что нужно знать, чтобы запустить свой проект на Python и добиться его стабильного развертывания и функционирования.

Прежде всего, делайте всё просто

Python создан для того, чтобы быть простым. Выполните команду import this в Python REPL, и вы получите «The Zen of Python» (Философия Python).

>>> import this
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Создание полезного проекта — это легко. Создание проекта, который будет долговечным, — это сложно. Но у меня есть руководство!

В самом деле, соотношение времени, потраченного на чтение по сравнению с писанием, значительно больше 10 к 1. Мы постоянно читаем старый код в процессе написания нового кода… [поэтому] сделать его легко читаемым облегчает написание.

Источник: Роберт С. Мартин, «Чистый код: руководство агильного разработчика»

При настройке проекта на Python крайне важно установить стандарт написания поддерживаемого кода — кода с низкой когнитивной нагрузкой. Легкочитаемый. Легко находимый. Легко следуемый.

Структура каталогов

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

1. Создайте корневой каталог для вашего проекта. Создайте корневой каталог для вашего проекта и дайте ему имя вашего проекта. Назовите свой проект чем-то осмысленным. Я предпочитаю именовать проекты и модули по их функциональности и избегать использования кодовых имен для вещей.
2. Используйте подкаталоги для вашего кода. Организуйте свой код в подкаталоги на основе логических компонентов или модулей. Например, у вас может быть подкаталог для кода обработки данных, подкаталог для кода визуализации и так далее.
3. Используйте файл __init.py__ в каталогах, содержащих модули. Если у вас есть каталог с модулями Python, добавьте файл __init.py__ в каталог. Это сообщает Python, что каталог является пакетом и позволяет вам импортировать модули из пакета.
4. Используйте описательные имена для вашего проекта, файлов и каталогов. Используйте описательные имена, которые четко указывают, что содержится в каждом модуле, файле и каталоге. Это упростит другим понимание вашего кода и навигацию по вашему проекту (и упростит вам самим, если вы отложите свой проект на несколько недель).
5. Держите ваши тесты рядом с вашим кодом. Некоторые инженеры предпочитают создавать каталог tests для написания своих тестов. Я предпочитаю держать тесты прямо рядом с тестируемым кодом. Если у вас есть файл с именем models/user.py, тестовый файл должен называться models/user_test.py. Это позволяет четко определить, где ваш код и где ваши тесты, и позволяет вам держать их в одном когнитивном пространстве.
6. Используйте виртуальное окружение. Используйте виртуальное окружение для управления зависимостями и обеспечения однородности работы вашего проекта в различных средах. Об этом позже.

Вы часто будете работать с фреймворками или инструментами, которые могут уже иметь свои предпочтения относительно структуры каталогов (я смотрю на вас, Django). Или вы использовать шаблон MVC к структуре вашего проекта. Независимо от вашего выбора, составьте план и придерживайтесь его!

Виртуальные окружения

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

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

Вот как создать виртуальное окружение с использованием virtualenv:

1. Установите virtualenv. Вы можете установить virtualenv, используя pip, менеджер пакетов Python. Откройте терминал и выполните команду pip install virtualenv.
2. Создайте виртуальное окружение. Перейдите в каталог вашего проекта и выполните команду virtualenv venv. Это создаст новое виртуальное окружение в текущем каталоге с именем venv.
3. Активируйте виртуальное окружение. Для активации виртуального окружения выполните команду source venv/bin/activate на Linux/Mac или venv\Scripts\activate на Windows.

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

Я использую Poetry для управления виртуальными окружениями во всех своих проектах на Python.

Вот как использовать Poetry:

1. Установите Poetry. Вы можете установить Poetry, следуя инструкциям на сайте Poetry.
2. Создайте новый проект. Перейдите в каталог, где вы хотите создать свой проект, и выполните команду poetry new myproject. Это создаст новый каталог проекта с именем myproject и базовой структурой проекта внутри.
3. Активируйте виртуальное окружение. Для активации виртуального окружения выполните команду poetry shell. Это создаст новое виртуальное окружение и активирует его. Если вы хотите выполнить команду в виртуальном окружении без его активации, используйте команду poetry run <команда>, например: poetry run python main.py.
4. Установите пакеты и зависимости. Чтобы установить пакеты и зависимости для вашего проекта, выполните команду poetry add package_name. Это установит пакет и добавит его в файл pyproject.toml вашего проекта. Подробнее об этом позже.

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

Если вы используете VS Code, вы также можете использовать Devcontainers в качестве альтернативы виртуальным окружениям. Devcontainers — это предварительно настроенные среды, работающие внутри контейнеров Docker и позволяющие вам разрабатывать и тестировать свой код в однородной среде. Я предпочитаю Devcontainers, так как работаю на нескольких компьютерах с тремя различными операционными системами. Комбинация Poetry + Devcontainer позволяет мне без лишних усилий запускать свой код на разных системах. Это всегда работает.

Зависимости

Зависимости проекта — это внешние пакеты или библиотеки (код, написанный другими людьми), которые ваш проект на Python использует для правильной работы. К зависимостям могут относиться такие вещи, как веб-фреймворки, драйверы баз данных или библиотеки машинного обучения.

Вместо копирования кода из других библиотек в свой собственный проект, Python (и большинство других языков) поддерживает установку зависимостей через инструмент управления зависимостями, называемый pip. Проекты, доступные для установки, можно найти на сайте PyPI.org.

pip — это хороший инструмент. Но он для старта. Во всех своих проектах на Python я использую Poetry для управления зависимостями. Это тот же инструмент, который я использую для управления виртуальными окружениями.

Установите Poetry с помощью этой команды:

curl -sSL https://install.python-poetry.org | python3 -

Как только это установлено на вашей системе, вы можете начать новый проект.

poetry new myproject
cd myproject

Добавление зависимостей к вашему проекту так же просто, как использование pip.

poetry add requests

Poetry сохраняет все ваши зависимости в файл pyproject.toml и закрепляет их за конкретной версией в файле poetry.lock. Это обеспечивает возможность точного воспроизведения вашего проекта в различных средах.

Есть еще несколько других функций, которые делают Poetry легким выбором. Их документация содержит актуальный список этих функций.

Форматирование кода

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

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

Помните нашу цитату от Боба Мартина? Больше времени уходит на чтение кода, чем на его написание. Если этот код отформатирован последовательно, чтение становится намного легче.

В этой связи я всегда использую Black. Есть и другие инструменты для форматирования. И Black не очень настраиваем, но именно в этом его преимущество. Любая команда, которая решит использовать Black, получит код, который выглядит одинаково везде. Не будет больше споров о форматировании, потому что выбор уже сделан. И он интегрируется со всеми редакторами кода, которые я когда-либо использовал.

poetry add black --group dev

Прямо из документации Black:

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

Узнайте больше о Black →

Линтинг кода

Линтинг кода и форматирование кода связаны, но это не одно и то же.

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

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

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

poetry add pylint --group dev

У pylint множество параметров конфигурации. Я предлагаю начать с набора настроек по умолчанию и добавлять исключения, по мере того как вы и ваша команда начнете больше работать с ним.

Использование pylint с black

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

На сегодняшний день существует только одно противоречие между стилями Pylint и Black: длина строки. Вы можете установить ее для Pylint в вашем файле pyproject.toml.

# pyproject.toml
[tool.pylint.format]
max-line-length = "88"

Интересный факт: кодовая база Pylint сама использует Black для своего собственного внутреннего форматирования.

Тестирование

• Почему тестирование важно
• Типы тестов, которые вы можете написать (например, модульные тесты, интеграционные тесты)
• Инструменты, которые вы можете использовать для тестирования (например, pytest, unittest)
• Лучшие практики написания и организации тестов

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

Стандартом для качественного тестирования в Python является Pytest. Pytest поставляется с мощными функциями по умолчанию, такими как подробный вывод ошибок тестов и простой API. Он также интегрируется с Django, Jupyter и множеством других инструментов Python.

poetry add pytest --group dev

Заранее планируйте успешное тестирование в вашем проекте.

1. Используйте тестовый фреймворк. В Python их несколько, но я настоятельно рекомендую использовать Pytest. Использование тестового фреймворка облегчает написание и управление вашими тестами.
2. Напишите тесты для каждой функции и метода. Напишите тесты для каждой функции и метода в вашей кодовой базе, чтобы убедиться, что они работают так, как задумано. Это упрощает выявление и устранение проблем в вашей кодовой базе при изменениях.
3. Используйте описательные имена тестов. Дайте каждому тесту имя, отражающее, что он тестирует (например, test_user_can_authenticate). Это облегчит понимание того, что делает каждый тест и поможет быстрее выявлять проблемы.
4. Используйте методы настройки (setup) и завершения (teardown). Используйте методы настройки и завершения, чтобы подготовить необходимые фикстуры для тестов и убрать следы после каждого теста. Это гарантирует, что тесты запускаются в чистой среде, и нет остаточных эффектов от предыдущих тестов.
5. Организуйте ваши тесты в тестовые наборы. Группируйте тесты в тестовые наборы в зависимости от их назначения или функционала. Это упростит запуск конкретных тестов (или групп тестов) и поможет быстрее выявлять проблемы.

Непрерывная интеграция и развертывание (CI/CD)

Непрерывная интеграция (CI) и непрерывное развертывание (CD) — это процессы, автоматизирующие создание, тестирование и развертывание изменений в коде. CI — это процесс автоматического создания и тестирования изменений в коде сразу после их коммита в репозиторий кода. CD — это процесс автоматического развертывания изменений в коде на производственные или тестовые среды после успешного прохождения тестов CI.

CI/CD (вместе как концепция) важны, потому что они выявляют проблемы на ранних этапах разработки и обеспечивают безопасность развертывания изменений в производственную среду. Ключевым моментом успеха является автоматизация создания, тестирования и развертывания изменений. Разработчикам не нужно запоминать вручную применять эти процессы после каждого изменения, и им не приходится выбирать. Это происходит автоматически и без лишних усилий.

Существует множество инструментов CI/CD, и лучший для вашего случая, вероятно, будет тот, который наиболее тесно интегрирован с вашим провайдером Git (GitHub, GitLab, Bitbucket и др.). Процесс одинаков для любой платформы.

1. Запланируйте вашу CI/CD-программу. Это обычно выглядит как «Создание → Тестирование → Развертывание». Некоторые из этих шагов могут содержать несколько подшагов. Например, шаг «Тестирование» может включать «Модульные тесты», «Интеграционные тесты» и «Проверки линтера».
2. Определите вашу программу в файлах конфигурации. Эти файлы фиксируются в вашем проекте и представляют собой кодовые определения вашей CI/CD-программы. Сделайте их читаемыми! Ознакомьтесь с документацией по GitHub Actions, GitLab Pipelines или CircleCI. Существуют и другие отличные проекты.
3. Проверьте вашу программу, внося изменения в код. Проверка вашей конфигурации обычно означает ее запуск с помощью новых коммитов в вашем проекте. Проверьте, что вывод соответствует вашим ожиданиям, и при необходимости внесите коррективы в конфигурационные файлы.