Проект для Федерации адаптивного хоккея
1.1. Инструкции и ритуалы на проекте
1.3. Референс
1.4. Дизайн
2.1. Структура проекта
2.2. Используемых технологий в проекте
3.1. Правила работы с git
3.2. Настройка poetry
3.3. Настройка pre-commit
3.4. Настройка переменных окружения
4.2. Запуск в Docker
4.3. Парсинг файлов
| Имя | Описание |
| ------------- | ------------- |
| 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 секунд добавится статика
Файлы документов для парсинга копируем в директорию /<корневая директория>/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
Все тесты запускаются командой:
pytest
Или
make run_tests
Выборочно тесты запускаются с указанием выбранного файла:
pytest test_start.py
Или
make run_unit_tests
Для написания тестов используется pytest.
Фикстуры хранятся в файле tests/conftest.py
Основные тесты хранятся в директории tests.
В зависимости от функционала тестов можно добавлять файлы тестов.
Файлы тестов должны начинаться с "test_".
Разработчик самостоятельно определяет функционал, который будет покрыт
данными. Но, как правило, рекомендуется тестировать все написанные
самостоятельно основные вьюхи, функции отправки и получения сообщений,
функции перенаправления на сторонние или внутренние ресурсы.