Проект для Федерации адаптивного хоккея
1.1. Инструкции и ритуалы на проекте
1.3. Референс
1.4. Дизайн
1.5. Диаграмма обработки видео игроков
1.6. Спецификация требований от аналитиков
2.1. Структура проекта
2.2. Используемых технологий в проекте
3.1. Правила работы с git
3.2. Настройка poetry
3.3. Настройка pre-commit
3.4. Настройка переменных окружения
4.2. Запуск в Docker
| Имя | Описание |
| ------------- | ------------- |
| infrastructure | Docker-compose файлы для запуска проекта с помощью Docker |
| adaptive_hockey_federation | основной код приложения |
Примечание: для работы над проектом необходим Python не ниже версии 3.11.
Также необходимо установить Poetry (не ниже 1.5.0) и pre-commit.
-
Две основные ветки:
master
иdev
-
Ветка
dev
— “предрелизная”. Т.е. здесь должен быть рабочий и выверенный код -
Создавая новую ветку, наследуйтесь от ветки
dev
-
В
master
находится только production-ready код (CI/CD) -
Правила именования веток
-
весь новый функционал —
feature/название-функционала
-
исправление ошибок —
bugfix/название-багфикса
-
Пушим свою ветку в репозиторий и открываем Pull Request
-
ВАЖНО! К таске из Projects привязываем свой Pull Request
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
Настройка pre-commit
- Убедиться, что pre-comit установлен:
pre-commit --version
- Настроить git hook скрипт:
pre-commit install
Далее при каждом коммите у вас будет происходить автоматическая проверка линтером, а так же будет происходить автоматическое приведение к единому стилю.
Перед запуском проекта необходимо создать копию файла
.env.example
, назвав его .env
и установить значение токена бота, базы данных почты и тд.
git clone https://github.com/Studio-Yandex-Practicum/adaptive_hockey_federation.git
cd adaptive_hockey_federation
Для удобного пользования проектом на локальном компьютере, реализованы короткие make команды.
- После клонирования проекта перейдите в корневую директорию проекта при помощи консоли.
cd adaptive_hockey_federation
- Запустить локально контейнер postgres (если не запущен)
make start-db
- Для быстрого развёртывания проекта воспользуйтесь командой:
make init-app
Скрипт сам соберёт статику, применит к базе готовые миграции и инициализирует создание супер-юзера, вам только понадобится ввести его данные. 4. Для запуска локального сервера используйте команду:
make run
- Если в модели были внесены изменения воспользуйтесь командой:
make makemigrations
Будут созданы свежие миграции и сразу применены к базе данных.
Более подробно со всеми возможностями можно ознакомится при помощи команды help:
make help
Собрать образ и запустить приложение из 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 секунд добавится статика
Все тесты запускаются командой:
pytest
Или
make pytest
Выборочно тесты запускаются с указанием выбранного файла:
pytest test_start.py
Для написания тестов используется pytest.
Фикстуры хранятся в файле tests/conftest.py
Основные тесты хранятся в директории tests.
В зависимости от функционала тестов можно добавлять файлы тестов.
Файлы тестов должны начинаться с "test_".
Разработчик самостоятельно определяет функционал, который будет покрыт
данными. Но, как правило, рекомендуется тестировать все написанные
самостоятельно основные вьюхи, функции отправки и получения сообщений,
функции перенаправления на сторонние или внутренние ресурсы.
Рекомендации к написанию кода Codestyle
Раздел будет обновляться.
http://127.0.0.1:8000/api/docs/
Для корректного выполнения запросов из Swagger необходимов нажать кнопку Authorize
и ввести API ключ.
При выполнении прямых запросов к эндпоинтам, необходимо добавить в заголовок запроса
ключ X-API-KEY
со значением API ключа.
API ключ вынесен в .env.example
файл. Для удобства работы в локальной среде
установлено значение по умолчанию.
Для запуска имитации сервера DS:
make ds-mock
Сервер запустится по адресу 127.0.0.1:8010
Задержку "распознавания" можно изменить в константе DELAY в файле service/tasks.py.