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

Описание

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

Содержание

1. БРИФ

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

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

1.3. Референс

1.4. Дизайн

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. Парсинг файлов

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

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 секунд добавится статика

4.3. Парсинг файлов

Файлы документов для парсинга копируем в директорию /<корневая директория>/adaptive_hockey_federation/resourses/

Файлы документов для парсинга скачивать с [Google Диска] доступ выдается при добавлении в проект и самый важный файл Числовые статусы следж-хоккей 02.10.203.docx доступ выдается при добавлении в проект

Запуск парсера документов для заполнения БД производится из корневой директории, короткой командой:

make fill-db

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

poetry run parser -r -p  adaptive_hockey_federation/resourses/

Результат парсинга сохранится в директории /<корневая директория>/adaptive_hockey_federation/core/fixtures/ в файле

Из data.json автоматически загрузятся распарсенные данные в таблицы main_player main_staffmember main_staffteammember

Загрузка реальных данных из файлов документов в формате JSON. Внимание! Перед загрузкой файлов из JSON базы и сиквенсы очищаются. Файлы документов в формате JSON получать у Тимлида проекта в виде архива.

make fill-db -f

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

cd ```/<корневая директория>/adaptive_hockey_federation/```
python3 manage.py fill-db -f

Опциональные параметры: -f, --fixtures - Загрузка реальных данных из файлов документов в формате JSON. Внимание! Перед загрузкой файлов из JSON базы и сиквенсы очищаются. Файлы документов в формате JSON получать у Тимлида проекта в виде архива.

-p, --path - Путь до директории с документами. -h, --help - Вызов справки.

!!!Необходимо скопировать папку с файлами в контейнер или примонтировать через -volume

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

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

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

pytest

Или

make  run_tests

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

pytest  test_start.py

Или

make  run_unit_tests

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

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

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

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

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

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

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

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

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

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

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

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