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

Описание

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

Содержание

1. БРИФ

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

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

1.3. Референс

1.4. Дизайн

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

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

2. О проекте

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

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

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

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

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

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

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

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

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

4.2. Запуск в Docker

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

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

6. Работа с API

7. Работа с Celery

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

2. О проекте

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

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

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

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

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

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

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. Правила именования веток

• весь новый функционал — feature/название-функционала

• исправление ошибок — bugfix/название-багфикса

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

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

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

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

Как скачать и установить?

Установка:

Установите poetry, не ниже версии 1.5.0 следуя инструкции с официального сайта.

Команды для установки:

Если у Вас уже установлен менеджер пакетов pip, то можно установить командой:

>  *pip install poetry==1.5.0*

Если по каким-то причинам через pip не устанавливается,

то для UNIX-систем и Bash on Windows вводим в консоль следующую команду:

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

Для WINDOWS PowerShell:

>  *(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -*

После установки перезапустите оболочку и введите команду

> poetry --version

Если установка прошла успешно, вы получите ответ в формате

Poetry (version 1.5.0)

P.S.: Если при попытке проверить версию возникает ошибка об отсутствии исполняемого файла

(poetry), необходимо после установки добавить его в Path Вашей системы

(пути указаны по ссылке на официальную инструкцию по установке чуть выше.)

Для дальнейшей работы введите команду:

> poetry config virtualenvs.in-project true

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

папке проекта.

После предыдущей команды создаём виртуальное окружение нашего проекта с

помощью команды:

> poetry install

Результатом выполнения команды станет создание в корне проекта папки .venv.

Зависимости для создания окружения берутся из файлов poetry.lock (приоритетнее)

и pyproject.toml

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

> poetry add <package_name>

Пример использования:

> poetry add starlette

Также poetry позволяет разделять зависимости необходимые для разработки, от

основных.

Для добавления зависимости необходимой для разработки и тестирования необходимо

добавить флаг --dev

> poetry add <package_name> --dev

Пример использования:

> poetry add pytest --dev

Порядок работы после настройки

Чтобы активировать виртуальное окружение, введите команду:

> poetry shell

Существует возможность запуска скриптов и команд с помощью команды без

активации окружения:

> poetry run <script_name>.py

Примеры:

> poetry run python script_name>.py

>

> poetry run pytest

>

> poetry run black

Порядок работы в оболочке не меняется. Пример команды для Win:

> python src\run_bot.py

Доступен стандартный метод работы с активацией окружения в терминале с помощью команд:

Для WINDOWS:

> source .venv/Scripts/activate

Для UNIX:

> 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 установлен:

pre-commit  --version

2. Настроить git hook скрипт:

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 (если не запущен)

make start-db

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

make init-app

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

make run

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

make makemigrations

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

Более подробно со всеми возможностями можно ознакомится при помощи команды 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 секунд добавится статика

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 файл. Для удобства работы в локальной среде

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

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

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

make ds-mock

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

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