search

Studio-Yandex-Practicum / adaptive_hockey_federation

Сервис Федерации Адаптивного Хоккея
8 stars 6 forks source link

readme

Федерация Адаптивного Хоккея

Описание

Проект для Федерации адаптивного хоккея

Содержание

  1. БРИФ

1.1. Инструкции и ритуалы на проекте

1.2. ER - диаграмма сущностей

1.3. Референс

1.4. Дизайн

1.5. Диаграмма обработки видео игроков

1.6. Спецификация требований от аналитиков

  1. О проекте

2.1. Структура проекта

2.2. Используемых технологий в проекте

  1. Подготовка к запуску

3.1. Правила работы с git

3.2. Настройка poetry

3.3. Настройка pre-commit

3.4. Настройка переменных окружения

  1. Запуск приложения

4.1. Запуск проекта локально

4.2. Запуск в Docker

4.3. Запуск Celery локально

  1. Требования к тестам

  2. Работа с API

  3. Работа с Celery

  4. Имитация сервера DS (временный раздел)



2. О проекте

2.1 Структура проекта

| Имя | Описание |

| ------------- | ------------- |

| infrastructure | Docker-compose файлы для запуска проекта с помощью Docker |

| adaptive_hockey_federation | основной код приложения |

2.2 Используемые технологии в проекте:

Python

Poetry

Pre-commit

Django

Docker

Postgres

Celery

3. Подготовка к запуску

Примечание: для работы над проектом необходим Python не ниже версии 3.11.

Также необходимо установить Poetry (не ниже 1.5.0) и pre-commit.

3.1. Правила работы с git (как делать коммиты и pull request-ы):

  1. Две основные ветки: master и dev

  2. Ветка dev — “предрелизная”. Т.е. здесь должен быть рабочий и выверенный код

  3. Создавая новую ветку, наследуйтесь от ветки dev

  4. В master находится только production-ready код (CI/CD)

  5. Правила именования веток

  1. Пушим свою ветку в репозиторий и открываем Pull Request

  2. ВАЖНО! К таске из Projects привязываем свой Pull Request

3.2. Poetry (инструмент для работы с виртуальным окружением и сборки пакетов):

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

Как скачать и установить? ### Установка: Установите poetry, не ниже версии 1.5.0 следуя [инструкции с официального сайта](https://python-poetry.org/docs/#installation).
Команды для установки: Если у Вас уже установлен менеджер пакетов pip, то можно установить командой: ```bash > *pip install poetry==1.5.0* ``` Если по каким-то причинам через pip не устанавливается, то для UNIX-систем и Bash on Windows вводим в консоль следующую команду: ```bash > *curl -sSL https://install.python-poetry.org | python -* ``` Для WINDOWS PowerShell: ```pwsh > *(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -* ```

После установки перезапустите оболочку и введите команду ```bash > poetry --version ``` Если установка прошла успешно, вы получите ответ в формате > Poetry (version 1.5.0) P.S.: Если при попытке проверить версию возникает ошибка об отсутствии исполняемого файла (poetry), необходимо после установки добавить его в Path Вашей системы (пути указаны по ссылке на официальную инструкцию по установке чуть выше.) Для дальнейшей работы введите команду: ```bash > poetry config virtualenvs.in-project true ``` Выполнение данной команды необходимо для создания виртуального окружения в папке проекта. После предыдущей команды создаём виртуальное окружение нашего проекта с помощью команды: ```bash > poetry install ``` Результатом выполнения команды станет создание в корне проекта папки .venv. Зависимости для создания окружения берутся из файлов poetry.lock (приоритетнее) и pyproject.toml Для добавления новой зависимости в окружение необходимо выполнить команду ```bash > poetry add ``` _Пример использования:_ ```bash > poetry add starlette ``` Также poetry позволяет разделять зависимости необходимые для разработки, от основных. Для добавления зависимости необходимой для разработки и тестирования необходимо добавить флаг ***--dev*** ```bash > poetry add --dev ``` _Пример использования:_ ```bash > poetry add pytest --dev ```
Порядок работы после настройки
Чтобы активировать виртуальное окружение, введите команду: ```bash > poetry shell ``` Существует возможность запуска скриптов и команд с помощью команды без активации окружения: ```bash > poetry run .py ``` _Примеры:_ ```bash > poetry run python script_name>.py > > poetry run pytest > > poetry run black ``` Порядок работы в оболочке не меняется. Пример команды для Win: ```bash > python src\run_bot.py ``` Доступен стандартный метод работы с активацией окружения в терминале с помощью команд: Для WINDOWS: ```pwsh > source .venv/Scripts/activate ``` Для UNIX: ```bash > source .venv/bin/activate ```

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

Подробнее: https://python-poetry.org/docs/cli/

Активировать виртуальное окружение


poetry  shell

Добавить зависимость


poetry  add <package_name>

Обновить зависимости


poetry  update

3.3. Pre-commit (инструмент автоматического запуска различных проверок перед выполнением коммита):

