Local development

First-time setup

1. Создать и активировать виртуальное окружение
2. Запустить из корня репозитория:

pip install -r requirements.txt -r requirements-dev.txt
pre-commit install --install-hooks 

Local setup

Запустить из корня репозитория

uvicorn src.__init__:app --reload --host 0.0.0.0 --port 8000 --reload-delay 0.1

Документация по структуре репозитория

Общая идея структуры кодовой базы -- использование слоевой архитектуры (см Clean Architecture by Uncle Bob) в совокупности с фреймворком FastAPI и ORM. Внешний слой views содержит код для обработки реквестов от публичного апи вебсервера (на данный момент -- только HTTP JSON API). Слой controllers содержит статичные сервисы, которые манипулируют методами и данными моделей ORM для исполнения бизнес-логики. Слой models содержит определения ORM моделей.

• ./docker - сетап docker и docker-compose для локальной разработки. Докер-файлы и конфиг композа, переменные окружения.

  • /example.env - список всех переменных окружения, которые подаются приложению при запуске, и их описание. Не содержит никаких credentials.

  • /local.env - значения переменнных окружения для локальной разработки. Может содержать credentials, исключен из гита.

• ./migrations - директория файлов миграций, внутренности специфично зависят от инструментов

• ./src - исходный код приложения

  • /__init__.py - входная точка для сборки приложения

  • /settings.py - получение параметров запуска через переменные окружения

  • /logging.py - настройка логгирования, overwrite стандартного логгера

  • /views - package для views и раутинга. Отвечает исключительно за трансляцию HTTP API в действия домена.

  • /controllers - package для вызова доменных действий и манипуляции над моделями

  • /models - персистентные модели ORM

• ./tests - тесты различного калибра

  • /unit - юнит-тесты компонентов, внутренняя структура копирует структуру src где это имеет смысл

  • /api - интеграционные тесты всего приложения через апи, внутрення структура следует структуре апи

• ./readme.md - базовая документация проекта, команды для запуска сетапа, тестов, etc. При старте проекта сохранить доку по структуре, но спустить ее вниз.

• ./.gitignore - пути, которые исключены из отслеживания гитом

• ./requirements.txt - зависимости "продовой" сборки приложения, идут в продовый контейнер, стараться минимизировать. Версии пакетов лучше указывать вручную через == или ~= чтобы избегать резолвинга совместимостей через pip и контролировать инъекции зависимостей.

• ./requirements-dev.txt - зависимости для разработки: линтеры, стат-анализаторы, тесты, etc. Не копирует стандартный requirements.txt, а расширяет его -- устанавливать либы из обоих. При надобности можно разделить файлы на зависимости для разработки и пайплайна CI/CD.

• ./.pre-commit-config.yaml -- конфиг для pre-commit.com, автотриггер линтеров перед коммитом

• ./pyproject.toml -- конфиг проекта, но на самом деле конфиг black и isort

• ./.flake8 -- конфиг флейка. Ворнинги флейка нужно анализировать, а не бездумно исполнять / мьютить.