Стиль Python-кода
Применять общие правила единообразия, не подменяя ими архитектурные,
технологические и продуктовые требования профильного скила.
Порядок работы
- Изучить локальные инструкции и существующую конфигурацию инструментов.
- Сохранить сложившиеся проектные соглашения, не противоречащие этому скилу.
- Изменять стиль только в затронутом коде; не смешивать задачу с массовым
форматированием или несвязанным рефакторингом.
- Проверить изменённый код линтером и форматировщиком, настроенными в проекте.
Условия
- Одну или две независимые простые проверки оставлять непосредственно в
if.
- Условие из трёх и более независимых предикатов, соединённых
and/or, либо
сложное многострочное условие выносить в переменную с именем, объясняющим его
общий смысл.
- Проверку membership считать одним предикатом независимо от числа элементов:
state in (State.ACTIVE, State.PENDING, State.BLOCKED) можно оставить в if.
- Если для составного условия нельзя подобрать содержательное имя, использовать
последовательные guard clauses или небольшой метод с одной ответственностью.
- Не сохранять простой boolean в переменную, если она лишь повторяет выражение и
не добавляет смысла.
Перечисления
- Сравнивать значение непосредственно с членом enum через
== или !=.
- Для нескольких допустимых членов использовать
in или not in.
- Не создавать методы-предикаты, дублирующие отдельные значения enum:
is_admin(), is_active(), is_deleted() и аналогичные.
- Методы enum допустимы для самостоятельного поведения или преобразования,
которое не сводится к сравнению с одним членом.
Функции и классы
- Одна функция или метод выполняет одну связную операцию.
- Не создавать приватную однострочную обёртку без самостоятельного смысла,
повторного использования или изоляции изменчивой детали.
- В классе располагать константы и class attributes,
__init__, свойства и
публичные методы, затем protected/private методы.
- Абстрактный метод содержит только
...; реализацию и побочные эффекты помещать
в конкретный класс.
- Рекомендуемая длина Python-файла — до 300 строк. Более длинный файл проверять
на несколько ответственностей и разделять по смыслу, а не механически.
Импорты
- Удалять неиспользуемые импорты.
- Предпочитать импорт конкретных сущностей импорту модуля целиком.
- Импортировать модуль целиком, когда используется много его элементов либо
пространство имён делает происхождение вызова понятнее.
- Не применять wildcard imports.
- Архитектурные границы импортов определяет профильный скил слоя.
Исключения
- При создании проектного исключения с именованной сигнатурой передавать
аргументы только по именам.
- Встроенные исключения и проектные классы, сохраняющие их позиционную
сигнатуру, вызывать согласно этой сигнатуре: например,
ValueError(message).
- Параметр со значением по умолчанию не передавать, если default совпадает с
требуемым значением.
- Не включать динамические структурированные данные в текст ошибки, если
контракт исключения предоставляет отдельное поле для этих данных.
- Типы, mapping и семантику исключений определяет профильный скил.
Форматирование и документация
- Использовать линтер и форматировщик, настроенные в текущем проекте; не
навязывать конкретный инструмент.
- Не править вручную результат, однозначно определяемый форматировщиком.
- Правила docstring и Markdown-документации брать из специализированного скила
документирования, не дублировать их здесь.
Границы
Не переносить в этот скил правила SQL-безопасности, зависимости слоёв,
неизменяемость domain-объектов, DTO, Unit of Work, transport validation,
конкурентность, lifecycle ресурсов или тестовые сценарии.
Проверка результата
- Условия оформлены единообразно и имеют понятные смысловые имена.
- Enum сравниваются напрямую без методов-предикатов значений.
- Функции и файлы не смешивают очевидно разные ответственности.
- Публичные члены класса расположены выше приватных.
- Импорты точны, wildcard и неиспользуемые импорты отсутствуют.
- Проектные исключения с именованной сигнатурой создаются через именованные
аргументы; встроенная позиционная сигнатура не маскируется ради стиля.
- Абстрактные методы содержат только
....
- Линтер и форматировщик проекта прошли.
Подробный список для ревью: checklist.md.
1---2name: python-code-style-writing3description: Используй при написании, изменении, рефакторинге и ревью любого Python-кода: единообразие условий, enum-сравнений, импортов, исключений, абстрактных методов, порядка членов класса, размера файлов и проверки форматировщиком проекта. Применяй совместно с профильным архитектурным или технологическим скилом; не использовать вместо него для определения поведения и структуры слоёв.4---56# Стиль Python-кода78Применять общие правила единообразия, не подменяя ими архитектурные,9технологические и продуктовые требования профильного скила.1011## Порядок работы12131. Изучить локальные инструкции и существующую конфигурацию инструментов.142. Сохранить сложившиеся проектные соглашения, не противоречащие этому скилу.153. Изменять стиль только в затронутом коде; не смешивать задачу с массовым16 форматированием или несвязанным рефакторингом.174. Проверить изменённый код линтером и форматировщиком, настроенными в проекте.1819## Условия2021- Одну или две независимые простые проверки оставлять непосредственно в `if`.22- Условие из трёх и более независимых предикатов, соединённых `and`/`or`, либо23 сложное многострочное условие выносить в переменную с именем, объясняющим его24 общий смысл.25- Проверку membership считать одним предикатом независимо от числа элементов:26 `state in (State.ACTIVE, State.PENDING, State.BLOCKED)` можно оставить в `if`.27- Если для составного условия нельзя подобрать содержательное имя, использовать28 последовательные guard clauses или небольшой метод с одной ответственностью.29- Не сохранять простой boolean в переменную, если она лишь повторяет выражение и30 не добавляет смысла.3132## Перечисления3334- Сравнивать значение непосредственно с членом enum через `==` или `!=`.35- Для нескольких допустимых членов использовать `in` или `not in`.36- Не создавать методы-предикаты, дублирующие отдельные значения enum:37 `is_admin()`, `is_active()`, `is_deleted()` и аналогичные.38- Методы enum допустимы для самостоятельного поведения или преобразования,39 которое не сводится к сравнению с одним членом.4041## Функции и классы4243- Одна функция или метод выполняет одну связную операцию.44- Не создавать приватную однострочную обёртку без самостоятельного смысла,45 повторного использования или изоляции изменчивой детали.46- В классе располагать константы и class attributes, `__init__`, свойства и47 публичные методы, затем protected/private методы.48- Абстрактный метод содержит только `...`; реализацию и побочные эффекты помещать49 в конкретный класс.50- Рекомендуемая длина Python-файла — до 300 строк. Более длинный файл проверять51 на несколько ответственностей и разделять по смыслу, а не механически.5253## Импорты5455- Удалять неиспользуемые импорты.56- Предпочитать импорт конкретных сущностей импорту модуля целиком.57- Импортировать модуль целиком, когда используется много его элементов либо58 пространство имён делает происхождение вызова понятнее.59- Не применять wildcard imports.60- Архитектурные границы импортов определяет профильный скил слоя.6162## Исключения6364- При создании проектного исключения с именованной сигнатурой передавать65 аргументы только по именам.66- Встроенные исключения и проектные классы, сохраняющие их позиционную67 сигнатуру, вызывать согласно этой сигнатуре: например, `ValueError(message)`.68- Параметр со значением по умолчанию не передавать, если default совпадает с69 требуемым значением.70- Не включать динамические структурированные данные в текст ошибки, если71 контракт исключения предоставляет отдельное поле для этих данных.72- Типы, mapping и семантику исключений определяет профильный скил.7374## Форматирование и документация7576- Использовать линтер и форматировщик, настроенные в текущем проекте; не77 навязывать конкретный инструмент.78- Не править вручную результат, однозначно определяемый форматировщиком.79- Правила docstring и Markdown-документации брать из специализированного скила80 документирования, не дублировать их здесь.8182## Границы8384Не переносить в этот скил правила SQL-безопасности, зависимости слоёв,85неизменяемость domain-объектов, DTO, Unit of Work, transport validation,86конкурентность, lifecycle ресурсов или тестовые сценарии.8788## Проверка результата8990- Условия оформлены единообразно и имеют понятные смысловые имена.91- Enum сравниваются напрямую без методов-предикатов значений.92- Функции и файлы не смешивают очевидно разные ответственности.93- Публичные члены класса расположены выше приватных.94- Импорты точны, wildcard и неиспользуемые импорты отсутствуют.95- Проектные исключения с именованной сигнатурой создаются через именованные96 аргументы; встроенная позиционная сигнатура не маскируется ради стиля.97- Абстрактные методы содержат только `...`.98- Линтер и форматировщик проекта прошли.99100Подробный список для ревью: [checklist.md](references/checklist.md).
Nemagu