FastAPI + Redis PubSub Template

Оглавление

• Разворачивание проекта
  • Зависимости
  • Окружение
  • Запуск в локальном окружении
  • Запуск в тестовом окружении
  • Запуск в прод окружении
  • После запуска
  • Возможные ошибки
• Стэк
  • Основные инструменты
  • Другие библиотеки / интеграции
• Запуск тестов
  • Внутри Docker-контейнера (рекомендуется)
  • Вне Docker-контейнера
• Запуск flake8
  • Внутри Docker-контейнера (рекомендуется)
  • Вне Docker-контейнера
• Запуск mypy
  • Внутри Docker-контейнера (рекомендуется)
  • Вне Docker-контейнера
• Разработка
  • Миграции
  • Форматирование кода
  • Git хуки

Разворачивание проекта

Зависимости

• docker
• docker compose
• python 3.8+ (опционально, для локального запуска pytest/flake8/mypy)
• poetry (опционально, для локального запуска pytest/flake8/mypy)

Окружение

Перед запуском контейнеров, необходимо убедиться, что в корневой директории проекта присутствует файл .env, в котором заполнены все необходимые переменные окружения.
Названия этих переменных можно посмотреть в .env.example

Подробное описание переменных окружения

PROJECT_NAME

Название проекта

DEBUG

Режим отладки
0 - выключен
1 - включен
Если включен, то:

• 500 ошибки сервера не будут обработаны обработчиком исключений
• В логах будут отображаться запросы в БД, генерируемые в рамках запроса

PROD

Режим прод окружения
0 - выключен
1 - включен
Если выключен, то:

• Будет доступна документация swagger-ui/redoc
• Работа с платежными системами будет работать в боевом режиме
• Чувствительные данные будут исключены из логов

MEDIA_PATH

Путь к директории, в которой хранятся медиа-файлы

MEDIA_URL

Префикс в ссылке для медиа-файлов

STATIC_PATH

Путь к директории, в которой хранятся статические файлы

STATIC_URL

Префикс в ссылке для статических-файлов

LOG_PATH

Путь к директории, в которой хранятся лог-файлы

Redis

REDIS_HOST должен соответствовать названию сервиса Redis из compose конфигурации
REDIS_PORT - любой доступный на хосте порт

Запуск в локальном окружении

docker-compose -f docker-compose.local.yml up

или

make localup

После запуска проект будет доступен по адресу http://localhost:.../

Запуск в тестовом окружении

docker-compose -f docker-compose.develop.yml up

или

make developup

После запуска

Проект станет доступен по порту ...
В локальном окружении достаточно перейти по адресу http://localhost:.../
В другом окружении необходимо настроить домен, при обращении к которому веб-сервер (Nginx/Apache) будет проксировать все запросы на порт ...

Возможные ошибки

Если на хосте установлена docker compose версии >2, то может возникнуть ошибка синтаксиса команды. В таком случае в командах выше нужно заменить

docker-compose

на

docker compose

Стэк

Основные инструменты

• Используемый язык программирования — Python ...
• Используемый фреймворк — FastAPI ...
• Используемый инструмент для реализации PubSub — Redis ...

Другие библиотеки / интеграции

• uvicorn (...) — HTTP-сервер для FastAPI
• redis (...) — библиотека для работы с Redis в Python
• websockets (...) - библиотека для работы с websocket-соединениями
• JSON-log-formatter (...) — библиотека для форматирования логов в JSON-формате
• dependency-injector (...) — библиотека для внедрения зависимостей (DI)
• pytest (...) — библиотека для тестирования
• pytest-cov (...) — библиотека для оценки покрытия кода тестами через pytest
• pytest-mock (...) — библиотека для мока зависимостей через pytest
• pytest-timeout (...) — библиотека для ограничения времени выполнения тестов через pytest
• pytest-asyncio (...) — библиотека для тестирования асинхронного кода
• concurrent-log-handler (...) — библиотека для последовательной записи логов в файлы при запуске веб приложения через несколько воркеров (как в uvicorn)
• mypy (...) — статический анализатор типов
• flake8 (...) — инструмент линтинга для Python
• black (...) — библиотека для форматирования кода на языке Python
• isort (...) - библиотека для сортировки импортов

Запуск тестов

Внутри Docker-контейнера (рекомендуется)

1. Зайти в контейнер asgi через команду

   docker exec -it asgi bash

2. Начать выполнение тестов через команду

   pytest

или

make test

Вне Docker-контейнера

При таком запуске тесты, в которых тестируется работа с БД, выполнятся с ошибкой
При ошибке выполнения команды запустите тесты внутри Docker-контейнера

1. Перейти в директорию с конфигурационным файлом

2. Начать выполнение тестов через команду

   poetry run pytest

Запуск Flake8

Внутри Docker-контейнера (рекомендуется)

1. Зайти в контейнер asgi через команду

   docker exec -it asgi bash

2. Начать выполнение flake8 через команду

   flake8 .

или

make flake8

Вне Docker-контейнера

1. Перейти в директорию с конфигурационным файлом

2. Начать выполнение flake8 через команду

   poetry run flake8 .

Запуск mypy

Внутри Docker-контейнера (рекомендуется)

1. Зайти в контейнер asgi через команду

   docker exec -it asgi bash

2. Начать выполнение mypy через команду

   mypy .

или

make mypy

Вне Docker-контейнера

При возникновении ошибок запуск возможен только внутри Docker-контейнера

1. Перейти в директорию с конфигурационным файлом

2. Начать выполнение mypy через команду

   poetry run mypy .

Разработка

Миграции

Создание миграции

docker exec -it asgi alembic revision -m "Message"

или

make makemigrations MESSAGE="Message"

Выполнение миграций

docker exec -it asgi alembic upgrade head

или

make migrate

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

При разработке рекомендуется использовать black, чтобы поддерживать чистоту кода и избегать лишних изменений при работе с гитом.
Пример конфигурационного файла для Visual Studio Code .vscode/settings.json:

{
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": true
    }
}

Git хуки

При разработке рекомендуется использовать pre-commit, чтобы перед формированием МР код был уже подготовленным и поверхностно проверенным (например, через flake8)

Для использования должны быть установлены dev-зависимости

Pre-commit хуки

Установка

poetry run pre-commit install

Удаление

poetry run pre-commit uninstall

После установки, при каждом коммите будут отрабатывать хуки из конфигурационного файла, предназначенные для коммитов (stages: [commit])

Pre-push хуки

Установка

poetry run pre-commit install --hook-type pre-push

Удаление

poetry run pre-commit uninstall -t pre-push

После установки, при каждом пуше будут отрабатывать хуки из конфигурационного файла, предназначенные для пушей (stages: [push])