black
24.10.0
«Любой цвет, который вам нравится».
Black — бескомпромиссный форматировщик кода Python. Используя его, вы соглашаетесь передать контроль над деталями ручного форматирования. В свою очередь, Black дает вам скорость, детерминизм и свободу от ворчания pycodestyle по поводу форматирования. Вы сэкономите время и умственную энергию для более важных дел.
Почерневший код выглядит одинаково независимо от проекта, который вы читаете. Через некоторое время форматирование становится прозрачным, и вместо этого вы можете сосредоточиться на содержимом.
Блэк ускоряет проверку кода, создавая минимально возможные различия.
Попробуйте это прямо сейчас, используя Black Playground. Посмотрите доклад PyCon 2019, чтобы узнать больше.
Прочтите документацию на ReadTheDocs!
Black можно установить, запустив pip install black . Для работы требуется Python 3.9+. Если вы хотите отформатировать блокноты Jupyter, установите его с помощью pip install "black[jupyter]" .
Если вы не можете дождаться последних новостей и хотите установить их с GitHub, используйте:
pip install git+https://github.com/psf/black
Чтобы сразу начать работу с разумными настройками по умолчанию:
black {source_file_or_directory}Вы можете запустить Black как пакет, если запуск его как скрипта не работает:
python -m black {source_file_or_directory}Дополнительную информацию можно найти в наших документах:
Черный уже успешно используется во многих проектах, маленьких и больших. У Black есть комплексный набор тестов с эффективными параллельными тестами, а также наша собственная программа автоматического форматирования и параллельной непрерывной интеграции. Теперь, когда мы стали стабильными, вам не следует ожидать больших изменений форматирования в будущем. Стилистические изменения в основном будут ответами на сообщения об ошибках и поддержкой нового синтаксиса Python. Дополнительную информацию см. в разделе «Стиль Black Code».
Кроме того, в качестве меры безопасности, которая замедляет обработку, Блэк проверит, что переформатированный код по-прежнему создает действительный AST, который фактически эквивалентен оригиналу (подробности см. в разделе «Прагматизм»). Если вы чувствуете себя уверенно, используйте --fast .
Black — это самоуверенное форматирующее устройство, совместимое с PEP 8. Черный переформатирует целые файлы на месте. Возможности конфигурации стиля намеренно ограничены и добавляются редко. Он не учитывает предыдущее форматирование (исключения см. в разделе «Прагматизм»).
Наша документация охватывает текущий стиль кода Блэка , но также документированы планируемые изменения в нем. Оба заслуживают внимания:
Изменения стиля кода Блэка регулируются Политикой стабильности:
Пожалуйста, ознакомьтесь с этим документом перед отправкой вопроса. То, что кажется ошибкой, может быть намеренным поведением.
Ранние версии Блэка в некоторых отношениях были абсолютистскими. Они взяли имя первоначального автора. В то время это было нормально, так как это упрощало реализацию, а пользователей все равно было не так много. Было зарегистрировано не так уж много пограничных случаев. Будучи зрелым инструментом, черные делают некоторые исключения из правил, которых они в остальном придерживаются.
Прежде чем отправлять сообщение о проблеме, ознакомьтесь с этим документом, как и в случае с документом выше. То, что кажется ошибкой, может быть намеренным поведением.
Black может читать значения по умолчанию для конкретных проектов для параметров командной строки из файла pyproject.toml . Это особенно полезно для указания пользовательских шаблонов --include и --exclude / --force-exclude / --extend-exclude для вашего проекта.
Более подробную информацию вы можете найти в нашей документации:
А если вам нужна более общая документация по конфигурации:
Совет : если вы спрашиваете себя: «Нужно ли мне что-нибудь настраивать?» ответ: «Нет». Черный – это разумные дефолты. Применение этих значений по умолчанию приведет ваш код в соответствие со многими другими проектами в формате Black .
Следующие известные проекты с открытым исходным кодом доверяют Блэку обеспечение единообразного стиля кода: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, приложения PyPA (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow , Twisted, LocalStack, интеграция с любым агентом Datadog, Home Assistant, Zulip, Kedro, OpenOA, ФЛОРИС, ОРБИТА, ВОМБАТ и многие другие.
Следующие организации используют Black : Facebook, Dropbox, KeepTruckin, Lyft, Mozilla, Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation.
Нам не хватает кого-нибудь? Дайте нам знать.
Майк Байер , автор SQLAlchemy :
За всю мою карьеру программиста я не могу вспомнить ни одного инструмента, который обеспечил бы мне больший прирост производительности благодаря его внедрению. Теперь я могу выполнять рефакторинг примерно за 1% нажатий клавиш, которые мне потребовались бы раньше, когда у нас не было возможности форматировать код.
Дасти Филлипс , писатель:
Черный самоуверен, так что вам не обязательно быть таким.
Хайнек Шлавак , создатель attrs , основной разработчик Twisted и CPython:
Неплохой автоформатер — это все, что я хочу на Рождество!
Карл Мейер , основной разработчик Django:
По крайней мере, имя хорошее.
Кеннет Рейтц , создатель requests и pipenv :
Это значительно улучшает форматирование нашего кода. Спасибо огромное!
Используйте значок в README.md вашего проекта:
[ ![ Code style: black ] ( https://img.shields.io/badge/code%20style-black-000000.svg )] ( https://github.com/psf/black )Использование значка в README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Выглядит так:
Массачусетский технологический институт
Добро пожаловать! Рад видеть, что вы готовы сделать проект лучше. Вы можете начать, прочитав это:
Вы также можете просмотреть остальную документацию или поговорить с разработчиками:
Журнал стал довольно длинным. Он переместился в свой собственный файл.
См. ИЗМЕНЕНИЯ.
Список авторов в настоящее время довольно длинный, поэтому он находится в отдельном файле.
См. AUTHORS.md
Ожидается, что каждый, кто участвует в проекте Black , и в частности в отслеживании проблем, запросах на включение и активности в социальных сетях, будет относиться к другим людям с уважением и в целом следовать рекомендациям, изложенным в Кодексе поведения сообщества Python.
При этом юмор приветствуется. Фактически, ожидается базовое знакомство с Летающим цирком Монти Пайтона. Мы не дикари.
А если вам действительно нужно кого-то шлепнуть, сделайте это с рыбой во время танца.
