В данном шаблоне используется Python3.9, однако вы можете использовать и другие версии, если хотите. Но мы не гарантируем, что все будет работать.
Make - это очень популярная утилита,
предназначенная для преобразования одних файлов в другие через определенную последовательность команд.
Однако ее можно использовать для исполнения произвольных последовательностей команд.
Команды и правила их исполнения прописываются в Makefile.
Мы будем активно использовать make в данном проекте, поэтому рекомендуем познакомится с ней поближе.
На MacOS и *nix системах make обычно идет в комплекте или ее можно легко установить.
Некоторые варианты, как можно поставить make на Windows,
описаны здесь.
Poetry - это удобный инструмент для работы с зависимостями в Python. Мы будем использовать его для подготовки окружения.
Поэтому перед началом работы необходимо выполнить шаги по установке.
Мы будем работать в виртуальном окружении, которое создадим специально для данного проекта. Если вы не знакомы с концепцией виртуальных окружений в Python, обязательно познакомьтесь. Мы рекомендуем использовать отдельное виртуальное окружение для каждого вашего проекта.
Выполните команду
make setup
Будет создано новое виртуальное окружение в папке .venv.
В него будут установлены пакеты, перечисленные в файле pyproject.toml.
Обратите внимание: если вы один раз выполнили make setup, при попытке повторного ее выполнения ничего не произойдет,
поскольку единственная ее зависимость - директория .venv - уже существует.
Если вам по какой-то причине нужно пересобрать окружение с нуля,
выполните сначала команду make clean - она удалит старое окружение.
Для установки новых пакетов используйте команду poetry add, для удаления - poetry remove.
Мы не рекомендуем вручную редактировать секцию с зависимостями в pyproject.toml.
Командой make format можно запустить автоматическое форматирование вашего кода.
Ее выполнение приведет к запуску isort - утилиты
для сортировки импортов в нужном порядке, и black - одного из самых популярных форматтеров для Python.
Командой make lint вы запустите проверку линтерами - инструментами для статического анализа кода.
Они помогают выявить ошибки в коде еще до его запуска, а также обнаруживают несоответствия стандарту
PEP8.
Среди линтеров есть те же isort и black, только в данном случае они уже ничего не исправляют, а просто проверяют, что код отформатирован правильно.
Командой make test вы запустите тесты при помощи утилиты pytest.
python main.py
Приложение запустится локально, в одном процессе.
Хост и порт по умолчанию: 127.0.0.1 и 8080.
Их можно изменить через переменные окружения HOST и PORT.
Управляет процессом легковесный ASGI server uvicorn.
Обратите внимание: для запуска нужно использовать python из окружения проекта.
uvicorn main:app
Очень похож на предыдущий, только запуск идет напрямую. Хост и порт можно передать через аргументы командной строки.
Обратите внимание: для запуска нужно использовать uvicorn из окружения проекта.
gunicorn main:app -c gunicorn.config.py
Способ похож на предыдущий, только вместо uvicorn используется
более функциональный сервер gunicorn (uvicorn используется внутри него).
Параметры задаются через конфиг, хост и порт можно задать
через переменные окружения или аргументы командной строки.
Сервис запускается в несколько параллельных процессов, по умолчанию их число равно числу ядер процессора.
Обратите внимание: для запуска нужно использовать gunicorn из окружения проекта.
Делаем все то же самое, но внутри docker-контейнера. Если вы не знакомы с docker, обязательно познакомьтесь.
Внутри контейнера можно использовать любой из способов, описанных выше.
В продакшене рекомендуется использовать gunicorn.
Собрать и запустить образ можно командой
make run
Когда вы выполняете какое-то действие (прописанное в конфиге), запускается процесс CI.
Что именно происходит в этом процессе и как он триггерится,
описывается в специальных .yaml/.yml конфигах в папке .github/workflows.
Сейчас там есть только один конфиг test.yml, который запускает процесс, в котором создается виртуальное окружение,
прогоняются линтеры и тесты. Если что-то пошло не так, процесс падает с ошибкой и в Github появляется красный крестик.
Вам нужно посмотреть логи, исправить ошибку и запушить изменения.
Этот процесс тригеррится при создании и обновлении пулл-реквеста, а также по пушу в master.