repository·main·Indexed 12 days ago
https://github.com/psf/blackAn opinionated Python code formatter that provides speed, determinism, and freedom from manual formatting. Black is primarily a command line tool that supports Python 3.10+ and PyPy 3.8+. It includes specialized support for Jupyter Notebooks via the `black[jupyter]` extra and provides guidance on integrating with tools like isort, Flake8, and Pylint.
Black provides official integration documentation for the following areas:
There are four primary ways to use Black in PyCharm/IntelliJ IDEA:
BlackConnect plugin and blackd for the fastest formatting by avoiding startup costs.Black can be invoked by passing specific files or entire directories. When a directory is passed, Black walks the directory tree to collect files for formatting. It automatically determines which files to format or skip based on:
.gitignore rules (if --exclude is not explicitly set)Black avoids spurious vertical whitespace to follow PEP 8 principles.
You can prevent Black from reformatting specific lines or blocks of code using special comments:
# fmt: skip to a line. This can be combined with other comments (e.g., # fmt: skip # pylint # noqa) or used as a semicolon-separated list (e.g., # fmt: skip; pylint; noqa).# fmt: off at the start and # fmt: on at the end. These must be at the same indentation level and within the same block (no unindenting between them).Black also supports YAPF's block comment style for compatibility.
In .pyi stub files, the --preview style improves heuristics for blank lines around decorated function groups (like @overload).
Rules applied to groups of $\ge 2$ decorated functions with the same name:
This ensures @overload groups are kept together without unwanted blank lines inside the group, even if one overload has a docstring.
# Before
@overload
def foo(x: int) -> int:
"""Docs."""
@overload # unwanted blank line within group
def foo(x: str) -> str: ...
def bar(x): ... # no blank line after group
# After (with --preview)
@overload
def foo(x: int) -> int:
"""Docs."""
@overload
def foo(x: str) -> str: ...
def bar(x): ...Black normalizes string quotes and string prefixes to lowercase. However, it makes an exception for r-strings (raw strings) to preserve compatibility with syntax highlighters like MagicPython (used by GitHub and VS Code). This ensures that r"string" is highlighted as a regular expression while R"string" is treated as a true raw string.The string_processing feature improves how long and short strings are handled:
Note: f-strings are not merged if doing so would change their internal quotation mark style.
Black adds trailing commas to expressions that are split by commas where each element is on its own line (including function signatures).
Exceptions and Behaviors:
*, *args, or **kwargs: Black only adds trailing commas if it detects the file is Python 3.6+ (by looking for f-strings or existing trailing commas in starred signatures). If you manually add a trailing comma in these cases and Black doesn't recognize it as safe, it will preserve your manual comma.Black prefers double quotes (" and """) over single quotes (' and ''') to reduce reader distraction and align with PEP 257.
r for raw), except for the capital R prefix. Unicode markers (u) are removed. For multiple characters, r is placed first (e.g., rf"string").\uabcd), but uses uppercase for \N named character escapes.If you are adopting Black in a project with existing single-quote conventions, use the --skip-string-normalization flag to prevent mass changes. This is recommended for adoption only, not for new projects.
Black corrects indentation for both quotations and text, removes superfluous trailing whitespace, and removes unnecessary newlines at the end of the docstring. It converts leading tabs to spaces but preserves tabs inside the text.
black --skip-string-normalization .Black applies uniform horizontal and vertical whitespace by ignoring previous formatting.
Rules follow pycodestyle recommendations.
Black attempts to render one full expression or simple statement per line.
from ... import ... line cannot fit the allotted length, it is always split into one element per line. This minimizes git diffs and improves readability.# in:
ImportantClass.important_method(exc, limit, lookup_lines, capture_locals, extra_argument)
# out:
ImportantClass.important_method(
exc, limit, lookup_lines, capture_locals, extra_argument
)Black breaks a line before a binary operator when splitting a block of code over multiple lines to comply with PEP 8.
+, -, ~).**) when both operands are 'simple' (a NAME, numeric CONSTANT, or attribute access, with or without a preceding unary operator).Examples of no whitespace:
a = x**y
b = config.base**5.2
c = 2**5Examples with whitespace:
f = 2 ** get_exponent()
g = get_x() ** get_y()