From 56bf380828b1be53dbb16edff9399d8e3d635948 Mon Sep 17 00:00:00 2001 From: Ivan Filippov Date: Thu, 14 Dec 2023 22:34:10 +0500 Subject: [PATCH] refactoring readme.md --- README.md | 500 +++++++++++++++--- .../adaptive_hockey_federation/settings.py | 1 - .../core/management/commands/fill-db.py | 4 +- 3 files changed, 433 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 4dc1d3a6..3cf07884 100644 --- a/README.md +++ b/README.md @@ -1,356 +1,718 @@ + # Федерация Адаптивного Хоккея + + #### Описание -Проект для [Федерации адаптивного хоккея](https://paraicehockey.ru/) + +Проект для [Федерации адаптивного хоккея](https://paraicehockey.ru/) + + # Содержание + + 1. [БРИФ](https://docs.google.com/document/d/1iHkA4Al-H-ppALPJDLMhb_Dl-ciRHH2npM6YRa2HQwg/edit) - 1.1. [Инструкции и ритуалы на проекте](docs/materials/instructions.md) + + +1.1. [Инструкции и ритуалы на проекте](docs/materials/instructions.md) + + + +1.2. [ER - диаграмма сущностей](docs/) + + - 1.2. [ER - диаграмма сущностей](docs/) +1.3. [Референс](https://www.youtube.com/watch?v=b0LMWiSynQs) - 1.3. [Референс](https://www.youtube.com/watch?v=b0LMWiSynQs) + - 1.4. [Дизайн](https://www.figma.com/file/8uPoOvMuuJ8hMKASk7hog2/Hokei?type=design&node-id=0-1&mode=design) +1.4. [Дизайн](https://www.figma.com/file/8uPoOvMuuJ8hMKASk7hog2/Hokei?type=design&node-id=0-1&mode=design) + + 2. [О проекте](#project) - 2.1. [Структура проекта](#structure) + + +2.1. [Структура проекта](#structure) + + + +2.2. [Используемых технологий в проекте](#technologies-project) - 2.2. [Используемых технологий в проекте](#technologies-project) + 3. [Подготовка к запуску](#start) - 3.1. [Правила работы с git](#git) + + +3.1. [Правила работы с git](#git) + + + +3.2. [Настройка poetry](#poetry) - 3.2. [Настройка poetry](#poetry) + - 3.3. [Настройка pre-commit](#pre-commit) +3.3. [Настройка pre-commit](#pre-commit) - 3.4. [Настройка переменных окружения](#env) + + +3.4. [Настройка переменных окружения](#env) + + 4. [Запуск приложения](#run-app) - 4.1. [Запуск проекта локально](#run-local) + + +4.1. [Запуск проекта локально](#run-local) + + - 4.2. [Запуск в Docker](#run-docker) +4.2. [Запуск в Docker](#run-docker) - 4.3. [Парсинг файлов](#parsing) + + +4.3. [Парсинг файлов](#parsing) + + 5. [Требования к тестам](#test-app) + +

