# Python Code Style Writing

> Используй при написании, изменении, рефакторинге и ревью любого Python-кода: единообразие условий, enum-сравнений, импортов, исключений, абстрактных методов, порядка членов класса, размера файлов и проверки форматировщиком проекта. Применяй совместно с профильным архитектурным или технологическим скилом; не использовать вместо него для определения поведения и структуры слоёв.

- Skill: `nemagu/python-code-style-writing` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nemagu/python-code-style-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/python-code-style-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Nemagu (https://skillmd.com/u/nemagu)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nemagu/python-code-style-writing

---


# Стиль Python-кода

Применять общие правила единообразия, не подменяя ими архитектурные,
технологические и продуктовые требования профильного скила.

## Порядок работы

1. Изучить локальные инструкции и существующую конфигурацию инструментов.
2. Сохранить сложившиеся проектные соглашения, не противоречащие этому скилу.
3. Изменять стиль только в затронутом коде; не смешивать задачу с массовым
   форматированием или несвязанным рефакторингом.
4. Проверить изменённый код линтером и форматировщиком, настроенными в проекте.

## Условия

- Одну или две независимые простые проверки оставлять непосредственно в `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](references/checklist.md).