Перейти к содержанию

Основы

Базовые сведения об использовании и настройке Black.

Black ведёт себя как обычная Unix-утилита командной строки:

  • ничего не делает, если не находит исходников для форматирования;
  • читает из stdin и пишет в stdout, если в качестве имени файла указан -;
  • выводит сообщения пользователю только в stderr;
  • завершается с кодом 0, если не произошла внутренняя ошибка и опция CLI не предписывает иначе.

Использование

Black переформатирует целые файлы на месте. Для быстрого старта с разумными значениями по умолчанию:

black {source_file_or_directory}

Если запуск как скрипт не срабатывает, можно запустить Black как пакет:

python -m black {source_file_or_directory}

Игнорирование участков кода

Black не переформатирует строки, содержащие # fmt: skip, и блоки между # fmt: off и # fmt: on. # fmt: skip можно комбинировать с другими прагмами/комментариями в нескольких комментариях (например, # fmt: skip # pylint # noqa) или через точку с запятой (например, # fmt: skip; pylint; noqa). # fmt: on/off должны быть на одном уровне отступа и в одном блоке — между ними не должно быть «выхода» из начального уровня отступа. Black также распознаёт блочные комментарии YAPF с тем же эффектом.

Опции командной строки

Опции CLI выводятся командой black --help. Ниже они описаны подробнее. Несмотря на множество настроек, Black остаётся «opinionated», поэтому опций стиля мало и добавляются они редко.

Все перечисленные опции можно задать в файле pyproject.toml (см. ниже).

-h, --help

Показать доступные опции и выйти.

-c, --code

Форматировать код, переданный строкой.

$ black --code "print ( 'hello, world' )"
print("hello, world")

-l, --line-length

Максимальное число символов в строке. По умолчанию 88.

См. также документацию по стилю.

-t, --target-version

Версии Python, которые должен поддерживать вывод Black. Полный список — в black --help для опции --target-version. Укажите все версии, которые поддерживает ваш код. Например, для Python 3.11–3.13:

$ black -t py311 -t py312 -t py313

В конфигурационном файле:

target-version = ["py311", "py312", "py313"]

По умолчанию Black берёт целевые версии из метаданных проекта в pyproject.toml (поле [project.requires-python]). Если однозначно определить не удаётся, используется автоопределение по каждому файлу.

Эта опция задаёт грамматику для разбора кода и может влиять на стиль. Например, запятая после *args в вызове функции появилась в Python 3.5, поэтому Black добавит её только если все целевые версии 3.5+:

$ black --line-length=10 --target-version=py35 -c 'f(a, *args)'
# вывод с запятой после *args

$ black --line-length=10 --target-version=py34 -c 'f(a, *args)'
# вывод без запятой после *args

$ black --line-length=10 --target-version=py34 --target-version=py35 -c 'f(a, *args)'
# без запятой (консервативно, т.к. есть py34)

--pyi

Форматировать все входные файлы как typing stubs (.pyi), независимо от расширения. Удобно при передаче кода через stdin.

--ipynb

Форматировать все входные файлы как Jupyter Notebooks, независимо от расширения. Удобно при передаче через stdin.

--python-cell-magics

При обработке Jupyter Notebooks добавлять указанный magic в список известных python-magics. Нужно для ячеек с кастомными python magics.

-x, --skip-source-first-line

Пропустить первую строку исходного кода.

-S, --skip-string-normalization

По умолчанию Black использует двойные кавычки и нормализует префиксы строк (см. документацию по стилю). С этой опцией строки не меняются.

-C, --skip-magic-trailing-comma

По умолчанию Black учитывает существующие trailing commas (см. документацию). С этой опцией «магическая» trailing comma игнорируется.

--preview

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

Подробнее: preview style. Гарантий стабильности стиля при использовании этого флага между релизами нет.

--unstable

Включить все изменения из --preview плюс дополнительные, которые планируются, но имеют известные проблемы. Используйте для экспериментов и помощи в отладке. Гарантий стабильности вывода нет.

--enable-unstable-feature

Включить отдельные возможности из стиля --unstable. Список — в документации preview style. Флаг можно использовать только при включённом --preview. Полезно, если вы используете --preview и какую-то возможность перенесли из preview в unstable, но вы хотите сохранить её поведение без отката.

Поведение и даже наличие этих возможностей между релизами не гарантируется.

--check

Не записывать файлы, только вернуть статус. Black завершится с:

  • кодом 0, если ничего не изменилось;
  • кодом 1, если какие-то файлы были бы переформатированы;
  • кодом 123 при внутренней ошибке.

