diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index 5b33d36..f08f14c 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -14,23 +14,23 @@ Когда задачи, намеченные на новый релиз проекта выполнены, версия проекта в ветке `develop` ещё раз тестируется и затем происходит слияние ветки `develop` и `main` с git-тегом, указывающим на новую версию проекта. ---- + ## Про Python пакеты проекта. -* Каждый файл `\_\_init\_\_.py` должен содержать в своей первой строке список `\_\_all\_\_ = [...]` с перечислением всех элементов, которые могут быть импортированы из этого пакета. То есть если пакет в своем `\_\_init\_\_.py` содержит 2 различные переменные и импорт 1 класса, которые должны быть из него импортированы, то их названия следует указать в `\_\_all\_\_`. Пакет - директория, содерщая в себе другие директории, Python-модули и имеющая файл `\_\_init\_\_.py`. +* Каждый файл `__init__.py` должен содержать в своей первой строке список `__all__ = [...]` с перечислением всех элементов, которые могут быть импортированы из этого пакета. То есть если пакет в своем `__init__.py` содержит 2 различные переменные и импорт 1 класса, которые должны быть из него импортированы, то их названия следует указать в `__all__`. Пакет - директория, содерщая в себе другие директории, Python-модули и имеющая файл `__init__.py`. -* После `\_\_all\_\_`, но перед началом импортов всегда должно находится 2 пустых строки. Если дальше идет обычная переменная, то 1 строка, если класс, функция или что-то ещё, то тоже 2 строки. +* После `__all__`, но перед началом импортов всегда должно находится 2 пустых строки. Если дальше идет обычная переменная, то 1 строка, если класс, функция или что-то ещё, то тоже 2 строки. -* В пакете не следует импортировать абсолютно все переменные из его подпакетов, только то, что действительно может потребоваться за пределами этого основного пакета. Так, пакет `middlewares` в своем `\_\_init\_\_.py` будет содержать только импорт функции для присоединения мидлвари к диспетчеру бота, с последующим указанием названия этой функции в `\_\_all\_\_`, вся остальная логика, зависимости и реализации мидлвари могут быть скрыты в других файлах пакета, или находится внутри его подпакетов, если в них нет необходимости для использования за рамками этого пакета. +* В пакете не следует импортировать абсолютно все переменные из его подпакетов, только то, что действительно может потребоваться за пределами этого основного пакета. Так, пакет `middlewares` в своем `__init__.py` будет содержать только импорт функции для присоединения мидлвари к диспетчеру бота, с последующим указанием названия этой функции в `__all__`, вся остальная логика, зависимости и реализации мидлвари могут быть скрыты в других файлах пакета, или находится внутри его подпакетов, если в них нет необходимости для использования за рамками этого пакета. * Если вашему пакету требуются вспомогательные функции, то их можно указать в модуле `utils.py` и импортировать оттуда. -* Внутри директории `src` содержатся папки для всех основных компонентов проекта, его основных пакетов. Внутри них могут быть как вспомогательные пакеты, так и простые папки, так и простые модули. +* Внутри директории `src/` содержатся папки для всех основных компонентов проекта, его основных пакетов. Внутри них могут быть как вспомогательные пакеты, так и простые папки, так и простые модули. * Относительные пути следует использовать только в случае, если мы имеем хотим импортировать в пакет его содержимое. В остальном случае требуется использовать полный путь, который начинается с объявления основного пакета. Например `from bot.handlers import connect_routers`. ---- + ## Про инструменты. @@ -40,11 +40,11 @@ * Из-за указания флага `--dev` при использовании `uv sync`, были загружены зависимости необходимые для разработки. К ним относится `ruff` - Python линтер, который проверяет основные ошибки при написании кода с помощью команды `ruff check`. А также `pyrefly` - type-checker, который проверяет, учитывают ли ваши сценарии для работы с кодом то, что переменная может иметь разные типы данных, в зависимости от ситуации. Так `CallbackQuery` не всегда имеет атрибут `message`. Проверка осуществляется с помощью `pyrefly check`. ---- + ## Про написание кода. -* Все основные правила написания кода заложены в настройки `ruff`, `pyrefly`. +* Все основные правила написания кода заложены в настройки `ruff`, `pyrefly`. * Длина строки не больше 70 символов. @@ -58,7 +58,7 @@ * Логируйте важные события, делайте лог ошибок, старайтесь не допускать дыр в поведении программы. Логирование совершается с помощью библиотеки `loguru`. Импорт логера следует делать так: `from loguru import logger as loguru_logger`. Никаких `print()`, только логирование. ---- + ## Про структуру проекта. @@ -94,9 +94,9 @@ urfu-daddy/ └── uv.lock # Закрепление версий зависимостей проекта. ``` -* В директориях `commands` и `callbacks` для создания новых хендлеров, требуется только создание нового файла (или изменение текущего) с привязкой декоратора RouterRegistry.register к функции хендлера. Подробный пример смотрите в docstring декоратора. Подключение к роутеру и последующая привязка к диспетчеру Aiogram происходит автоматически. Если вы хотите объединить несколько Python-модулей в одну папку, то просто создайте её и переместите модули туда. Файл `\_\_init\_\_.py` создавать не требуется, он будет проигнорирован при импортировании настроек RouterRegistry для привязки к роутеру! +* В директориях `commands` и `callbacks` для создания новых хендлеров, требуется только создание нового файла (или изменение текущего) с привязкой декоратора RouterRegistry.register к функции хендлера. Подробный пример смотрите в docstring декоратора. Подключение к роутеру и последующая привязка к диспетчеру Aiogram происходит автоматически. Если вы хотите объединить несколько Python-модулей в одну папку, то просто создайте её и переместите модули туда. Файл `__init__.py` создавать не требуется, он будет проигнорирован при импортировании настроек RouterRegistry для привязки к роутеру! + ---- ## Про настройки для проекта (env-настройки, config). @@ -106,23 +106,25 @@ urfu-daddy/ * Список всех обязательный переменных и опциональных переменных с их значениями можно найти в `src/config/utils`, класс `Settings`. ---- + ## Про коммиты, PR, документацию. + * Если вы предлагаете PR, то пишите краткое, но полное описание изменений (если вы обсудили их с командой) или развернутое описание (в ином случае). * Коммиты пишутся на английском языке и соответствуют [соглашению о коммитах](https://www.conventionalcommits.org/ru/v1.0.0/). * Докстинги на английском языке и соответствуют общепринятому соглашению (расширения для VSCode - python docstrings). ---- + ## Небольшие уточнения. * Игнорируйте замечания `pyrefly` на то, что для `config: Settings` не объявлена обязательная переменная, он не понимает, что они получаются из `.env` файла. ---- + ## И самое главное. + * Делайте хорошо. * Плохо не делайте.