Форматирование Python

Что делает этот инструмент

Форматтер Python переписывает код в широко распространённом стиле Black: единообразные отступы, пробелы вокруг операторов, двойные кавычки, две пустые строки между определениями верхнего уровня и перенос длинных строк в разумных местах.

Под капотом работает форматтер из Ruff — быстрого линтера и форматтера для Python, написанного на Rust, — скомпилированный в WebAssembly. Результат Ruff практически построчно совпадает с Black, поэтому отформатированный здесь код не будет переформатирован pre-commit-хуком вашего проекта.

Как пользоваться

1. Вставьте код на Python или откройте файл .py.
2. Отформатированный код появляется справа по мере ввода.
3. Настройте параметры, если в проекте принят другой стиль:
   • Отступ: 4 пробела — это PEP 8 и значение по умолчанию; доступны также 2 пробела и табуляция.
   • Ширина строки: 88 — значение Black по умолчанию, 79 — ограничение PEP 8, а 100 или 120 подходят для широких экранов.
   • Кавычки: двойные, одинарные или те, что уже используются в каждой строке.
   • Учитывать завершающие запятые: оставлять развёрнутыми коллекции, которые заканчиваются запятой.
4. Скопируйте или скачайте результат.

Если код не удаётся разобрать, сообщение об ошибке показывает, где остановился парсер, например Expected `,`, found `=` в строке 4, и к этой строке можно сразу перейти.

Пример

В примере — небольшой модуль, написанный небрежно: импорты в одной строке без пробелов, dataclass с пробелом перед двоеточием, метод с отступом в два пробела и однострочный оператор if. После форматирования каждый блок получает отступ в четыре пробела, тело if переносится на отдельную строку, вокруг операторов появляются пробелы, одинарные кавычки становятся двойными, а между классом и функциями добавляются пустые строки. Список, заканчивавшийся завершающей запятой, разворачивается — по одному словарю на строку.

Чего форматтер не делает

Форматирование меняет только оформление. Оно не сортирует импорты, не удаляет неиспользуемые переменные и ничего не переименовывает — это задачи линтера (с ними справляется ruff check --fix). Комментарии и docstring сохраняются, а код, который не удаётся разобрать, форматтер отказывается менять, вместо того чтобы гадать.

Советы

• Используйте ту же ширину строки, что и в pyproject.toml вашего проекта, чтобы результат совпадал с CI.
• Фрагмент кода, отформатированный перед публикацией в вопросе или ревью, читать гораздо проще.
• Если код пришёл из ноутбука или чата и в нём перемешаны табуляции и пробелы, форматтер приведёт его в порядок за один шаг.