В сочетании с --quiet выводится только код выхода (если не было внутренней ошибки).

$ black test.py --check
All done! ✨ 🍰 ✨
1 file would be left unchanged.
$ echo $?
0

$ black test.py --check
would reformat test.py
Oh no! 💥 💔 💥
1 file would be reformatted.
$ echo $?
1

$ black test.py --check
# при внутренней ошибке — код 123

--diff

Не записывать файлы, только вывести diff с предполагаемыми изменениями. Вывод идёт в stdout. Цветной diff — опция --color.

$ black test.py --diff
--- test.py     ...
+++ test.py     ...
@@ -1 +1 @@
-print ( 'hello, world' )
+print("hello, world")
would reformat test.py
All done! ✨ 🍰 ✨
1 file would be reformatted.

--no-cache

Не использовать и не обновлять кэш Black в этом запуске. Black заново анализирует все файлы и не читает/не пишет кэш. Помогает воспроизвести результат «с нуля», отладить проблемы с кэшем или обеспечить свежий анализ при каждом запуске в CI.

--color / --no-color

Показывать (или не показывать) цветной diff. Действует только при --diff.

--line-ranges

Форматировать только указанные строки. Опцию можно указывать несколько раз; объединяются все указанные диапазоны. Каждый диапазон задаётся двумя целыми через -. Нумерация с 1, границы включительно.

Black может всё равно затронуть строки вне диапазона для многострочных утверждений. Форматирование нескольких файлов или ipynb с этой опцией не поддерживается. Опцию нельзя задать в pyproject.toml.

Пример: black --line-ranges=1-10 --line-ranges=21-30 test.py отформатирует строки 1–10 и 21–30. Опция предназначена в основном для интеграций с редакторами (например, «Format Selection»).

Note

Из-за #4052 --line-ranges может затронуть лишние строки, если рядом с запрошенными есть неотформатированные строки с тем же содержимым. В режиме --safe при этом отключается проверка стабильности форматирования.

--fast / --safe

По умолчанию Black после форматирования выполняет проверку AST. Флаг --fast отключает проверку, --safe — явно включает.

--required-version

Требовать определённую версию Black. Удобно, чтобы все участники проекта использовали одну версию (разные версии могут слегка по-разному форматировать). Опцию можно задать в конфигурационном файле.

$ black --version
black, 26.1.0 (compiled: yes)
$ black --required-version 26.1.0 -c "format = 'this'"
format = "this"
$ black --required-version 31.5b2 -c "still = 'beta?!'"
Oh no! 💥 💔 💥 The required version does not match the running version!

Можно указать только мажорную версию:

$ black --required-version 22 -c "format = 'this'"
format = "this"
$ black --required-version 31 -c "still = 'beta?!'"
Oh no! 💥 💔 💥 The required version does not match the running version!

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

--exclude

Регулярное выражение для файлов и каталогов, исключаемых при рекурсивном поиске. Пустое значение — ничего не исключать. На всех платформах (включая Windows) для каталогов используйте прямые слэши. По умолчанию Black также игнорирует пути из .gitignore. Задание этого значения переопределяет все исключения по умолчанию.

Исключения по умолчанию: .direnv, .eggs, .git, .hg, .ipynb_checkpoints, .mypy_cache, .nox, .pytest_cache, .ruff_cache, .tox, .svn, .venv, .vscode, __pypackages__, _build, buck-out, build, dist, venv.

Если в регулярном выражении есть переводы строк, оно трактуется как verbose regex. Удобно при настройке в pyproject.toml.

--extend-exclude

Как --exclude, но добавляет шаблоны к значениям по умолчанию, а не заменяет их.

--force-exclude

Как --exclude, но соответствующие файлы и каталоги исключаются даже при явной передаче аргументами. Удобно при программном вызове Black по изменённым файлам (pre-commit, плагин редактора).

--stdin-filename

Имя файла при передаче через stdin. Нужно, чтобы Black учитывал --force-exclude в редакторах, использующих stdin.

--include

Регулярное выражение для файлов и каталогов, включаемых при рекурсивном поиске. Пустое значение — включать все файлы. Переопределяет все исключения, в том числе из .gitignore и опций командной строки.

Включения по умолчанию: ['.pyi', '.ipynb'].

-W, --workers

При форматировании нескольких файлов Black может использовать пул процессов. Эта опция задаёт число воркеров. Можно также задать переменной окружения BLACK_NUM_WORKERS. По умолчанию — число CPU в системе.

-q, --quiet