Настройка pre-commit
1. Убедиться, что pre-comit установлен: ```bash pre-commit --version ``` 2. Настроить git hook скрипт: ```bash pre-commit install ``` Далее при каждом коммите у вас будет происходить автоматическая проверка линтером, а так же будет происходить автоматическое приведение к единому стилю.

3.4. Настройка переменных окружения

Перед запуском проекта необходимо создать копию файла

.env.example, назвав его .env и установить значение токена бота, базы данных почты и тд.

4. Запуск приложения

Клонировать репозиторий

git  clone  https://github.com/Studio-Yandex-Practicum/adaptive_hockey_federation.git
Перейти в директорию

cd  adaptive_hockey_federation

4.1. Запуск проекта локально

Для удобного пользования проектом на локальном компьютере, реализованы короткие make команды.

  1. После клонирования проекта перейдите в корневую директорию проекта при помощи консоли.

    cd  adaptive_hockey_federation

  2. Запустить локально контейнер postgres/redis (если не запущен)

    make start-db

  3. Для быстрого развёртывания проекта воспользуйтесь командой:

    make init-app

    Скрипт сам соберёт статику, применит к базе готовые миграции и инициализирует создание супер-юзера, вам только понадобится ввести его данные.

  4. Для запуска локального сервера используйте команду:

    make run

  5. Если в модели были внесены изменения воспользуйтесь командой:

    make makemigrations

    Будут созданы свежие миграции и сразу применены к базе данных.

  6. Для минимальной работы celery (из директории с manage.py)

    poetry run celery -A core worker -Q process_queue,slice_player_video_queue -l INFO -P solo

    Более подробно со всеми возможностями можно ознакомится при помощи команды help:

    make help

4.2. Запуск проекта в Docker

Собрать образ и запустить приложение из Dockerfile


docker  build  -t  adaptive-hockey-federation  .

docker  run  --name  adaptive-hockey-federation  -it  -p  8000:8000  adaptive-hockey-federation

Собрать приложения в контейнеры при помощи Docker-compose:


docker-compose  up  -d  --build

Django-проект и Nginx запустятся в контейнерах, при помощи инструкций в entrypoint.sh через 10 секунд добавится статика

4.3. Запуск Celery локально

Для этого прилагается видео инструкция, которую можно посмотреть тут.

5. Требования к тестам

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

Все тесты запускаются командой:


pytest

Или


make pytest

Выборочно тесты запускаются с указанием выбранного файла:


pytest test_start.py

Написание тестов

Для написания тестов используется pytest.

Фикстуры хранятся в файле tests/conftest.py

Основные тесты хранятся в директории tests.

В зависимости от функционала тестов можно добавлять файлы тестов.

Файлы тестов должны начинаться с "test_".

Что необходимо тестировать

Разработчик самостоятельно определяет функционал, который будет покрыт

данными. Но, как правило, рекомендуется тестировать все написанные

самостоятельно основные вьюхи, функции отправки и получения сообщений,

функции перенаправления на сторонние или внутренние ресурсы.

Рекомендации к написанию кода Codestyle

6. Работа с API

Доступ к документации API осуществляется по ссылкке (локальный доступ):

Раздел будет обновляться.

http://127.0.0.1:8000/api/docs/

Для корректного выполнения запросов из Swagger необходимов нажать кнопку Authorize

и ввести API ключ.

При выполнении прямых запросов к эндпоинтам, необходимо добавить в заголовок запроса

ключ X-API-KEY со значением API ключа.

API ключ вынесен в .env.example файл. Для удобства работы в локальной среде

установлено значение по умолчанию.

6. Работа с Celery

Раздел будет обновляться.

настройка интеграции с django.

core.config.base_settings.py - настройка брокера и бекэнда используемого celery

конфиги для воркеров, очередей, тасков, приоритетов и т.д.

core.celery.py

Воркер запускается в составе команды make run с использованием команды:

poetry run celery -A core worker -P solo -l info

core - имя экзепляра Сelery(). Флаг -P solo определяет, что каждый таск из очереди будет передаваться по одному. Так же есть geevent, group см. документацию.

опциональные флаги:

-l INFO -  если требуются логи
-Q <имена очередей через запятую без пробелов> - если нужно указать воркеру какие очереди он обслуживает. Поумолчанию "default"
-n <имя воркера@%h> - передается имя воркера, если запускается больше 1 воркера. поумолчанию "celery"
    см. документацию https://docs.celeryq.dev/en/stable/userguide/workers.html

В составе команды make run также запускается пользовательский интерфейс по отслеживанию за работой воркеров. Для запуска пользовательского интерфейса используется команда:

poetry run celery -A core flower

По умолчанию запускается на

http://127.0.0.1:5555

6. Имитация сервера DS (временный раздел)

Для запуска имитации сервера DS:

make ds-mock

Сервер запустится по адресу 127.0.0.1:8010

Задержку "распознавания" можно изменить в константе DELAY в файле service/tasks.py.