+ + # 2. О проекте + + ## 2.1 Структура проекта -| Имя | Описание | + + +| Имя | Описание | + | ------------- | ------------- | + | infrastructure | Docker-compose файлы для запуска проекта с помощью Docker | + | adaptive_hockey_federation | основной код приложения | + + ## 2.2 Используемые технологии в проекте: + + [![Python][Python-badge]][Python-url] + [![Poetry][Poetry-badge]][Poetry-url] + [![Pre-commit][Pre-commit-badge]][Pre-commit-url] + [![Django][Django-badge]][Django-url] + [![Docker][Docker-badge]][Docker-url] + [![Postgres][Postgres-badge]][Postgres-url] + + # 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/название-багфикса` + +- весь новый функционал — `feature/название-функционала` + +- исправление ошибок — `bugfix/название-багфикса` + 6. Пушим свою ветку в репозиторий и открываем Pull Request + 7. ВАЖНО! К таске из Projects привязываем свой Pull Request + + ## 3.2. Poetry (инструмент для работы с виртуальным окружением и сборки пакетов): + + Poetry - это инструмент для управления зависимостями и виртуальными окружениями, также может использоваться для сборки пакетов. В этом проекте Poetry необходим для дальнейшей разработки приложения, его установка обязательна.
+ +
- - Как скачать и установить? - + + + +Как скачать и установить? + + + + ### Установка: + + Установите poetry, не ниже версии 1.5.0 следуя [инструкции с официального сайта](https://python-poetry.org/docs/#installation). +
- - Команды для установки: - + + + +Команды для установки: + + + + Если у Вас уже установлен менеджер пакетов pip, то можно установить командой: -> *pip install poetry==1.5.0* + + +> *pip install poetry==1.5.0* + + Если по каким-то причинам через pip не устанавливается, + то для UNIX-систем и Bash on Windows вводим в консоль следующую команду: -> *curl -sSL https://install.python-poetry.org | python -* + + +> *curl -sSL https://install.python-poetry.org | python -* + + Для WINDOWS PowerShell: -> *(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -* + + +> *(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 + + _Пример использования:_ + + > poetry add starlette + + Также poetry позволяет разделять зависимости необходимые для разработки, от + основных. + Для добавления зависимости необходимой для разработки и тестирования необходимо + добавить флаг ***--dev*** + + > poetry add --dev + + _Пример использования:_ + + > poetry add pytest --dev + +
+ +
- - Порядок работы после настройки - + + + +Порядок работы после настройки + + + +
+ + Чтобы активировать виртуальное окружение, введите команду: + + > poetry shell + + Существует возможность запуска скриптов и команд с помощью команды без + активации окружения: + + > poetry run .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/ + + #### Активировать виртуальное окружение + ```shell -poetry shell + +poetry shell + ``` + + #### Добавить зависимость + ```shell -poetry add + +poetry add + ``` + + #### Обновить зависимости + ```shell -poetry update + +poetry update + ``` + ## 3.3. Pre-commit (инструмент автоматического запуска различных проверок перед выполнением коммита): + +
- - Настройка pre-commit - + + + +Настройка pre-commit + + +
+ 1. Убедиться, что pre-comit установлен: - ```shell - pre-commit --version - ``` + + +```shell + +pre-commit --version + +``` + 2. Настроить git hook скрипт: - ```shell - pre-commit install - ``` + + +```shell + +pre-commit install + +``` + + Далее при каждом коммите у вас будет происходить автоматическая проверка + линтером, а так же будет происходить автоматическое приведение к единому стилю. +
+ + ## 3.4. Настройка переменных окружения + + Перед запуском проекта необходимо создать копию файла + ```.env.example```, назвав его ```.env``` и установить значение токена бота, базы данных почты и тд. + + # 4. Запуск приложения + + ##### Клонировать репозиторий + + ```shell -git clone https://github.com/Studio-Yandex-Practicum/adaptive_hockey_federation.git + +git clone https://github.com/Studio-Yandex-Practicum/adaptive_hockey_federation.git + ``` + + ##### Перейти в директорию + + ```shell -cd adaptive_hockey_federation + +cd adaptive_hockey_federation + ``` + + ## 4.1. Запуск проекта локально +Для удобного пользования проектом на локальном компьютере, реализованы короткие make команды. +1. После клонирования проекта перейдите в корневую директорию проекта при помощи консоли. +```bash +cd adaptive_hockey_federation +``` +2. Для быстрого развёртывания проекта воспользуйтесь командой: +```bash +make init-app +``` +Скрипт сам соберёт статику, применит к базе готовые миграции и инициализирует создание супер-юзера, вам только понадобится ввести его данные. +3. Для запуска локального сервера используйте команду: +```bash +make run +``` +4. Если в модели были внесены изменения воспользуйтесь командой: +```bash +make makemigrations +``` +Будут созданы свежие миграции и сразу применены к базе данных. -```shell -cd adaptive_hockey_federation -python manage.py runserver +Более подробно со всеми возможностями можно ознакомится при помощи команды help: +```bash +make help ``` + ## 4.2. Запуск проекта в Docker + + Собрать образ и запустить приложение из Dockerfile + + ```shell -docker build -t adaptive-hockey-federation . -docker run --name adaptive-hockey-federation -it -p 8000:8000 adaptive-hockey-federation + +docker build -t adaptive-hockey-federation . + +docker run --name adaptive-hockey-federation -it -p 8000:8000 adaptive-hockey-federation + ``` + + Собрать приложения в контейнеры при помощи Docker-compose: + + ```shell -docker-compose up -d --build + +docker-compose up -d --build + ``` + + Django-проект и Nginx запустятся в контейнерах, при помощи инструкций в entrypoint.sh через 10 секунд добавится статика + + ## 4.3. Парсинг файлов -```shell -poetry run parser --path + Запуск парсера документов для заполнения БД производится из корневой директории, короткой командой: +```bash +make fill-db ``` -Запуск парсера документов для заполнения БД. +В случае не успешного запуска воспользуйтесь альтернативным способом: +```bash +poetry run parser -r -p adaptive_hockey_federation/resourses/ +``` +Результат парсинга сохранится в директории ```adaptive_hockey_federation/resourses/``` в фале ```result.txt```. Опциональные параметры: ---result Вывод в консоль извлеченных данных и статистики ---help Вызов справки +-r, --result - Вывод в консоль извлеченных данных и статистики +-p, --path - Путь до директории с документами. +-h, --help - Вызов справки. !!!Необходимо скопировать папку с файлами в контейнер или примонтировать через -volume + + # 5. Требования к тестам + + #### Запуск тестов + Все тесты запускаются командой: - ```shell - pytest - ``` - Или +```shell + +pytest + +``` + + + +Или + + + +```shell + +make run_tests + +``` - ```shell - make run_tests - ``` Выборочно тесты запускаются с указанием выбранного файла: - ```shell - pytest test_start.py - ``` - Или +```shell + +pytest test_start.py + +``` + + + +Или - ```shell - make run_unit_tests - ``` + + +```shell + +make run_unit_tests + +``` + + #### Написание тестов + Для написания тестов используется pytest. + Фикстуры хранятся в файле tests/conftest.py + Основные тесты хранятся в директории tests. + В зависимости от функционала тестов можно добавлять файлы тестов. + Файлы тестов должны начинаться с "test_". + + #### Что необходимо тестировать + Разработчик самостоятельно определяет функционал, который будет покрыт + данными. Но, как правило, рекомендуется тестировать все написанные + самостоятельно основные вьюхи, функции отправки и получения сообщений, + функции перенаправления на сторонние или внутренние ресурсы. + + #### Рекомендации к написанию кода [Codestyle](docs/codestyle.md) + + + + [Python-url]: https://www.python.org/downloads/release/python-3110/ + [Python-badge]: https://img.shields.io/badge/python-v3.11-yellow?style=for-the-badge&logo=python + + [Poetry-url]: https://python-poetry.org/ + [Poetry-badge]: https://img.shields.io/badge/poetry-blue?style=for-the-badge&logo=poetry + + [Pre-commit-url]: https://pre-commit.com/ + [Pre-commit-badge]: https://img.shields.io/badge/Pre--commit-teal?style=for-the-badge&logo=precommit + + [Django-url]: https://docs.djangoproject.com/en/4.2/releases/4.2.6/ + [Django-badge]: https://img.shields.io/badge/Django-v4.2.6-008000?logo=django&style=for-the-badge + + [Docker-url]: https://www.docker.com/ + [Docker-badge]: https://img.shields.io/badge/docker-red?style=for-the-badge&logo=docker + + [Postgres-url]: https://www.postgresql.org/ -[Postgres-badge]: https://img.shields.io/badge/postgresql-gray?style=for-the-badge&logo=postgresql + +[Postgres-badge]: https://img.shields.io/badge/postgresql-gray?style=for-the-badge&logo=postgresql \ No newline at end of file diff --git a/adaptive_hockey_federation/adaptive_hockey_federation/settings.py b/adaptive_hockey_federation/adaptive_hockey_federation/settings.py index 06ac2a18..8a697397 100644 --- a/adaptive_hockey_federation/adaptive_hockey_federation/settings.py +++ b/adaptive_hockey_federation/adaptive_hockey_federation/settings.py @@ -90,7 +90,6 @@ MEDIA_ROOT = os.path.join(BASE_DIR, 'media') RESOURSES_ROOT = os.path.join(BASE_DIR, 'resourses') -PARSER_MAIN = os.path.join(BASE_DIR, 'parser/parser.py') DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField' AUTH_USER_MODEL = 'users.User' diff --git a/adaptive_hockey_federation/core/management/commands/fill-db.py b/adaptive_hockey_federation/core/management/commands/fill-db.py index fd154fb8..89439ee9 100644 --- a/adaptive_hockey_federation/core/management/commands/fill-db.py +++ b/adaptive_hockey_federation/core/management/commands/fill-db.py @@ -2,7 +2,7 @@ from django.core.management.base import BaseCommand -from adaptive_hockey_federation.settings import PARSER_MAIN, RESOURSES_ROOT +from adaptive_hockey_federation.settings import RESOURSES_ROOT class Command(BaseCommand): @@ -10,7 +10,7 @@ class Command(BaseCommand): def handle(self, *args, **options): run_parser = subprocess.getoutput( - f'poetry run python {PARSER_MAIN} -r -p {RESOURSES_ROOT}' + f'poetry run parser -r -p {RESOURSES_ROOT}' ) with open( f'{RESOURSES_ROOT}/result.txt',