Не выводить некритичные сообщения. Сообщения об ошибках по-прежнему выводятся (их можно подавить через 2>/dev/null).

$ black src/ -q
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio

-v, --verbose

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

$ black src/ -v
Using configuration from /tmp/pyproject.toml.
src/blib2to3 ignored: matches the --extend-exclude regular expression
...

--version

Проверить установленную версию Black.

$ black --version
black, 26.1.0

--config

Читать опции из указанного конфигурационного файла. Подробнее о формате — ниже.

Опции через переменные окружения

Поддерживаются:

  • BLACK_CACHE_DIR — каталог для кэша Black.
  • BLACK_NUM_WORKERS — число параллельных воркеров. Опция -W/--workers имеет приоритет над этой переменной.

Альтернативы вводу кода

Black может форматировать код из stdin и выводить результат в stdout. Укажите путь -:

$ echo "print ( 'hello, world' )" | black -
print("hello, world")
reformatted -
All done! ✨ 🍰 ✨
1 file reformatted.

Tip: чтобы Black трактовал stdin как файл, переданный через CLI, используйте --stdin-filename. Так в редакторах, работающих через stdin, будет учитываться --force-exclude.

Код можно также передать строкой через опцию --code.

Запись и отчёт

По умолчанию Black переформатирует указанные и/или найденные файлы на месте. Режимы «только показать, что будет сделано» включаются флагами:

  • --check — завершиться с кодом 1, если какой-то файл был бы переформатирован;
  • --diff — вывести diff вместо перезаписи файлов.

Оба флага можно использовать вместе.

Подробность вывода

Black по умолчанию выводит изменённые файлы, сообщения об ошибках и краткую сводку. Уровень детализации задаётся флагами --quiet и --verbose.

Конфигурация через файл

Black может читать значения по умолчанию для опций из файла pyproject.toml. Это удобно для кастомных паттернов --include и --exclude/--force-exclude/--extend-exclude.

Совет: на вопрос «Нужно ли что-то настраивать?» ответ — «Нет». Black опирается на разумные умолчания; их достаточно, чтобы код соответствовал стилю других проектов, форматируемых Black.

Что такое pyproject.toml?

PEP 518 определяет pyproject.toml как конфигурационный файл для требований системы сборки. С помощью Poetry, Flit или Hatch он может полностью заменить setup.py и setup.cfg.

Где Black ищет конфигурацию

Black ищет pyproject.toml с секцией [tool.black], начиная с общего базового каталога всех переданных файлов и каталогов, затем в родительских каталогах. Поиск прекращается при нахождении файла, каталога .git или .hg, либо корня файловой системы.

При форматировании stdin поиск идёт от текущего рабочего каталога.

Можно использовать «глобальную» конфигурацию в домашнем каталоге — она применяется только если Black не нашёл конфигурацию описанным выше способом. Пути:

  • Windows: ~\.black
  • Unix (Linux, macOS и т.д.): $XDG_CONFIG_HOME/black (или ~/.config/black, если XDG_CONFIG_HOME не задана)

Это пути к самому TOML-файлу (файл не должен называться pyproject.toml). То есть нужно создать файл black или .black в каталоге ~/.config/ (или аналог на Windows, например C:\Users\UserName).

Путь к конкретному файлу можно задать явно через --config. В этом случае Black не ищет другие файлы.

При --verbose выводится сообщение о найденном и использованном файле.

blackd конфигурацию из pyproject.toml не использует.

Формат конфигурации

pyproject.toml — это TOML. Black использует секцию [tool.black]. Ключи опций совпадают с длинными именами опций командной строки.

В TOML для регулярных выражений нужно использовать строки в одинарных кавычках (аналог r-строк в Python). Многострочные строки Black трактует как verbose regex. Значимый пробел можно задать как [ ].

Пример pyproject.toml:

[tool.black]
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
extend-exclude = '''
(
  ^/foo.py
  | .*_pb2.py
)
'''

Иерархия настроек

У опций командной строки есть значения по умолчанию (видны в --help). Их может переопределять pyproject.toml. Опции, переданные в командной строке, переопределяют и то и другое.

Black за один запуск использует только один файл pyproject.toml — не ищет несколько и не объединяет конфигурацию с разных уровней каталогов.

Дальнейшие шаги

Имеет смысл настроить автообнаружение файлов, чтобы достаточно было black . вместо перечисления файлов и каталогов. См. File collection and discovery.

Также полезно настроить интеграцию с редактором или pre-commit для контроля версий.

Источник: The basics. Перевод неофициальный.