Как Помочь#
Этот файл описывает наш стиль кода и немного другой документации про внесение своей помощи в проект. Вы должны прочитать этот файл перед вашим первым изменением.
Также учитывайте что это все только рекомендации, вы можете использовать что угодно в некоторых случаях, если это будет лучше, чем то что мы предлагаем тут. Однако мы будем давать приоритет этим рекомендациям при рассмотрении ваших изменений.
Language#
All contributions, all code, all comments, all commits and everything else must be in English.
make test#
Эта «магическая» команда собирает в себе почти все наше CI. Если вы на Windows, попробуйте Chocolatey для запуска make.
Так же из-за конфликта между pytest-testmon и pytest-cov мы используем опцию --no-cov в pytest и таким образом даем приоритет pytest-testmon. Если вы хотите сгенерировать отчет с помощью pytest-cov, используйте make test ci=1.
pre-commit#
Более того, вы можете привязать make test (плюс несколько дополнительных полезных проверок) для запуска при каждом коммите, так что вы всегда будете уверены, что CI никогда не провалиться. Просто запустите pre-commit install.
Commit naming style#
Every commit must have one small change. We also use the Tim Pope commit message template for commits“ messages.
If you worry about clean git log - just don’t. We use squash strategy for merging PRs.
Стиль Кода#
Мы используем black для почти всего контроля стиля. Мы также пытаемся использовать форматеры вместо линтеров, где это возможно.
Более того, мы также имеем некоторые правила, которые black не покрывает. Это включает:
Импорты#
У нас есть isort и pycln для контроля импортов. Первая утилита используется для сортировки импортов, а вторая для удаления не используемых импортов. Все остальные правила не покрываются линтерами/форматерами или чем либо еще. Вы должны следить за этим сами.
Вам лучше использовать import module и from package import module, где это возможно, но иногда стиль from module import ... бывает более полезен. Например:
from dataclasses import dataclass
Если вы используете только одну переменную из модуля, и она читаема без имени этого модуля, вам следует использовать from module import .... Но если вы используете много переменных из модуля, лучше использовать import module/from package import module:
from functools import cached_property
Возможно, вы заметили, что import module и from package import module написаны с /, это потому, что вы должны использовать первый способ, если нет пакета (package). Но если пакет существует - вы должны использовать from package import module. Посмотрите на эти примеры:
import os
from my_project import config
from my_project import models
Обратите внимание, что здесь нет относительных импортов, вы не можете использовать его у нас. Однако вы можете использовать as.
Кроме того, вы должны указать переменную __all__ во всех файлах __init__.py с любым кодом (не одной строкой документации). Причина этого ограничения в том, что pycln и документация не могут точно знать, хотите ли вы добавить импорт как псевдоним или импортируете для использования в коде, который находится в этом файле. pycln проигнорирует эти импорты, а документы будут дублировать документацию для всего, что вы будете импортировать.
Док-строки#
Мы используем flake8 для проверки наличия док-строк и их качества. Позже они появятся в документации API. Вы должны писать док-строки везде, кроме методов __init__ (не то же самое, что файлы __init__.py), потому что они не попадут в документацию.
Я также рекомендую прочитать гайд по стилю Google про док-строки, потому что мы используем стиль Google в док-строках.
Разметка#
Из-за ограничений Sphinx мы должны использовать разметку ReST в док-строках. Это позволяет нам использовать перекрестные ссылки на другие функции или даже проекты.
Подробнее о ReST разметке и перекрестных ссылках Sphinx.
Док-строки в __init__.py#
Они описывают пакет (папку, package) с модулями (.py файлы, modules).
Док-строки в модулях, функциях, классах и методах#
Это краткое описание элемента. Они должны соответствовать гайду по стилю Google про док-строки.
Док-строки в переменных#
Они должны идти в формате:
some_variable = "abc"
"""This ``some`` variable used in :class:`.SomeClass`."""
Это относится к уровню модуля и атрибутам классов в датаклассах/классах, генерируемых attrs. Это не будет работать в методах __init__, потому что они не попадают в документацию. Атрибуты должны быть задокументированы в док-строках на основе класса, в секции Attributes.
В настоящее время линтер не обнаруживает их. Лучше иногда проверять, что все в документации API действительно задокументировано.
pyproject.toml#
В этом файле мы настраиваем только poetry (за исключением black, который поддерживает только файл pyproject.toml для настройки).
Группы#
Начиная с версии poetry 1.2 появилась новая возможность - группы. Она позволяет загружать только те группы пакетов, которые вам понадобятся. У нас есть четыре группы - make, tests, docs и github_hooks. Каждая из них рассказывает про свою функцию названием.
make: Все необходимые зависимости для make test.tests: Все необходимые зависимости для тестов.docs: Все необходимые зависимости для постройки документации.github_hooks: Все необходимые зависимости для GitHub hooks.
Пожалуйста, смотрите Управление зависимостями в poetry.
Версии#
Все версии должны следовать в формате X.Y.z (абсолютная версия) или (~X.Y). Последний способ будет компилироваться в формат >=X.Y.0,<X.Y+1.0. Например, у нас есть последняя версия для абстрактной зависимости 1.2.3, мы указываем ее версию ~1.2, поэтому она будет компилироваться в >=1.2.0,<1.3.0 (принимается любая версия патча для 1.2, но не 1.3+). Если 1.3.0 будет выпущен - dependabot создаст PR для него.
Подробнее о Semantic Versions и спецификации зависимостей в poetry.
Переводы#
Если вы не знаете языков, которые мы поддерживаем - предоставьте перевод нам.
Для обновления .po файлов запустите make translate, после чего вы сможете редактировать переводы в .po файлах по пути locales/<тэг языка>/LC_MESSAGES/messages.po или locale/<тэг языка>/LC_MESSAGES/ в документации. После редактирования, для компиляции можете еще раз запустить make translate (или make html в документации).
Для добавления нового языка используйте pybabel init -i locales/base.pot -l <тэг языка> -d locales или sphinx-intl update -l <тэг языка> для документации.
P.S. Тэг языка это короткое его название, например en или en_EN. Полный список вы можете посмотреть запустив pybabel --list-locales.
Документация#
Мы используем Sphinx для документации и док-строки для документации API. На данный момент здесь нет никаких актуальных стилей, кроме doc8.
Другая Помощь#
Вы можете помочь проекту распространяя информацию о нём. Так же большой поддержкой будет, например, написание короткой статьи о том как вы используете этот проект. Вы также можете делаться своими практиками с нами.