The uncompromising code formatter¶
By using Black, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.
Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.
Try it out now using the Black Playground.
Note - this is a beta product
Black is already successfully used by many projects, small and big. Black has a comprehensive test suite, with efficient parallel tests, our own auto formatting and parallel Continuous Integration runner. However, Black is still beta. Things will probably be wonky for a while. This is made explicit by the “Beta” trove classifier, as well as by the “b” in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.
Also, as a safety measure which slows down processing, Black will check that the
reformatted code still produces a valid AST that is effectively equivalent to the
original (see the
Pragmatism
section for details). If you’re feeling confident, use --fast.
Testimonials¶
Mike Bayer, author of SQLAlchemy:
I can’t think of any single tool in my entire programming career that has given me a bigger productivity increase by its introduction. I can now do refactorings in about 1% of the keystrokes that it would have taken me previously when we had no way for code to format itself.
Dusty Phillips, writer:
Black is opinionated so you don’t have to be.
Hynek Schlawack, creator of attrs, core developer of Twisted and CPython:
An auto-formatter that doesn’t suck is all I want for Xmas!
Carl Meyer, Django core developer:
At least the name is good.
Kenneth Reitz, creator of requests and pipenv:
This vastly improves the formatting of our code. Thanks a ton!
Show your style¶
Use the badge in your project’s README.md:
[](https://github.com/psf/black)
Using the badge in README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Looks like this:
Contents¶
The Black Code Style¶
The Black code style¶
Code style¶
Black reformats entire files in place. Style configuration options are deliberately
limited and rarely added. It doesn’t take previous formatting into account, except for
the magic trailing comma and preserving newlines. It doesn’t reformat blocks that start
with # fmt: off and end with # fmt: on, or lines that ends with # fmt: skip.
# fmt: on/off have to be on the same level of indentation. It also recognizes
YAPF’s block comments to the same effect, as a
courtesy for straddling code.
How Black wraps lines¶
Black ignores previous formatting and applies uniform horizontal and vertical
whitespace to your code. The rules for horizontal whitespace can be summarized as: do
whatever makes pycodestyle happy. The coding style used by Black can be viewed as a
strict subset of PEP 8.
As for vertical whitespace, Black tries to render one full expression or simple statement per line. If this fits the allotted line length, great.
# in:
j = [1,
2,
3
]
# out:
j = [1, 2, 3]
If not, Black will look at the contents of the first outer matching brackets and put that in a separate indented line.
# in:
ImportantClass.important_method(exc, limit, lookup_lines, capture_locals, extra_argument)
# out:
ImportantClass.important_method(
exc, limit, lookup_lines, capture_locals, extra_argument
)
If that still doesn’t fit the bill, it will decompose the internal expression further using the same rule, indenting matching brackets every time. If the contents of the matching brackets pair are comma-separated (like an argument list, or a dict literal, and so on) then Black will first try to keep them on the same line with the matching brackets. If that doesn’t work, it will put all of them in separate lines.
# in:
def very_important_function(template: str, *variables, file: os.PathLike, engine: str, header: bool = True, debug: bool = False):
"""Applies `variables` to the `template` and writes to `file`."""
with open(file, 'w') as f:
...
# out:
def very_important_function(
template: str,
*variables,
file: os.PathLike,
engine: str,
header: bool = True,
debug: bool = False,
):
"""Applies `variables` to the `template` and writes to `file`."""
with open(file, "w") as f:
...
Black prefers parentheses over backslashes, and will remove backslashes if found.
# in:
if some_short_rule1 \
and some_short_rule2:
...
# out:
if some_short_rule1 and some_short_rule2:
...
# in:
if some_long_rule1 \
and some_long_rule2:
...
# out:
if (
some_long_rule1
and some_long_rule2
):
...
Backslashes and multiline strings are one of the two places in the Python grammar that break significant indentation. You never need backslashes, they are used to force the grammar to accept breaks that would otherwise be parse errors. That makes them confusing to look at and brittle to modify. This is why Black always gets rid of them.
If you’re reaching for backslashes, that’s a clear signal that you can do better if you slightly refactor your code. I hope some of the examples above show you that there are many ways in which you can do it.
You might have noticed that closing brackets are always dedented and that a trailing comma is always added. Such formatting produces smaller diffs; when you add or remove an element, it’s always just one line. Also, having the closing bracket dedented provides a clear delimiter between two distinct sections of the code that otherwise share the same indentation level (like the arguments list and the docstring in the example above).
If a data structure literal (tuple, list, set, dict) or a line of “from” imports cannot
fit in the allotted length, it’s always split into one element per line. This minimizes
diffs as well as enables readers of code to find which commit introduced a particular
entry. This also makes Black compatible with
isort with the ready-made black
profile or manual configuration.
Line length¶
You probably noticed the peculiar default line length. Black defaults to 88 characters per line, which happens to be 10% over 80. This number was found to produce significantly shorter files than sticking with 80 (the most popular), or even 79 (used by the standard library). In general, 90-ish seems like the wise choice.
If you’re paid by the line of code you write, you can pass --line-length with a lower
number. Black will try to respect that. However, sometimes it won’t be able to without
breaking other rules. In those rare cases, auto-formatted code will exceed your allotted
limit.
You can also increase it, but remember that people with sight disabilities find it harder to work with line lengths exceeding 100 characters. It also adversely affects side-by-side diff review on typical screen resolutions. Long lines also make it harder to present code neatly in documentation or talk slides.
If you’re using Flake8, you can bump max-line-length to 88 and mostly forget about it.
However, it’s better if you use Bugbear’s
B950 warning instead of E501, and bump the max line length to 88 (or the --line-length
you used for black), which will align more with black’s “try to respect
--line-length, but don’t become crazy if you can’t”. You’d do it like this:
[flake8]
max-line-length = 88
...
select = C,E,F,W,B,B950
extend-ignore = E203, E501
Explanation of why E203 is disabled can be found further in this documentation. And if you’re curious about the reasoning behind B950, Bugbear’s documentation explains it. The tl;dr is “it’s like highway speed limits, we won’t bother you if you overdo it by a few km/h”.
If you’re looking for a minimal, black-compatible flake8 configuration:
[flake8]
max-line-length = 88
extend-ignore = E203
Empty lines¶
Black avoids spurious vertical whitespace. This is in the spirit of PEP 8 which says that in-function vertical whitespace should only be used sparingly.
Black will allow single empty lines inside functions, and single and double empty lines on module level left by the original editors, except when they’re within parenthesized expressions. Since such expressions are always reformatted to fit minimal space, this whitespace is lost.
It will also insert proper spacing before and after function definitions. It’s one line before and after inner functions and two lines before and after module-level functions and classes. Black will not put empty lines between function/class definitions and standalone comments that immediately precede the given function/class.
Black will enforce single empty lines between a class-level docstring and the first following field or method. This conforms to PEP 257.
Black won’t insert empty lines after function docstrings unless that empty line is required due to an inner function starting immediately after.
Comments¶
Black does not format comment contents, but it enforces two spaces between code and a
comment on the same line, and a space before the comment text begins. Some types of
comments that require specific spacing rules are respected: doc comments (#: comment),
section comments with long runs of hashes, and Spyder cells. Non-breaking spaces after
hashes are also preserved. Comments may sometimes be moved because of formatting
changes, which can break tools that assign special meaning to them. See
AST before and after formatting for more discussion.
Trailing commas¶
Black will add trailing commas to expressions that are split by comma where each element is on its own line. This includes function signatures.
One exception to adding trailing commas is function signatures containing *, *args,
or **kwargs. In this case a trailing comma is only safe to use on Python 3.6. Black
will detect if your file is already 3.6+ only and use trailing commas in this situation.
If you wonder how it knows, it looks for f-strings and existing use of trailing commas
in function signatures that have stars in them. In other words, if you’d like a trailing
comma in this situation and Black didn’t recognize it was safe to do so, put it there
manually and Black will keep it.
A pre-existing trailing comma informs Black to always explode contents of the current bracket pair into one item per line. Read more about this in the Pragmatism section below.
Strings¶
Black prefers double quotes (" and """) over single quotes (' and '''). It
will replace the latter with the former as long as it does not result in more backslash
escapes than before.
Black also standardizes string prefixes, making them always lowercase. On top of that,
if your code is already Python 3.6+ only or it’s using the unicode_literals future
import, Black will remove u from the string prefix as it is meaningless in those
scenarios.
The main reason to standardize on a single form of quotes is aesthetics. Having one kind of quotes everywhere reduces reader distraction. It will also enable a future version of Black to merge consecutive string literals that ended up on the same line (see #26 for details).
Why settle on double quotes? They anticipate apostrophes in English text. They match the
docstring standard described in
PEP 257. An empty
string in double quotes ("") is impossible to confuse with a one double-quote
regardless of fonts and syntax highlighting used. On top of this, double quotes for
strings are consistent with C which Python interacts a lot with.
On certain keyboard layouts like US English, typing single quotes is a bit easier than double quotes. The latter requires use of the Shift key. My recommendation here is to keep using whatever is faster to type and let Black handle the transformation.
If you are adopting Black in a large project with pre-existing string conventions
(like the popular
“single quotes for data, double quotes for human-readable strings”),
you can pass --skip-string-normalization on the command line. This is meant as an
adoption helper, avoid using this for new projects.
As an experimental option (can be enabled by --experimental-string-processing),
Black splits long strings (using parentheses where appropriate) and merges short ones.
When split, parts of f-strings that don’t need formatting are converted to plain
strings. User-made splits are respected when they do not exceed the line length limit.
Line continuation backslashes are converted into parenthesized strings. Unnecessary
parentheses are stripped. Because the functionality is experimental, feedback and issue
reports are highly encouraged!
Black also processes docstrings. Firstly the indentation of docstrings is corrected for both quotations and the text within, although relative indentation in the text is preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the end of the docstring are removed. All leading tabs are converted to spaces, but tabs inside text are preserved. Whitespace leading and trailing one-line docstrings is removed.
Numeric literals¶
Black standardizes most numeric literals to use lowercase letters for the syntactic
parts and uppercase letters for the digits themselves: 0xAB instead of 0XAB and
1e10 instead of 1E10. Python 2 long literals are styled as 2L instead of 2l to
avoid confusion between l and 1.
Line breaks & binary operators¶
Black will break a line before a binary operator when splitting a block of code over multiple lines. This is so that Black is compliant with the recent changes in the PEP 8 style guide, which emphasizes that this approach improves readability.
Slices¶
PEP 8
recommends
to treat : in slices as a binary operator with the lowest priority, and to leave an
equal amount of space on either side, except if a parameter is omitted (e.g.
ham[1 + 1 :]). It recommends no spaces around : operators for “simple expressions”
(ham[lower:upper]), and extra space for “complex expressions”
(ham[lower : upper + offset]). Black treats anything more than variable names as
“complex” (ham[lower : upper + 1]). It also states that for extended slices, both :
operators have to have the same amount of spacing, except if a parameter is omitted
(ham[1 + 1 ::]). Black enforces these rules consistently.
This behaviour may raise E203 whitespace before ':' warnings in style guide
enforcement tools like Flake8. Since E203 is not PEP 8 compliant, you should tell
Flake8 to ignore these warnings.
Parentheses¶
Some parentheses are optional in the Python grammar. Any expression can be wrapped in a pair of parentheses to form an atom. There are a few interesting cases:
if (...):while (...):for (...) in (...):assert (...), (...)from X import (...)assignments like:
target = (...)target: type = (...)some, *un, packing = (...)augmented += (...)
In those cases, parentheses are removed when the entire statement fits in one line, or if the inner expression doesn’t have any delimiters to further split on. If there is only a single delimiter and the expression starts or ends with a bracket, the parentheses can also be successfully omitted since the existing bracket pair will organize the expression neatly anyway. Otherwise, the parentheses are added.
Please note that Black does not add or remove any additional nested parentheses that you might want to have for clarity or further code organization. For example those parentheses are not going to be removed:
return not (this or that)
decision = (maybe.this() and values > 0) or (maybe.that() and values < 0)
Call chains¶
Some popular APIs, like ORMs, use call chaining. This API style is known as a fluent interface. Black formats those by treating dots that follow a call or an indexing operation like a very low priority delimiter. It’s easier to show the behavior than to explain it. Look at the example:
def example(session):
result = (
session.query(models.Customer.id)
.filter(
models.Customer.account_id == account_id,
models.Customer.email == email_address,
)
.order_by(models.Customer.id.asc())
.all()
)
Typing stub files¶
PEP 484 describes the syntax for type hints in Python. One of the use cases for typing is providing type annotations for modules which cannot contain them directly (they might be written in C, or they might be third-party, or their implementation may be overly dynamic, and so on).
To solve this,
stub files with the .pyi file extension
can be used to describe typing information for an external module. Those stub files omit
the implementation of classes and functions they describe, instead they only contain the
structure of the file (listing globals, functions, and classes with their members). The
recommended code style for those files is more terse than PEP 8:
prefer
...on the same line as the class/function signature;avoid vertical whitespace between consecutive module-level functions, names, or methods and fields within a single class;
use a single blank line between top-level class definitions, or none if the classes are very small.
Black enforces the above rules. There are additional guidelines for formatting .pyi
file that are not enforced yet but might be in a future version of the formatter:
all function bodies should be empty (contain
...instead of the body);do not use docstrings;
prefer
...overpass;for arguments with a default, use
...instead of the actual default;avoid using string literals in type annotations, stub files support forward references natively (like Python 3.7 code with
from __future__ import annotations);use variable annotations instead of type comments, even for stubs that target older versions of Python;
for arguments that default to
None, useOptional[]explicitly;use
floatinstead ofUnion[int, float].
Pragmatism¶
Early versions of Black used to be absolutist in some respects. They took after its initial author. This was fine at the time as it made the implementation simpler and there were not many users anyway. Not many edge cases were reported. As a mature tool, Black does make some exceptions to rules it otherwise holds. This section documents what those exceptions are and why this is the case.
The magic trailing comma¶
Black in general does not take existing formatting into account.
However, there are cases where you put a short collection or function call in your code but you anticipate it will grow in the future.
For example:
TRANSLATIONS = {
"en_us": "English (US)",
"pl_pl": "polski",
}
Early versions of Black used to ruthlessly collapse those into one line (it fits!). Now, you can communicate that you don’t want that by putting a trailing comma in the collection yourself. When you do, Black will know to always explode your collection into one item per line.
How do you make it stop? Just delete that trailing comma and Black will collapse your collection into one line if it fits.
If you must, you can recover the behaviour of early versions of Black with the option
--skip-magic-trailing-comma / -C.
r”strings” and R”strings”¶
Black normalizes string quotes as well as string prefixes, making them lowercase. One exception to this rule is r-strings. It turns out that the very popular MagicPython syntax highlighter, used by default by (among others) GitHub and Visual Studio Code, differentiates between r-strings and R-strings. The former are syntax highlighted as regular expressions while the latter are treated as true raw strings with no special semantics.
AST before and after formatting¶
When run with --safe, Black checks that the code before and after is semantically
equivalent. This check is done by comparing the AST of the source with the AST of the
target. There are three limited cases in which the AST does differ:
Black cleans up leading and trailing whitespace of docstrings, re-indenting them if needed. It’s been one of the most popular user-reported features for the formatter to fix whitespace issues with docstrings. While the result is technically an AST difference, due to the various possibilities of forming docstrings, all realtime use of docstrings that we’re aware of sanitizes indentation and leading/trailing whitespace anyway.
Black manages optional parentheses for some statements. In the case of the
delstatement, presence of wrapping parentheses or lack of thereof changes the resulting AST but is semantically equivalent in the interpreter.Black might move comments around, which includes type comments. Those are part of the AST as of Python 3.8. While the tool implements a number of special cases for those comments, there is no guarantee they will remain where they were in the source. Note that this doesn’t change runtime behavior of the source code.
To put things in perspective, the code equivalence check is a feature of Black which other formatters don’t implement at all. It is of crucial importance to us to ensure code behaves the way it did before it got reformatted. We treat this as a feature and there are no plans to relax this in the future. The exceptions enumerated above stem from either user feedback or implementation details of the tool. In each case we made due diligence to ensure that the AST divergence is of no practical consequence.
The (future of the) Black code style¶
Warning
Changes to this document often aren’t tied and don’t relate to releases of Black. It’s recommended that you read the latest version available.
Using backslashes for with statements¶
Backslashes are bad and should be never be used however
there is one exception: with statements using multiple context managers. Before Python
3.9 Python’s grammar does not allow organizing parentheses around the series of context
managers.
We don’t want formatting like:
with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
... # nothing to split on - line too long
So Black will eventually format it like this:
with \
make_context_manager(1) as cm1, \
make_context_manager(2) as cm2, \
make_context_manager(3) as cm3, \
make_context_manager(4) as cm4 \
:
... # backslashes and an ugly stranded colon
Although when the target version is Python 3.9 or higher, Black will use parentheses instead since they’re allowed in Python 3.9 and higher.
Improved string processing¶
Currently, Black does not split long strings to fit the line length limit. Currently, there is an experimental option to enable splitting strings. We plan to enable this option by default once it is fully stable. This is tracked in this issue.
Black is a PEP 8 compliant opinionated formatter with its own style.
It should be noted that while keeping the style unchanged throughout releases is a goal, the Black code style isn’t set in stone. Sometimes it’s modified in response to user feedback or even changes to the Python language!
Documentation for both the current and future styles can be found:
Getting Started¶
New to Black? Don’t worry, you’ve found the perfect place to get started!
Do you like the Black code style?¶
Before using Black on some of your code, it might be a good idea to first understand how Black will format your code. Black isn’t for everyone and you may find something that is a dealbreaker for you personally, which is okay! The current Black code style is described here.
Try it out online¶
Also, you can try out Black online for minimal fuss on the Black Playground generously created by José Padilla.
Installation¶
Black can be installed by running pip install black. It requires Python 3.6.2+ to
run, but can format Python 2 code too. Python 2 support needs the typed_ast
dependency, which be installed with pip install black[python2].
If you can’t wait for the latest hotness and want to install from GitHub, use:
pip install git+git://github.com/psf/black
Basic usage¶
To get started right away with sensible defaults:
black {source_file_or_directory}...
You can run Black as a package if running it as a script doesn’t work:
python -m black {source_file_or_directory}...
Next steps¶
Took a look at the Black code style and tried out Black? Fantastic, you’re ready for more. Why not explore some more on using Black by reading Usage and Configuration: The basics. Alternatively, you can check out the Introducing Black to your project guide.
Usage and Configuration¶
The basics¶
Foundational knowledge on using and configuring Black.
Black is a well-behaved Unix-style command-line tool:
it does nothing if no sources are passed to it;
it will read from standard input and write to standard output if
-is used as the filename;it only outputs messages to users on standard error;
exits with code 0 unless an internal error occurred (or
--checkwas used).
Usage¶
To get started right away with sensible defaults:
black {source_file_or_directory}
You can run Black as a package if running it as a script doesn’t work:
python -m black {source_file_or_directory}
Command line options¶
Black has quite a few knobs these days, although Black is opinionated so style
configuration options are deliberately limited and rarely added. You can list them by
running black --help.
Help output
Usage: black [OPTIONS] SRC ...
The uncompromising code formatter.
Options:
-c, --code TEXT Format the code passed in as a string.
-l, --line-length INTEGER How many characters per line to allow.
[default: 88]
-t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
Python versions that should be supported by
Black's output. [default: per-file auto-
detection]
--pyi Format all input files like typing stubs
regardless of file extension (useful when
piping source on standard input).
-S, --skip-string-normalization
Don't normalize string quotes or prefixes.
-C, --skip-magic-trailing-comma
Don't use trailing commas as a reason to
split lines.
--check Don't write the files back, just return the
status. Return code 0 means nothing would
change. Return code 1 means some files would
be reformatted. Return code 123 means there
was an internal error.
--diff Don't write the files back, just output a
diff for each file on stdout.
--color / --no-color Show colored diff. Only applies when
`--diff` is given.
--fast / --safe If --fast given, skip temporary sanity
checks. [default: --safe]
--required-version TEXT Require a specific version of Black to be
running (useful for unifying results across
many environments e.g. with a pyproject.toml
file).
--include TEXT A regular expression that matches files and
directories that should be included on
recursive searches. An empty value means all
files are included regardless of the name.
Use forward slashes for directories on all
platforms (Windows, too). Exclusions are
calculated first, inclusions later.
[default: \.pyi?$]
--exclude TEXT A regular expression that matches files and
directories that should be excluded on
recursive searches. An empty value means no
paths are excluded. Use forward slashes for
directories on all platforms (Windows, too).
Exclusions are calculated first, inclusions
later. [default: /(\.direnv|\.eggs|\.git|\.h
g|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn
|_build|buck-out|build|dist)/]
--extend-exclude TEXT Like --exclude, but adds additional files
and directories on top of the excluded ones.
(Useful if you simply want to add to the
default)
--force-exclude TEXT Like --exclude, but files and directories
matching this regex will be excluded even
when they are passed explicitly as
arguments.
--stdin-filename TEXT The name of the file when passing it through
stdin. Useful to make sure Black will
respect --force-exclude option on some
editors that rely on using stdin.
-q, --quiet Don't emit non-error messages to stderr.
Errors are still emitted; silence those with
2>/dev/null.
-v, --verbose Also emit messages to stderr about files
that were not changed or were ignored due to
exclusion patterns.
--version Show the version and exit.
--config FILE Read configuration from FILE path.
-h, --help Show this message and exit.
Code input alternatives¶
Black supports formatting code via stdin, with the result being printed to stdout.
Just let Black know with - as the path.
$ echo "print ( 'hello, world' )" | black -
print("hello, world")
reformatted -
All done! ✨ 🍰 ✨
1 file reformatted.
Tip: if you need Black to treat stdin input as a file passed directly via the CLI,
use --stdin-filename. Useful to make sure Black will respect the --force-exclude
option on some editors that rely on using stdin.
You can also pass code as a string using the -c / --code option.
$ black --code "print ( 'hello, world' )"
print("hello, world")
Writeback and reporting¶
By default Black reformats the files given and/or found in place. Sometimes you need Black to just tell you what it would do without actually rewriting the Python files.
There’s two variations to this mode that are independently enabled by their respective flags. Both variations can be enabled at once.
Passing --check will make Black exit with:
code 0 if nothing would change;
code 1 if some files would be reformatted; or
code 123 if there was an internal error
$ 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
error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source. Please report a bug on https://github.com/psf/black/issues. This diff might be helpful: /tmp/blk_kjdr1oog.log
Oh no! 💥 💔 💥
1 file would fail to reformat.
$ echo $?
123
Passing --diff will make Black print out diffs that indicate what changes Black
would’ve made. They are printed to stdout so capturing them is simple.
If you’d like colored diffs, you can enable them with the --color.
$ black test.py --diff
--- test.py 2021-03-08 22:23:40.848954 +0000
+++ test.py 2021-03-08 22:23:47.126319 +0000
@@ -1 +1 @@
-print ( 'hello, world' )
+print("hello, world")
would reformat test.py
All done! ✨ 🍰 ✨
1 file would be reformatted.
Output verbosity¶
Black in general tries to produce the right amount of output, balancing between usefulness and conciseness. By default, Black emits files modified and error messages, plus a short summary.
$ black src/
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
reformatted src/black_primer/lib.py
reformatted src/blackd/__init__.py
reformatted src/black/__init__.py
Oh no! 💥 💔 💥
3 files reformatted, 2 files left unchanged, 1 file failed to reformat.
Passing -v / --verbose will cause Black to also emit messages about files that
were not changed or were ignored due to exclusion patterns. If Black is using a
configuration file, a blue message detailing which one it is using will be emitted.
$ black src/ -v
Using configuration from /tmp/pyproject.toml.
src/blib2to3 ignored: matches the --extend-exclude regular expression
src/_black_version.py wasn't modified on disk since last run.
src/black/__main__.py wasn't modified on disk since last run.
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
reformatted src/black_primer/lib.py
reformatted src/blackd/__init__.py
reformatted src/black/__init__.py
Oh no! 💥 💔 💥
3 files reformatted, 2 files left unchanged, 1 file failed to reformat
Passing -q / --quiet will cause Black to stop emitting all non-critial output.
Error messages will still be emitted (which can silenced by 2>/dev/null).
$ black src/ -q
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
Versions¶
You can check the version of Black you have installed using the --version flag.
$ black --version
black, version 21.5b0
An option to require a specific version to be running is also provided.
$ black --required-version 21.5b2 -c "format = 'this'"
format = "this"
$ black --required-version 31.5b2 -c "still = 'beta?!'"
Oh no! 💥 💔 💥 The required version does not match the running version!
This is useful for example when running Black in multiple environments that haven’t necessarily installed the correct version. This option can be set in a configuration file for consistent results across environments.
Configuration via a file¶
Black is able to read project-specific default values for its command line options
from a pyproject.toml file. This is especially useful for specifying custom
--include and --exclude/--force-exclude/--extend-exclude patterns for your
project.
Pro-tip: If you’re asking yourself “Do I need to configure anything?” the answer is “No”. Black is all about sensible defaults. Applying those defaults will have your code in compliance with many other Black formatted projects.
What on Earth is a pyproject.toml file?¶
PEP 518 defines pyproject.toml as a
configuration file to store build system requirements for Python projects. With the help
of tools like Poetry or
Flit it can fully replace the need for
setup.py and setup.cfg files.
Where Black looks for the file¶
By default Black looks for pyproject.toml starting from the common base directory of
all files and directories passed on the command line. If it’s not there, it looks in
parent directories. It stops looking when it finds the file, or a .git directory, or a
.hg directory, or the root of the file system, whichever comes first.
If you’re formatting standard input, Black will look for configuration starting from the current working directory.
You can use a “global” configuration, stored in a specific location in your home directory. This will be used as a fallback configuration, that is, it will be used if and only if Black doesn’t find any configuration as mentioned above. Depending on your operating system, this configuration file should be stored as:
Windows:
~\.blackUnix-like (Linux, MacOS, etc.):
$XDG_CONFIG_HOME/black(~/.config/blackif theXDG_CONFIG_HOMEenvironment variable is not set)
Note that these are paths to the TOML file itself (meaning that they shouldn’t be named
as pyproject.toml), not directories where you store the configuration. Here, ~
refers to the path to your home directory. On Windows, this will be something like
C:\\Users\UserName.
You can also explicitly specify the path to a particular file that you want with
--config. In this situation Black will not look for any other file.
If you’re running with --verbose, you will see a blue message if a file was found and
used.
Please note blackd will not use pyproject.toml configuration.
Configuration format¶
As the file extension suggests, pyproject.toml is a
TOML file. It contains separate sections for
different tools. Black is using the [tool.black] section. The option keys are the
same as long names of options on the command line.
Note that you have to use single-quoted strings in TOML for regular expressions. It’s
the equivalent of r-strings in Python. Multiline strings are treated as verbose regular
expressions by Black. Use [ ] to denote a significant space character.
Example pyproject.toml
[tool.black]
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# in the root of the project.
^/foo.py # exclude a file named foo.py in the root of the project (in addition to the defaults)
'''
Lookup hierarchy¶
Command-line options have defaults that you can see in --help. A pyproject.toml can
override those defaults. Finally, options provided by the user on the command line
override both.
Black will only ever use one pyproject.toml file during an entire run. It doesn’t
look for multiple files, and doesn’t compose configuration from different levels of the
file hierarchy.
Next steps¶
You’ve probably noted that not all of the options you can pass to Black have been covered. Don’t worry, the rest will be covered in a later section.
A good next step would be configuring auto-discovery so black . is all you need
instead of laborously listing every file or directory. You can get started by heading
over to File collection and discovery.
Another good choice would be setting up an integration with your editor of choice or with pre-commit for source version control.
File collection and discovery¶
You can directly pass Black files, but you can also pass directories and Black will walk them, collecting files to format. It determines what files to format or skip automatically using the inclusion and exclusion regexes and as well their modification time.
Ignoring unmodified files¶
Black remembers files it has already formatted, unless the --diff flag is used or
code is passed via standard input. This information is stored per-user. The exact
location of the file depends on the Black version and the system on which Black is
run. The file is non-portable. The standard location on common operating systems is:
Windows:
C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.<file-mode>.picklemacOS:
/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickleLinux:
/home/<username>/.cache/black/<version>/cache.<line-length>.<file-mode>.pickle
file-mode is an int flag that determines whether the file was formatted as 3.6+ only,
as .pyi, and whether string normalization was omitted.
To override the location of these files on macOS or Linux, set the environment variable
XDG_CACHE_HOME to your preferred location. For example, if you want to put the cache
in the directory you’re running Black from, set XDG_CACHE_HOME=.cache. Black will
then write the above files to .cache/black/<version>/.
.gitignore¶
If --exclude is not set, Black will automatically ignore files and directories in
.gitignore file(s), if present.
If you want Black to continue using .gitignore while also configuring the exclusion
rules, please use --extend-exclude.
Black as a server (blackd)¶
blackd is a small HTTP server that exposes Black’s functionality over a simple
protocol. The main benefit of using it is to avoid the cost of starting up a new Black
process every time you want to blacken a file.
Usage¶
blackd is not packaged alongside Black by default because it has additional
dependencies. You will need to execute pip install black[d] to install it.
You can start the server on the default port, binding only to the local interface by
running blackd. You will see a single line mentioning the server’s version, and the
host and port it’s listening on. blackd will then print an access log similar to most
web servers on standard output, merged with any exception traces caused by invalid
formatting requests.
blackd provides even less options than Black. You can see them by running
blackd --help:
Usage: blackd [OPTIONS]
Options:
--bind-host TEXT Address to bind the server to.
--bind-port INTEGER Port to listen on
--version Show the version and exit.
-h, --help Show this message and exit.
There is no official blackd client tool (yet!). You can test that blackd is working
using curl:
blackd --bind-port 9090 & # or let blackd choose a port
curl -s -XPOST "localhost:9090" -d "print('valid')"
Protocol¶
blackd only accepts POST requests at the / path. The body of the request should
contain the python source code to be formatted, encoded according to the charset field
in the Content-Type request header. If no charset is specified, blackd assumes
UTF-8.
There are a few HTTP headers that control how the source code is formatted. These
correspond to command line flags for Black. There is one exception to this:
X-Protocol-Version which if present, should have the value 1, otherwise the request
is rejected with HTTP 501 (Not Implemented).
The headers controlling how source code is formatted are:
X-Line-Length: corresponds to the--line-lengthcommand line flag.X-Skip-String-Normalization: corresponds to the--skip-string-normalizationcommand line flag. If present and its value is not the empty string, no string normalization will be performed.X-Skip-Magic-Trailing-Comma: corresponds to the--skip-magic-trailing-commacommand line flag. If present and its value is not the empty string, trailing commas will not be used as a reason to split lines.X-Fast-Or-Safe: if set tofast,blackdwill act as Black does when passed the--fastcommand line flag.X-Python-Variant: if set topyi,blackdwill act as Black does when passed the--pyicommand line flag. Otherwise, its value must correspond to a Python version or a set of comma-separated Python versions, optionally prefixed withpy. For example, to request code that is compatible with Python 3.5 and 3.6, set the header topy3.5,py3.6.X-Diff: corresponds to the--diffcommand line flag. If present, a diff of the formats will be output.
If any of these headers are set to invalid values, blackd returns a HTTP 400 error
response, mentioning the name of the problematic header in the message body.
Apart from the above, blackd can produce the following response codes:
HTTP 204: If the input is already well-formatted. The response body is empty.HTTP 200: If formatting was needed on the input. The response body contains the blackened Python code, and theContent-Typeheader is set accordingly.HTTP 400: If the input contains a syntax error. Details of the error are returned in the response body.HTTP 500: If there was any other kind of error while trying to format the input. The response body contains a textual representation of the error.
The response headers include a X-Black-Version header containing the version of
Black.
Sometimes, running Black with its defaults and passing filepaths to it just won’t cut it. Passing each file using paths will become burdensome, and maybe you would like Black to not touch your files and just output diffs. And yes, you can tweak certain parts of Black’s style, but please know that configurability in this area is purposefully limited.
Using many of these more advanced features of Black will require some configuration. Configuration that will either live on the command line or in a TOML configuration file.
This section covers features of Black and configuring Black in detail:
Integrations¶
Editor integration¶
PyCharm/IntelliJ IDEA¶
Install
black.$ pip install blackLocate your
blackinstallation folder.On macOS / Linux / BSD:
$ which black /usr/local/bin/black # possible location
On Windows:
$ where black %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
Note that if you are using a virtual environment detected by PyCharm, this is an unneeded step. In this case the path to
blackis$PyInterpreterDirectory$/black.Open External tools in PyCharm/IntelliJ IDEA
On macOS:
PyCharm -> Preferences -> Tools -> External ToolsOn Windows / Linux / BSD:
File -> Settings -> Tools -> External ToolsClick the + icon to add a new external tool with the following values:
Name: Black
Description: Black is the uncompromising Python code formatter.
Program: <install_location_from_step_2>
Arguments:
"$FilePath$"
Format the currently opened file by selecting
Tools -> External Tools -> black.Alternatively, you can set a keyboard shortcut by navigating to
Preferences or Settings -> Keymap -> External Tools -> External Tools - Black.
Optionally, run Black on every file save:
Make sure you have the File Watchers plugin installed.
Go to
Preferences or Settings -> Tools -> File Watchersand click+to add a new watcher:Name: Black
File type: Python
Scope: Project Files
Program: <install_location_from_step_2>
Arguments:
$FilePath$Output paths to refresh:
$FilePath$Working directory:
$ProjectFileDir$
In Advanced Options
Uncheck “Auto-save edited files to trigger the watcher”
Uncheck “Trigger the watcher on external changes”
Wing IDE¶
Wing supports black via the OS Commands tool, as explained in the Wing documentation on pep8 formatting. The detailed procedure is:
Install
black.$ pip install blackMake sure it runs from the command line, e.g.
$ black --helpIn Wing IDE, activate the OS Commands panel and define the command black to execute black on the currently selected file:
Use the Tools -> OS Commands menu selection
click on + in OS Commands -> New: Command line..
Title: black
Command Line: black %s
I/O Encoding: Use Default
Key Binding: F1
[x] Raise OS Commands when executed
[x] Auto-save files before execution
[x] Line mode
Select a file in the editor and press F1 , or whatever key binding you selected in step 3, to reformat the file.
Vim¶
Official plugin¶
Commands and shortcuts:
:Blackto format the entire file (ranges not supported);:BlackUpgradeto upgrade Black inside the virtualenv;:BlackVersionto get the current version of Black inside the virtualenv.
Configuration:
g:black_fast(defaults to0)g:black_linelength(defaults to88)g:black_skip_string_normalization(defaults to0)g:black_virtualenv(defaults to~/.vim/blackor~/.local/share/nvim/black)g:black_quiet(defaults to0)
To install with vim-plug:
Plug 'psf/black', { 'branch': 'stable' }
or with Vundle:
Plugin 'psf/black'
and execute the following in a terminal:
$ cd ~/.vim/bundle/black
$ git checkout origin/stable -b stable
or you can copy the plugin files from plugin/black.vim and autoload/black.vim.
mkdir -p ~/.vim/pack/python/start/black/plugin
mkdir -p ~/.vim/pack/python/start/black/autoload
curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim
Let me know if this requires any changes to work with Vim 8’s builtin packadd, or
Pathogen, and so on.
This plugin requires Vim 7.0+ built with Python 3.6+ support. It needs Python 3.6 to be able to run Black inside the Vim process which is much faster than calling an external command.
On first run, the plugin creates its own virtualenv using the right Python version and
automatically installs Black. You can upgrade it later by calling :BlackUpgrade and
restarting Vim.
If you need to do anything special to make your virtualenv work and install Black (for
example you want to run a version from main), create a virtualenv manually and point
g:black_virtualenv to it. The plugin will use it.
To run Black on save, add the following line to .vimrc or init.vim:
autocmd BufWritePre *.py execute ':Black'
To run Black on a key press (e.g. F9 below), add this:
nnoremap <F9> :Black<CR>
How to get Vim with Python 3.6? On Ubuntu 17.10 Vim comes with Python 3.6 by
default. On macOS with Homebrew run: brew install vim. When building Vim from source,
use: ./configure --enable-python3interp=yes. There’s many guides online how to do
this.
I get an import error when using Black from a virtual environment: If you get an error message like this:
Traceback (most recent call last):
File "<string>", line 63, in <module>
File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
from typed_ast import ast3, ast27
File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
from typed_ast import _ast3
ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
Then you need to install typed_ast and regex directly from the source code. The
error happens because pip will download Python wheels if
they are available. Python wheels are a new standard of distributing Python packages and
packages that have Cython and extensions written in C are already compiled, so the
installation is much more faster. The problem here is that somehow the Python
environment inside Vim does not match with those already compiled C extensions and these
kind of errors are the result. Luckily there is an easy fix: installing the packages
from the source code.
The two packages that cause the problem are:
Now remove those two packages:
$ pip uninstall regex typed-ast -y
And now you can install them with:
$ pip install --no-binary :all: regex typed-ast
The C extensions will be compiled and now Vim’s Python environment will match. Note that
you need to have the GCC compiler and the Python development files installed (on
Ubuntu/Debian do sudo apt-get install build-essential python3-dev).
If you later want to update Black, you should do it like this:
$ pip install -U black --no-binary regex,typed-ast
Gedit¶
gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit as
$ gedit <file_name>
Go to edit > preferences > pluginsSearch for
external toolsand activate it.In
Tools menu -> Manage external toolsAdd a new tool using
+button.Copy the below content to the code window.
#!/bin/bash
Name=$GEDIT_CURRENT_DOCUMENT_NAME
black $Name
Set a keyboard shortcut if you like, Ex.
ctrl-BSave:
NothingInput:
NothingOutput:
Display in bottom paneif you like.Change the name of the tool if you like.
Use your keyboard shortcut or Tools -> External Tools to use your new tool. When you
close and reopen your File, Black will be done with its job.
Visual Studio Code¶
Use the Python extension (instructions).
SublimeText 3¶
Use sublack plugin.
Jupyter Notebook Magic¶
Use blackcellmagic.
Python Language Server¶
If your editor supports the Language Server Protocol (Atom, Sublime Text, Visual Studio Code and many more), you can use the Python Language Server with the pyls-black plugin.
Atom/Nuclide¶
Use python-black or formatters-python.
Kakoune¶
Add the following hook to your kakrc, then run Black with :format.
hook global WinSetOption filetype=python %{
set-option window formatcmd 'black -q -'
}
Thonny¶
GitHub Actions integration¶
You can use Black within a GitHub Actions workflow without setting your own Python environment. Great for enforcing that your code matches the Black code style.
Compatibility¶
This action is known to support all GitHub-hosted runner OSes. In addition, only published versions of Black are supported (i.e. whatever is available on PyPI).
Finally, this action installs Black with both the colorama and python2 extras so
the --color flag and formatting Python 2 code are supported.
Usage¶
Create a file named .github/workflows/black.yml inside your repository with:
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: psf/black@stable
We recommend the use of the @stable tag, but per version tags also exist if you prefer
that. Note that the action’s version you select is independent of the version of Black
the action will use.
The version of Black the action will use can be configured via version. The action
defaults to the latest release available on PyPI. Only versions available from PyPI are
supported, so no commit SHAs or branch names.
You can also configure the arguments passed to Black via options (defaults to
'--check --diff') and src (default is '.')
Here’s an example configuration:
- uses: psf/black@stable
with:
options: "--check --verbose"
src: "./src"
version: "21.5b1"
Version control integration¶
Use pre-commit. Once you
have it installed, add this to the
.pre-commit-config.yaml in your repository:
repos:
- repo: https://github.com/psf/black
rev: stable # Replace by any tag/version: https://github.com/psf/black/tags
hooks:
- id: black
language_version: python3 # Should be a command that runs python3.6+
Black can be integrated into many environments, providing a better and smoother experience. Documentation for integrating Black with a tool can be found for the following areas:
Editors and tools not listed will require external contributions.
Patches welcome! ✨ 🍰 ✨
Any tool can pipe code through Black using its stdio mode (just
use `-` as the file name).
The formatted code will be returned on stdout (unless --check was passed). Black
will still emit messages on stderr but that shouldn’t affect your use case.
This can be used for example with PyCharm’s or IntelliJ’s File Watchers.
Guides¶
Introducing Black to your project¶
Note
This guide is incomplete. Contributions are welcomed and would be deeply appreciated!
Avoiding ruining git blame¶
A long-standing argument against moving to automated code formatters like Black is
that the migration will clutter up the output of git blame. This was a valid argument,
but since Git version 2.23, Git natively supports
ignoring revisions in blame
with the --ignore-rev option. You can also pass a file listing the revisions to ignore
using the --ignore-revs-file option. The changes made by the revision will be ignored
when assigning blame. Lines modified by an ignored revision will be blamed on the
previous revision that modified those lines.
So when migrating your project’s code style to Black, reformat everything and commit the changes (preferably in one massive commit). Then put the full 40 characters commit identifier(s) into a file.
# Migrate code style to Black
5b4ab991dede475d393e9d69ec388fd6bd949699
Afterwards, you can pass that file to git blame and see clean and meaningful blame
information.
$ git blame important.py --ignore-revs-file .git-blame-ignore-revs
7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
abdfd8b0 (Alice Doe 2019-09-23 11:39:32 -0400 2) text = text.lstrip()
7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3) with open(file, "r+") as f:
7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4) f.write(formatted)
You can even configure git to automatically ignore revisions listed in a file on every
call to git blame.
$ git config blame.ignoreRevsFile .git-blame-ignore-revs
The one caveat is that GitHub and GitLab do not yet support ignoring revisions using their native UI of blame. So blame information will be cluttered with a reformatting commit on those platforms. (If you’d like this feature, there’s an open issue for GitLab and please let GitHub know!)
Using Black with other tools¶
Black compatible configurations¶
All of Black’s changes are harmless (or at least, they should be), but a few do conflict against other tools. It is not uncommon to be using other tools alongside Black like linters and type checkers. Some of them need a bit of tweaking to resolve the conflicts. Listed below are Black compatible configurations in various formats for the common tools out there.
Please note that Black only supports the TOML file format for its configuration
(e.g. pyproject.toml). The provided examples are to only configure their corresponding
tools, using their supported file formats.
Compatible configuration files can be found here.
isort¶
isort helps to sort and format imports in your Python code. Black also formats imports, but in a different way from isort’s defaults which leads to conflicting changes.
Since version 5.0.0, isort supports
profiles to allow easy
interoperability with common code styles. You can set the black profile in any of the
config files
supported by isort. Below, an example for pyproject.toml:
[tool.isort]
profile = "black"
If you’re using an isort version that is older than 5.0.0 or you have some custom
configuration for Black, you can tweak your isort configuration to make it compatible
with Black. Below, an example for .isort.cfg:
multi_line_output = 3
include_trailing_comma = True
force_grid_wrap = 0
use_parentheses = True
ensure_newline_before_comments = True
line_length = 88
Black wraps imports that surpass line-length by moving identifiers into their own
indented line. If that still doesn’t fit the bill, it will put all of them in separate
lines and put a trailing comma. A more detailed explanation of this behaviour can be
found here.
isort’s default mode of wrapping imports that extend past the line_length limit is
“Grid”.
from third_party import (lib1, lib2, lib3,
lib4, lib5, ...)
This style is incompatible with Black, but isort can be configured to use a different wrapping mode called “Vertical Hanging Indent” which looks like this:
from third_party import (
lib1,
lib2,
lib3,
lib4,
)
This style is Black compatible and can be achieved by multi-line-output = 3. Also,
as mentioned above, when wrapping long imports Black puts a trailing comma and uses
parentheses. isort should follow the same behaviour and passing the options
include_trailing_comma = True and use_parentheses = True configures that.
The option force_grid_wrap = 0 is just to tell isort to only wrap imports that surpass
the line_length limit.
Finally, isort should be told to wrap imports when they surpass Black’s default limit
of 88 characters via line_length = 88 as well as
ensure_newline_before_comments = True to ensure spacing import sections with comments
works the same as with Black.
Please note ensure_newline_before_comments = True only works since isort >= 5 but
does not break older versions so you can keep it if you are running previous versions.
.isort.cfg
[settings]
profile = black
setup.cfg
[isort]
profile = black
pyproject.toml
[tool.isort]
profile = 'black'
.editorconfig
[*.py]
profile = black
Flake8¶
Flake8 is a code linter. It warns you of syntax errors, possible bugs, stylistic errors, etc. For the most part, Flake8 follows PEP 8 when warning about stylistic errors. There are a few deviations that cause incompatibilities with Black.
max-line-length = 88
extend-ignore = E203
In some cases, as determined by PEP 8, Black will enforce an equal amount of
whitespace around slice operators. Due to this, Flake8 will raise
E203 whitespace before ':' warnings. Since this warning is not PEP 8 compliant, Flake8
should be configured to ignore it via extend-ignore = E203.
When breaking a line, Black will break it before a binary operator. This is compliant
with PEP 8 as of
April 2016.
There’s a disabled-by-default warning in Flake8 which goes against this PEP 8
recommendation called W503 line break before binary operator. It should not be enabled
in your configuration.
Also, as like with isort, flake8 should be configured to allow lines up to the length
limit of 88, Black’s default. This explains max-line-length = 88.
.flake8
[flake8]
max-line-length = 88
extend-ignore = E203
setup.cfg
[flake8]
max-line-length = 88
extend-ignore = E203
tox.ini
[flake8]
max-line-length = 88
extend-ignore = E203
Pylint¶
Pylint is also a code linter like Flake8. It has the same checks as flake8 and more. In particular, it has more formatting checks regarding style conventions like variable naming. With so many checks, Pylint is bound to have some mixed feelings about Black’s formatting style.
disable = C0330, C0326
max-line-length = 88
When Black is folding very long expressions, the closing brackets will be dedented.
ImportantClass.important_method(
exc, limit, lookup_lines, capture_locals, callback
)
Although this style is PEP 8 compliant, Pylint will raise
C0330: Wrong hanging indentation before block (add 4 spaces) warnings. Since Black
isn’t configurable on this style, Pylint should be told to ignore these warnings via
disable = C0330.
Also, since Black deals with whitespace around operators and brackets, Pylint’s
warning C0326: Bad whitespace should be disabled using disable = C0326.
And as usual, Pylint should be configured to only complain about lines that surpass 88
characters via max-line-length = 88.
pylintrc
[MESSAGES CONTROL]
disable = C0330, C0326
[format]
max-line-length = 88
setup.cfg
[pylint]
max-line-length = 88
[pylint.messages_control]
disable = C0330, C0326
pyproject.toml
[tool.pylint.messages_control]
disable = "C0330, C0326"
[tool.pylint.format]
max-line-length = "88"
Wondering how to do something specific? You’ve found the right place! Listed below are topic specific guides available:
Frequently Asked Questions¶
The most common questions and issues users face are aggregated to this FAQ.
Does Black have an API?¶
Not yet. Black is fundamentally a command line tool. Many integrations are provided, but a Python interface is not one of them. A simple API is being planned though.
Is Black safe to use?¶
Yes, for the most part. Black is strictly about formatting, nothing else. But because
Black is still in beta, some edges are still a bit rough. To combat
issues, the equivalence of code after formatting is
checked with
limited special cases where the code is allowed to differ. If issues are found, an error
is raised and the file is left untouched. Magical comments that influence linters and
other tools, such as # noqa, may be moved by Black. See below for more details.
How stable is Black’s style?¶
Quite stable. Black aims to enforce one style and one style only, with some room for pragmatism. However, Black is still in beta so style changes are both planned and still proposed on the issue tracker. See The Black Code Style for more details.
Why is my file not formatted?¶
Most likely because it is ignored in .gitignore or excluded with configuration. See
file collection and discovery
for details.
Why are Flake8’s E203 and W503 violated?¶
Because they go against PEP 8. E203 falsely triggers on list slices, and adhering to W503 hinders readability because operators are misaligned. Disable W503 and enable the disabled-by-default counterpart W504. E203 should be disabled while changes are still discussed.
Does Black support Python 2?¶
For formatting, yes! Install with the python2 extra
to format Python 2 files too! There are no current plans to drop support, but most
likely it is bound to happen. Sometime. Eventually. In terms of running Black though,
Python 3.6 or newer is required.
Why does my linter or typechecker complain after I format my code?¶
Some linters and other tools use magical comments (e.g., # noqa, # type: ignore) to
influence their behavior. While Black does its best to recognize such comments and leave
them in the right place, this detection is not and cannot be perfect. Therefore, you’ll
sometimes have to manually move these comments to the right place after you format your
codebase with Black.
Contributing¶
The basics¶
An overview on contributing to the Black project.
Technicalities¶
Development on the latest version of Python is preferred. As of this writing it’s 3.9. You can use any operating system.
Install all development dependencies using:
$ pipenv install --dev
$ pipenv shell
$ pre-commit install
If you haven’t used pipenv before but are comfortable with virtualenvs, just run
pip install pipenv in the virtualenv you’re already using and invoke the command above
from the cloned Black repo. It will do the correct thing.
Non pipenv install works too:
$ pip install -r test_requirements.txt
$ pip install -e .[d]
Before submitting pull requests, run lints and tests with the following commands from the root of the black repo:
# Linting
$ pre-commit run -a
# Unit tests
$ tox -e py
# Optional Fuzz testing
$ tox -e fuzz
# Optional CI run to test your changes on many popular python projects
$ black-primer [-k -w /tmp/black_test_repos]
News / Changelog Requirement¶
Black has CI that will check for an entry corresponding to your PR in CHANGES.md. If
you feel this PR does not require a changelog entry please state that in a comment and a
maintainer can add a skip news label to make the CI pass. Otherwise, please ensure you
have a line in the following format:
- `Black` is now more awesome (#X)
Note that X should be your PR number, not issue number! To workout X, please use
Next PR Number. This
is not perfect but saves a lot of release overhead as now the releaser does not need to
go back and workout what to add to the CHANGES.md for each release.
Style Changes¶
If a change would affect the advertised code style, please modify the documentation (The Black code style) to reflect that change. Patches that fix unintended bugs in formatting don’t need to be mentioned separately though.
Docs Testing¶
If you make changes to docs, you can test they still build locally too.
$ pip install -r docs/requirements.txt
$ pip install [-e] .[d]
$ sphinx-build -a -b html -W docs/ docs/_build/
black-primer¶
black-primer is used by CI to pull down well-known Black formatted projects and see
if we get source code changes. It will error on formatting changes or errors. Please run
before pushing your PR to see if you get the actions you would expect from Black with
your PR. You may need to change
primer.json
configuration for it to pass.
For more black-primer information visit the
documentation.
Hygiene¶
If you’re fixing a bug, add a test. Run it first to confirm it fails, then fix the bug, run it again to confirm it’s really fixed.
If adding a new feature, add a test. In fact, always add a test. But wait, before adding any large feature, first open an issue for us to discuss the idea first.
Finally¶
Thanks again for your interest in improving the project! You’re taking action when most people decide to sit and watch.
Gauging changes¶
A lot of the time, your change will affect formatting and/or performance. Quantifying these changes is hard, so we have tooling to help make it easier.
It’s recommended you evaluate the quantifiable changes your Black formatting modification causes before submitting a PR. Think about if the change seems disruptive enough to cause frustration to projects that are already “black formatted”.
black-primer¶
black-primer is a tool built for CI (and humans) to have Black --check a number of
Git accessible projects in parallel. (configured in primer.json) (A PR will be
accepted to add Mercurial support.)
Run flow¶
Ensure we have a
black+gitin PATHLoad projects from
primer.jsonRun projects in parallel with
--workerworkers (defaults to CPU count / 2)Checkout projects
Run black and record result
Clean up repository checkout (can optionally be disabled via
--keep)
Display results summary to screen
Default to cleaning up
--work-dir(which defaults to tempfile schemantics)Return
0 for successful run
< 0 for environment / internal error
> 0 for each project with an error
Speed up runs 🏎¶
If you’re running locally yourself to test black on lots of code try:
Using
-k/--keep+-w/--work-dirso you don’t have to re-checkout the repo each run
CLI arguments¶
Usage: black-primer [OPTIONS]
primer - prime projects for blackening... 🏴
Options:
-c, --config PATH JSON config file path [default: /home/docs/checkouts
/readthedocs.org/user_builds/black/envs/hello-rtd-
theme/lib/python3.8/site-
packages/black_primer/primer.json]
--debug Turn on debug logging [default: False]
-k, --keep Keep workdir + repos post run [default: False]
-L, --long-checkouts Pull big projects to test [default: False]
--no-diff Disable showing source file changes in black output
[default: False]
-R, --rebase Rebase project if already checked out [default:
False]
-w, --workdir PATH Directory path for repo checkouts [default:
/tmp/primer.20210724224300]
-W, --workers INTEGER Number of parallel worker coroutines [default: 2]
-h, --help Show this message and exit.
Issue triage¶
Currently, Black uses the issue tracker for bugs, feature requests, proposed design modifications, and general user support. Each of these issues have to be triaged so they can be eventually be resolved somehow. This document outlines the triaging process and also the current guidelines and recommendations.
Tip
If you’re looking for a way to contribute without submitting patches, this might be the area for you. Since Black is a popular project, its issue tracker is quite busy and always needs more attention than is available. While triage isn’t the most glamorous or technically challenging form of contribution, it’s still important. For example, we would love to know whether that old bug report is still reproducible!
You can get easily started by reading over this document and then responding to issues.
If you contribute enough and have stayed for a long enough time, you may even be given Triage permissions!
The basics¶
Black gets a whole bunch of different issues, they range from bug reports to user support issues. To triage is to identify, organize, and kickstart the issue’s journey through its lifecycle to resolution.
More specifically, to triage an issue means to:
identify what type and categories the issue falls under
confirm bugs
ask questions / for further information if necessary
link related issues
provide the first initial feedback / support
Note that triage is typically the first response to an issue, so don’t fret if the issue doesn’t make much progress after initial triage. The main goal of triaging to prepare the issue for future more specific development or discussion, so eventually it will be resolved.
The lifecycle of a bug report or user support issue typically goes something like this:
the issue is waiting for triage
identified - has been marked with a type label and other relevant labels, more details or a functional reproduction may be still needed (and therefore should be marked with
S: needs reproorS: awaiting reponse)confirmed - the issue can reproduced and necessary details have been provided
discussion - initial triage has been done and now the general details on how the issue should be best resolved are being hashed out
awaiting fix - no further discussion on the issue is necessary and a resolving PR is the next step
closed - the issue has been resolved, reasons include:
the issue couldn’t be reproduced
the issue has been fixed
duplicate of another pre-existing issue or is invalid
For enhancement, documentation, and design issues, the lifecycle looks very similar but the details are different:
the issue is waiting for triage
identified - has been marked with a type label and other relevant labels
discussion - the merits of the suggested changes are currently being discussed, a PR would be acceptable but would be at sigificant risk of being rejected
accepted & awaiting PR - it’s been determined the suggested changes are OK and a PR would be welcomed (
S: accepted)closed: - the issue has been resolved, reasons include:
the suggested changes were implemented
it was rejected (due to technical concerns, ethos conflicts, etc.)
duplicate of a pre-existing issue or is invalid
Note: documentation issues don’t use the S: accepted label currently since they’re
less likely to be rejected.
Labelling¶
We use labels to organize, track progress, and help effectively divvy up work.
Our labels are divided up into several groups identified by their prefix:
T - Type: the general flavor of issue / PR
C - Category: areas of concerns, ranges from bug types to project maintenance
F - Formatting Area: like C but for formatting specifically
S - Status: what stage of resolution is this issue currently in?
R - Resolution: how / why was the issue / PR resolved?
We also have a few standalone labels:
good first issue: issues that are beginner-friendly (and will show up in GitHub banners for first-time visitors to the repository)help wanted: complex issues that need and are looking for a fair bit of work as to progress (will also show up in various GitHub pages)skip news: for PRs that are trivial and don’t need a CHANGELOG entry (and skips the CHANGELOG entry check)
Note
We do use labels for PRs, in particular the skip news label, but we aren’t that
rigorous about it. Just follow your judgement on what labels make sense for the
specific PR (if any even make sense).
Projects¶
For more general and broad goals we use projects to track work. Some may be longterm projects with no true end (e.g. the “Amazing documentation” project) while others may be more focused and have a definite end (like the “Getting to beta” project).
Note
To modify GitHub Projects you need the Write repository permission level or higher.
Closing issues¶
Closing an issue signifies the issue has reached the end of its life, so closing issues should be taken with care. The following is the general recommendation for each type of issue. Note that these are only guidelines and if your judgement says something else it’s totally cool to go with it instead.
For most issues, closing the issue manually or automatically after a resolving PR is
ideal. For bug reports specifically, if the bug has already been fixed, try to check in
with the issue opener that their specific case has been resolved before closing. Note
that we close issues as soon as they’re fixed in the main branch. This doesn’t
necessarily mean they’ve been released yet.
Design and enhancement issues should be also closed when it’s clear the proposed change won’t be implemented, whether that has been determined after a lot of discussion or just simply goes against Black’s ethos. If such an issue turns heated, closing and locking is acceptable if it’s severe enough (although checking in with the core team is probably a good idea).
User support issues are best closed by the author or when it’s clear the issue has been resolved in some sort of manner.
Duplicates and invalid issues should always be closed since they serve no purpose and add noise to an already busy issue tracker. Although be careful to make sure it’s truly a duplicate and not just very similar before labelling and closing an issue as duplicate.
Common reports¶
Some issues are frequently opened, like issues about Black formatted code causing E203 messages. Even though these issues are probably heavily duplicated, they still require triage sucking up valuable time from other things (although they usually skip most of their lifecycle since they’re closed on triage).
Here’s some of the most common issues and also pre-made responses you can use:
“The trailing comma isn’t being removed by Black!”¶
Black used to remove the trailing comma if the expression fits in a single line, but this was changed by #826 and #1288. Now a trailing comma tells Black to always explode the expression. This change was made mostly for the cases where you _know_ a collection or whatever will grow in the future. Having it always exploded as one element per line reduces diff noise when adding elements. Before the "magic trailing comma" feature, you couldn't anticipate a collection's growth reliably since collections that fitted in one line were ruthlessly collapsed regardless of your intentions. One of Black's goals is reducing diff noise, so this was a good pragmatic change.
So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma", including the ability to skip this functionality with the `--skip-magic-trailing-comma` option. Hopefully that helps solve the possible confusion.
“Black formatted code is violating Flake8’s E203!”¶
Hi,
This is expected behaviour, please see the documentation regarding this case (emphasis
mine):
> PEP 8 recommends to treat : in slices as a binary operator with the lowest priority, and to leave an equal amount of space on either side, **except if a parameter is omitted (e.g. ham[1 + 1 :])**. It recommends no spaces around : operators for “simple expressions” (ham[lower:upper]), and **extra space for “complex expressions” (ham[lower : upper + offset])**. **Black treats anything more than variable names as “complex” (ham[lower : upper + 1]).** It also states that for extended slices, both : operators have to have the same amount of spacing, except if a parameter is omitted (ham[1 + 1 ::]). Black enforces these rules consistently.
> This behaviour may raise E203 whitespace before ':' warnings in style guide enforcement tools like Flake8. **Since E203 is not PEP 8 compliant, you should tell Flake8 to ignore these warnings**.
https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#slices
Have a good day!
Release process¶
Black has had a lot of work automating its release process. This document sets out to explain what everything does and how to release Black using said automation.
Cutting a Release¶
To cut a release, you must be a Black maintainer with GitHub Release creation
access. Using this access, the release process is:
Cut a new PR editing
CHANGES.mdto version the latest changesExample PR: https://github.com/psf/black/pull/2192
Example title:
Update CHANGES.md for XX.X release
Once the release PR is merged ensure all CI passes
If not, ensure there is an Issue open for the cause of failing CI (generally we’d want this fixed before cutting a release)
Open
CHANGES.mdand copy the raw markdown of the latest changes to use in the description of the GitHub Release.Go and cut a release using the GitHub UI so that all workflows noted below are triggered.
The release version and tag should be the CalVer version Black used for the current release e.g.
21.6/21.5b1Black uses setuptools scm to pull the current version for the package builds and release.
Once the release is cut, you’re basically done. It’s a good practice to go and watch to make sure all the GitHub Actions pass, although you should receive an email to your registered GitHub email address should one fail.
You should see all the release workflows and lint/unittests workflows running on the new tag in the Actions UI
If anything fails, please go read the respective action’s log output and configuration file to reverse engineer your way to a fix/soluton.
Release workflows¶
All Blacks’s automation workflows use GitHub Actions. All workflows are therefore
configured using .yml files in the .github/workflows directory of the Black
repository.
Below are descriptions of our release workflows.
Docker¶
This workflow uses the QEMU powered buildx feature of docker to upload a arm64 and
amd64/x86_64 build of the official Black docker image™.
Currently this workflow uses an API Token associated with @cooperlees account
pypi_upload¶
This workflow builds a Python sdist and wheel using the latest setuptools and wheel modules.
It will then use twine to upload both release formats to PyPI for general downloading of the Black Python package. This is where pip looks by default.
Currently this workflow uses an API token associated with @ambv’s PyPI account
Upload self-contained binaries¶
This workflow builds self-contained binaries for multiple platforms. This allows people to download the executable for their platform and run Black without a Python Runtime installed.
The created binaries are attached/stored on the associated GitHub Release for download over IPv4 only (GitHub still does not have IPv6 access 😢).
Moving the stable tag¶
Black provides a stable tag for people who want to move along as Black developers deem the newest version reliable. Here the Black developers will move once the release has been problem free for at least ~24 hours from release. Given the large Black userbase we hear about bad bugs quickly. We do strive to continually improve our CI too.
Developer reference¶
Note
The documentation here is quite outdated and has been neglected. Many objects worthy of inclusion aren’t documented. Contributions are appreciated!
Contents are subject to change.
Black classes¶
Contents are subject to change.
BracketTracker¶
- class black.brackets.BracketTracker(depth: int = 0, bracket_match: Dict[Tuple[int, int], blib2to3.pytree.Leaf] = <factory>, delimiters: Dict[int, int] = <factory>, previous: Optional[blib2to3.pytree.Leaf] = None, _for_loop_depths: List[int] = <factory>, _lambda_argument_depths: List[int] = <factory>, invisible: List[blib2to3.pytree.Leaf] = <factory>)¶
Keeps track of brackets on a line.
- mark(leaf: blib2to3.pytree.Leaf) None¶
Mark leaf with bracket-related metadata. Keep track of delimiters.
All leaves receive an int bracket_depth field that stores how deep within brackets a given leaf is. 0 means there are no enclosing brackets that started on this line.
If a leaf is itself a closing bracket, it receives an opening_bracket field that it forms a pair with. This is a one-directional link to avoid reference cycles.
If a leaf is a delimiter (a token on which Black can split the line if needed) and it’s on depth 0, its id() is stored in the tracker’s delimiters field.
- max_delimiter_priority(exclude: Iterable[int] = ()) int¶
Return the highest priority of a delimiter found on the line.
Values are consistent with what is_split_*_delimiter() return. Raises ValueError on no delimiters.
- delimiter_count_with_priority(priority: int = 0) int¶
Return the number of delimiters with the given priority.
If no priority is passed, defaults to max priority on the line.
- maybe_increment_for_loop_variable(leaf: blib2to3.pytree.Leaf) bool¶
In a for loop, or comprehension, the variables are often unpacks.
To avoid splitting on the comma in this situation, increase the depth of tokens between for and in.
- maybe_decrement_after_for_loop_variable(leaf: blib2to3.pytree.Leaf) bool¶
See maybe_increment_for_loop_variable above for explanation.
- maybe_increment_lambda_arguments(leaf: blib2to3.pytree.Leaf) bool¶
In a lambda expression, there might be more than one argument.
To avoid splitting on the comma in this situation, increase the depth of tokens between lambda and :.
- maybe_decrement_after_lambda_arguments(leaf: blib2to3.pytree.Leaf) bool¶
See maybe_increment_lambda_arguments above for explanation.
- get_open_lsqb() Optional[blib2to3.pytree.Leaf]¶
Return the most recent opening square bracket (if any).
EmptyLineTracker¶
- class black.EmptyLineTracker(is_pyi: bool = False, previous_line: Optional[black.lines.Line] = None, previous_after: int = 0, previous_defs: List[int] = <factory>)¶
Provides a stateful method that returns the number of potential extra empty lines needed before and after the currently processed line.
Note: this tracker works on lines that haven’t been split yet. It assumes the prefix of the first leaf consists of optional newlines. Those newlines are consumed by maybe_empty_lines() and included in the computation.
- maybe_empty_lines(current_line: black.lines.Line) Tuple[int, int]¶
Return the number of extra empty lines before and after the current_line.
This is for separating def, async def and class with extra empty lines (two on module-level).
Line¶
- class black.Line(mode: black.mode.Mode, depth: int = 0, leaves: List[blib2to3.pytree.Leaf] = <factory>, comments: Dict[int, List[blib2to3.pytree.Leaf]] = <factory>, bracket_tracker: black.brackets.BracketTracker = <factory>, inside_brackets: bool = False, should_split_rhs: bool = False, magic_trailing_comma: Optional[blib2to3.pytree.Leaf] = None)¶
Holds leaves and comments. Can be printed with str(line).
- append(leaf: blib2to3.pytree.Leaf, preformatted: bool = False) None¶
Add a new leaf to the end of the line.
Unless preformatted is True, the leaf will receive a new consistent whitespace prefix and metadata applied by
BracketTracker. Trailing commas are maybe removed, unpacked for loop variables are demoted from being delimiters.Inline comments are put aside.
- append_safe(leaf: blib2to3.pytree.Leaf, preformatted: bool = False) None¶
Like
append()but disallow invalid standalone comment structure.Raises ValueError when any leaf is appended after a standalone comment or when a standalone comment is not the first leaf on the line.
- property is_comment: bool¶
Is this line a standalone comment?
- property is_decorator: bool¶
Is this line a decorator?
- property is_import: bool¶
Is this an import line?
- property is_class: bool¶
Is this line a class definition?
- property is_stub_class: bool¶
Is this line a class definition with a body consisting only of “…”?
- property is_def: bool¶
Is this a function definition? (Also returns True for async defs.)
- property is_class_paren_empty: bool¶
Is this a class with no base classes but using parentheses?
Those are unnecessary and should be removed.
- property is_triple_quoted_string: bool¶
Is the line a triple quoted string?
- contains_standalone_comments(depth_limit: int = 9223372036854775807) bool¶
If so, needs to be split before emitting.
- has_magic_trailing_comma(closing: blib2to3.pytree.Leaf, ensure_removable: bool = False) bool¶
Return True if we have a magic trailing comma, that is when: - there’s a trailing comma here - it’s not a one-tuple Additionally, if ensure_removable: - it’s not from square bracket indexing
- append_comment(comment: blib2to3.pytree.Leaf) bool¶
Add an inline or standalone comment to the line.
- comments_after(leaf: blib2to3.pytree.Leaf) List[blib2to3.pytree.Leaf]¶
Generate comments that should appear directly after leaf.
- is_complex_subscript(leaf: blib2to3.pytree.Leaf) bool¶
Return True iff leaf is part of a slice with non-trivial exprs.
LineGenerator¶
- class black.LineGenerator(mode: black.mode.Mode, remove_u_prefix: bool = False)¶
Bases:
black.nodes.Visitor[black.lines.Line]Generates reformatted Line objects. Empty lines are not emitted.
Note: destroys the tree it’s visiting by mutating prefixes of its leaves in ways that will no longer stringify to valid Python code on the tree.
- line(indent: int = 0) Iterator[black.lines.Line]¶
Generate a line.
If the line is empty, only emit if it makes sense. If the line is too long, split it first and then generate.
If any lines were generated, set up a new current_line.
- visit_default(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) Iterator[black.lines.Line]¶
Default visit_*() implementation. Recurses to children of node.
- visit_INDENT(node: blib2to3.pytree.Leaf) Iterator[black.lines.Line]¶
Increase indentation level, maybe yield a line.
- visit_DEDENT(node: blib2to3.pytree.Leaf) Iterator[black.lines.Line]¶
Decrease indentation level, maybe yield a line.
- visit_stmt(node: blib2to3.pytree.Node, keywords: Set[str], parens: Set[str]) Iterator[black.lines.Line]¶
Visit a statement.
This implementation is shared for if, while, for, try, except, def, with, class, assert and assignments.
The relevant Python language keywords for a given statement will be NAME leaves within it. This methods puts those on a separate line.
parens holds a set of string leaf values immediately after which invisible parens should be put.
- visit_suite(node: blib2to3.pytree.Node) Iterator[black.lines.Line]¶
Visit a suite.
- visit_simple_stmt(node: blib2to3.pytree.Node) Iterator[black.lines.Line]¶
Visit a statement without nested statements.
- visit_async_stmt(node: blib2to3.pytree.Node) Iterator[black.lines.Line]¶
Visit async def, async for, async with.
- visit_decorators(node: blib2to3.pytree.Node) Iterator[black.lines.Line]¶
Visit decorators.
- visit_SEMI(leaf: blib2to3.pytree.Leaf) Iterator[black.lines.Line]¶
Remove a semicolon and put the other statement on a separate line.
- visit_ENDMARKER(leaf: blib2to3.pytree.Leaf) Iterator[black.lines.Line]¶
End of file. Process outstanding comments and end with a newline.
- visit_factor(node: blib2to3.pytree.Node) Iterator[black.lines.Line]¶
Force parentheses between a unary op and a binary power:
-2 ** 8 -> -(2 ** 8)
ProtoComment¶
- class black.comments.ProtoComment(type: int, value: str, newlines: int, consumed: int)¶
Describes a piece of syntax that is a comment.
It’s not a
blib2to3.pytree.Leafso that:it can be cached (Leaf objects should not be reused more than once as they store their lineno, column, prefix, and parent information);
newlines and consumed fields are kept separate from the value. This simplifies handling of special marker comments like
# fmt: off/on.
Report¶
- class black.Report(check: bool = False, diff: bool = False, quiet: bool = False, verbose: bool = False, change_count: int = 0, same_count: int = 0, failure_count: int = 0)¶
Provides a reformatting counter. Can be rendered with str(report).
- done(src: pathlib.Path, changed: black.report.Changed) None¶
Increment the counter for successful reformatting. Write out a message.
- failed(src: pathlib.Path, message: str) None¶
Increment the counter for failed reformatting. Write out a message.
- property return_code: int¶
Return the exit code that the app should use.
This considers the current state of changed files and failures: - if there were any failures, return 123; - if any files were changed and –check is being used, return 1; - otherwise return 0.
Visitor¶
- class black.nodes.Visitor(*args, **kwds)¶
Bases:
Generic[black.nodes.T]Basic lib2to3 visitor that yields things of type T on visit().
- visit(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) Iterator[black.nodes.T]¶
Main method to visit node and its children.
It tries to find a visit_*() method for the given node.type, like visit_simple_stmt for Node objects or visit_INDENT for Leaf objects. If no dedicated visit_*() method is found, chooses visit_default() instead.
Then yields objects of type T from the selected visitor.
- visit_default(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) Iterator[black.nodes.T]¶
Default visit_*() implementation. Recurses to children of node.
Black functions¶
Contents are subject to change.
Assertions and checks¶
- black.assert_equivalent(src: str, dst: str, *, pass_num: int = 1) None¶
Raise AssertionError if src and dst aren’t equivalent.
- black.assert_stable(src: str, dst: str, mode: black.mode.Mode) None¶
Raise AssertionError if dst reformats differently the second time.
- black.lines.can_be_split(line: black.lines.Line) bool¶
Return False if the line cannot be split for sure.
This is not an exhaustive search but a cheap heuristic that we can use to avoid some unfortunate formattings (mostly around wrapping unsplittable code in unnecessary parentheses).
- black.lines.can_omit_invisible_parens(line: black.lines.Line, line_length: int, omit_on_explode: Collection[int] = ()) bool¶
Does line have a shape safe to reformat without optional parens around it?
Returns True for only a subset of potentially nice looking formattings but the point is to not return false positives that end up producing lines that are too long.
- black.nodes.is_empty_tuple(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) bool¶
Return True if node holds an empty tuple.
- black.nodes.is_import(leaf: blib2to3.pytree.Leaf) bool¶
Return True if the given leaf starts an import statement.
- black.lines.is_line_short_enough(line: black.lines.Line, *, line_length: int, line_str: str = '') bool¶
Return True if line is no longer than line_length.
Uses the provided line_str rendering, if any, otherwise computes a new one.
- black.nodes.is_multiline_string(leaf: blib2to3.pytree.Leaf) bool¶
Return True if leaf is a multiline string that actually spans many lines.
- black.nodes.is_one_tuple(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) bool¶
Return True if node holds a tuple with one element, with or without parens.
- black.brackets.is_split_after_delimiter(leaf: blib2to3.pytree.Leaf, previous: Optional[blib2to3.pytree.Leaf] = None) int¶
Return the priority of the leaf delimiter, given a line break after it.
The delimiter priorities returned here are from those delimiters that would cause a line break after themselves.
Higher numbers are higher priority.
- black.brackets.is_split_before_delimiter(leaf: blib2to3.pytree.Leaf, previous: Optional[blib2to3.pytree.Leaf] = None) int¶
Return the priority of the leaf delimiter, given a line break before it.
The delimiter priorities returned here are from those delimiters that would cause a line break before themselves.
Higher numbers are higher priority.
- black.nodes.is_stub_body(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) bool¶
Return True if node is a simple statement containing an ellipsis.
- black.nodes.is_stub_suite(node: blib2to3.pytree.Node) bool¶
Return True if node is a suite with a stub body.
- black.nodes.is_vararg(leaf: blib2to3.pytree.Leaf, within: Set[int]) bool¶
Return True if leaf is a star or double star in a vararg or kwarg.
If within includes VARARGS_PARENTS, this applies to function signatures. If within includes UNPACKING_PARENTS, it applies to right hand-side extended iterable unpacking (PEP 3132) and additional unpacking generalizations (PEP 448).
Formatting¶
- black.format_file_contents(src_contents: str, *, fast: bool, mode: black.mode.Mode) str¶
Reformat contents of a file and return new contents.
If fast is False, additionally confirm that the reformatted code is valid by calling
assert_equivalent()andassert_stable()on it. mode is passed toformat_str().
- black.format_file_in_place(src: pathlib.Path, fast: bool, mode: black.mode.Mode, write_back: black.WriteBack = WriteBack.NO, lock: Optional[Any] = None) bool¶
Format file under src path. Return True if changed.
If write_back is DIFF, write a diff to stdout. If it is YES, write reformatted code to the file. mode and fast options are passed to
format_file_contents().
- black.format_stdin_to_stdout(fast: bool, *, content: Optional[str] = None, write_back: black.WriteBack = WriteBack.NO, mode: black.mode.Mode) bool¶
Format file on stdin. Return True if changed.
If content is None, it’s read from sys.stdin.
If write_back is YES, write reformatted code back to stdout. If it is DIFF, write a diff to stdout. The mode argument is passed to
format_file_contents().
- black.format_str(src_contents: str, *, mode: black.mode.Mode) str¶
Reformat a string and return new contents.
mode determines formatting options, such as how many characters per line are allowed. Example:
>>> import black >>> print(black.format_str("def f(arg:str='')->None:...", mode=black.Mode())) def f(arg: str = "") -> None: ...
A more complex example:
>>> print( ... black.format_str( ... "def f(arg:str='')->None: hey", ... mode=black.Mode( ... target_versions={black.TargetVersion.PY36}, ... line_length=10, ... string_normalization=False, ... is_pyi=False, ... ), ... ), ... ) def f( arg: str = '', ) -> None: hey
- black.reformat_one(src: pathlib.Path, fast: bool, write_back: black.WriteBack, mode: black.mode.Mode, report: black.report.Report) None¶
Reformat a single file under src without spawning child processes.
fast, write_back, and mode options are passed to
format_file_in_place()orformat_stdin_to_stdout().
- async black.schedule_formatting(sources: Set[pathlib.Path], fast: bool, write_back: black.WriteBack, mode: black.mode.Mode, report: black.report.Report, loop: asyncio.events.AbstractEventLoop, executor: concurrent.futures._base.Executor) None¶
Run formatting of sources in parallel using the provided executor.
(Use ProcessPoolExecutors for actual parallelism.)
write_back, fast, and mode options are passed to
format_file_in_place().
File operations¶
- black.dump_to_file(*output: str, ensure_final_newline: bool = True) str¶
Dump output to a temporary file. Return path to the file.
- black.find_project_root(srcs: Sequence[str]) pathlib.Path¶
Return a directory containing .git, .hg, or pyproject.toml.
That directory will be a common parent of all files and directories passed in srcs.
If no directory in the tree contains a marker that would specify it’s the project root, the root of the file system is returned.
- black.gen_python_files(paths: Iterable[pathlib.Path], root: pathlib.Path, include: Pattern[str], exclude: Pattern[str], extend_exclude: Optional[Pattern[str]], force_exclude: Optional[Pattern[str]], report: black.report.Report, gitignore: Optional[pathspec.pathspec.PathSpec]) Iterator[pathlib.Path]¶
Generate all files under path whose paths are not excluded by the exclude_regex, extend_exclude, or force_exclude regexes, but are included by the include regex.
Symbolic links pointing outside of the root directory are ignored.
report is where output about exclusions goes.
Parsing¶
- black.decode_bytes(src: bytes) Tuple[str, str, str]¶
Return a tuple of (decoded_contents, encoding, newline).
newline is either CRLF or LF but decoded_contents is decoded with universal newlines (i.e. only contains LF).
Split functions¶
- black.linegen.bracket_split_build_line(leaves: List[blib2to3.pytree.Leaf], original: black.lines.Line, opening_bracket: blib2to3.pytree.Leaf, *, is_body: bool = False) black.lines.Line¶
Return a new line with given leaves and respective comments from original.
If is_body is True, the result line is one-indented inside brackets and as such has its first leaf’s prefix normalized and a trailing comma added when expected.
- black.linegen.bracket_split_succeeded_or_raise(head: black.lines.Line, body: black.lines.Line, tail: black.lines.Line) None¶
Raise
CannotSplitif the last left- or right-hand split failed.Do nothing otherwise.
A left- or right-hand split is based on a pair of brackets. Content before (and including) the opening bracket is left on one line, content inside the brackets is put on a separate line, and finally content starting with and following the closing bracket is put on a separate line.
Those are called head, body, and tail, respectively. If the split produced the same line (all content in head) or ended up with an empty body and the tail is just the closing bracket, then it’s considered failed.
- black.linegen.delimiter_split(line: black.lines.Line, features: Collection[black.mode.Feature] = ()) Iterator[black.lines.Line]¶
Split according to delimiters of the highest priority.
If the appropriate Features are given, the split will add trailing commas also in function signatures and calls that contain * and **.
- black.linegen.left_hand_split(line: black.lines.Line, _features: Collection[black.mode.Feature] = ()) Iterator[black.lines.Line]¶
Split line into many lines, starting with the first matching bracket pair.
Note: this usually looks weird, only use this for function definitions. Prefer RHS otherwise. This is why this function is not symmetrical with
right_hand_split()which also handles optional parentheses.
- black.linegen.right_hand_split(line: black.lines.Line, line_length: int, features: Collection[black.mode.Feature] = (), omit: Collection[int] = ()) Iterator[black.lines.Line]¶
Split line into many lines, starting with the last matching bracket pair.
If the split was by optional parentheses, attempt splitting without them, too. omit is a collection of closing bracket IDs that shouldn’t be considered for this split.
Note: running this function modifies bracket_depth on the leaves of line.
- black.linegen.standalone_comment_split(line: black.lines.Line, features: Collection[black.mode.Feature] = ()) Iterator[black.lines.Line]¶
Split standalone comments from the rest of the line.
- black.linegen.transform_line(line: black.lines.Line, mode: black.mode.Mode, features: Collection[black.mode.Feature] = ()) Iterator[black.lines.Line]¶
Transform a line, potentially splitting it into many lines.
They should fit in the allotted line_length but might not be able to.
features are syntactical features that may be used in the output.
Caching¶
- black.cache.filter_cached(cache: Dict[str, Tuple[float, int]], sources: Iterable[pathlib.Path]) Tuple[Set[pathlib.Path], Set[pathlib.Path]]¶
Split an iterable of paths in sources into two sets.
The first contains paths of files that modified on disk or are not in the cache. The other contains paths to non-modified files.
- black.cache.get_cache_file(mode: black.mode.Mode) pathlib.Path¶
- black.cache.get_cache_info(path: pathlib.Path) Tuple[float, int]¶
Return the information used to check if a file is already formatted or not.
- black.cache.read_cache(mode: black.mode.Mode) Dict[str, Tuple[float, int]]¶
Read the cache if it exists and is well formed.
If it is not well formed, the call to write_cache later should resolve the issue.
- black.cache.write_cache(cache: Dict[str, Tuple[float, int]], sources: Iterable[pathlib.Path], mode: black.mode.Mode) None¶
Update the cache file.
Utilities¶
- black.debug.DebugVisitor.show(code: str) None¶
Pretty-print the lib2to3 AST of a given string of code.
- black.concurrency.cancel(tasks: Iterable[asyncio.Task[Any]]) None¶
asyncio signal handler that cancels all tasks and reports to stderr.
- black.nodes.child_towards(ancestor: blib2to3.pytree.Node, descendant: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) Optional[Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]]¶
Return the child of ancestor that contains descendant.
- black.nodes.container_of(leaf: blib2to3.pytree.Leaf) Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]¶
Return leaf or one of its ancestors that is the topmost container of it.
By “container” we mean a node where leaf is the very first child.
- black.comments.convert_one_fmt_off_pair(node: blib2to3.pytree.Node) bool¶
Convert content of a single # fmt: off/# fmt: on into a standalone comment.
Returns True if a pair was converted.
- black.diff(a: str, b: str, a_name: str, b_name: str) str¶
Return a unified diff string between strings a and b.
- black.linegen.dont_increase_indentation(split_func: Callable[[black.lines.Line, Collection[black.mode.Feature]], Iterator[black.lines.Line]]) Callable[[black.lines.Line, Collection[black.mode.Feature]], Iterator[black.lines.Line]]¶
Normalize prefix of the first leaf in every line returned by split_func.
This is a decorator over relevant split functions.
- black.nodes.ensure_visible(leaf: blib2to3.pytree.Leaf) None¶
Make sure parentheses are visible.
They could be invisible as part of some statements (see
normalize_invisible_parens()andvisit_import_from()).
- black.lines.enumerate_reversed(sequence: Sequence[black.lines.T]) Iterator[Tuple[int, black.lines.T]]¶
Like reversed(enumerate(sequence)) if that were possible.
- black.comments.generate_comments(leaf: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) Iterator[blib2to3.pytree.Leaf]¶
Clean the prefix of the leaf and generate comments from it, if any.
Comments in lib2to3 are shoved into the whitespace prefix. This happens in pgen2/driver.py:Driver.parse_tokens(). This was a brilliant implementation move because it does away with modifying the grammar to include all the possible places in which comments can be placed.
The sad consequence for us though is that comments don’t “belong” anywhere. This is why this function generates simple parentless Leaf objects for comments. We simply don’t know what the correct parent should be.
No matter though, we can live without this. We really only need to differentiate between inline and standalone comments. The latter don’t share the line with any code.
Inline comments are emitted as regular token.COMMENT leaves. Standalone are emitted with a fake STANDALONE_COMMENT token identifier.
- black.comments.generate_ignored_nodes(leaf: blib2to3.pytree.Leaf, comment: black.comments.ProtoComment) Iterator[Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]]¶
Starting from the container of leaf, generate all leaves until # fmt: on.
If comment is skip, returns leaf only. Stops at the end of the block.
- black.comments.is_fmt_on(container: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) bool¶
Determine whether formatting is switched on within a container. Determined by whether the last # fmt: comment is on or off.
- black.comments.contains_fmt_on_at_column(container: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node], column: int) bool¶
Determine if children at a given column have formatting switched on.
- black.nodes.first_leaf_column(node: blib2to3.pytree.Node) Optional[int]¶
Returns the column of the first leaf child of a node.
- black.linegen.generate_trailers_to_omit(line: black.lines.Line, line_length: int) Iterator[Set[int]]¶
Generate sets of closing bracket IDs that should be omitted in a RHS.
Brackets can be omitted if the entire trailer up to and including a preceding closing bracket fits in one line.
Yielded sets are cumulative (contain results of previous yields, too). First set is empty, unless the line should explode, in which case bracket pairs until the one that needs to explode are omitted.
- black.get_future_imports(node: blib2to3.pytree.Node) Set[str]¶
Return a set of __future__ imports in the file.
- black.comments.list_comments(prefix: str, *, is_endmarker: bool) List[black.comments.ProtoComment]¶
Return a list of
ProtoCommentobjects parsed from the given prefix.
- black.comments.make_comment(content: str) str¶
Return a consistently formatted comment from the given content string.
All comments (except for “##”, “#!”, “#:”, ‘#’”, “#%%”) should have a single space between the hash sign and the content.
If content didn’t start with a hash sign, one is provided.
- black.linegen.maybe_make_parens_invisible_in_atom(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node], parent: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) bool¶
If it’s safe, make the parens in the atom node invisible, recursively. Additionally, remove repeated, adjacent invisible parens from the atom node as they are redundant.
Returns whether the node should itself be wrapped in invisible parentheses.
- black.brackets.max_delimiter_priority_in_atom(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) int¶
Return maximum delimiter priority inside node.
This is specific to atoms with contents contained in a pair of parentheses. If node isn’t an atom or there are no enclosing parentheses, returns 0.
- black.normalize_fmt_off(node: blib2to3.pytree.Node) None¶
Convert content between # fmt: off/# fmt: on into standalone comments.
- black.numerics.normalize_numeric_literal(leaf: blib2to3.pytree.Leaf) None¶
Normalizes numeric (float, int, and complex) literals.
All letters used in the representation are normalized to lowercase (except in Python 2 long literals).
- black.linegen.normalize_prefix(leaf: blib2to3.pytree.Leaf, *, inside_brackets: bool) None¶
Leave existing extra newlines if not inside_brackets. Remove everything else.
Note: don’t use backslashes for formatting or you’ll lose your voting rights.
- black.strings.normalize_string_prefix(s: str, remove_u_prefix: bool = False) str¶
Make all string prefixes lowercase.
If remove_u_prefix is given, also removes any u prefix from the string.
- black.strings.normalize_string_quotes(s: str) str¶
Prefer double quotes but only if it doesn’t cause more escaping.
Adds or removes backslashes as appropriate. Doesn’t parse and fix strings nested in f-strings.
- black.linegen.normalize_invisible_parens(node: blib2to3.pytree.Node, parens_after: Set[str]) None¶
Make existing optional parentheses invisible or create new ones.
parens_after is a set of string leaf values immediately after which parens should be put.
Standardizes on visible parentheses for single-element tuples, and keeps existing visible parentheses for other tuples and generator expressions.
- black.patch_click() None¶
Make Click not crash on Python 3.6 with LANG=C.
On certain misconfigured environments, Python 3 selects the ASCII encoding as the default which restricts paths that it can access during the lifetime of the application. Click refuses to work in this scenario by raising a RuntimeError.
In case of Black the likelihood that non-ASCII characters are going to be used in file paths is minimal since it’s Python source code. Moreover, this crash was spurious on Python 3.7 thanks to PEP 538 and PEP 540.
- black.nodes.preceding_leaf(node: Optional[Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]]) Optional[blib2to3.pytree.Leaf]¶
Return the first leaf that precedes node, if any.
- black.re_compile_maybe_verbose(regex: str) Pattern[str]¶
Compile a regular expression string in regex.
If it contains newlines, use verbose mode.
- black.linegen.should_split_line(line: black.lines.Line, opening_bracket: blib2to3.pytree.Leaf) bool¶
Should line be immediately split with delimiter_split() after RHS?
- black.shutdown(loop: asyncio.events.AbstractEventLoop) None¶
Cancel all pending tasks on loop, wait for them, and close the loop.
Black exceptions¶
Contents are subject to change.
- exception black.linegen.CannotSplit¶
A readable split that fits the allotted line length is impossible.
- exception black.NothingChanged¶
Raised when reformatted code is the same as source.
- exception black.InvalidInput¶
Raised when input source code fails all parse attempts.
Welcome! Happy to see you willing to make the project better. Have you read the entire user documentation yet?
Bird’s eye view
In terms of inspiration, Black is about as configurable as gofmt. This is deliberate.
Bug reports and fixes are always welcome! Please follow the issue template on GitHub for best results.
Before you suggest a new feature or configuration knob, ask yourself why you want it. If it enables better integration with some workflow, fixes an inconsistency, speeds things up, and so on - go for it! On the other hand, if your answer is “because I don’t like a particular formatting” then you’re not ready to embrace Black yet. Such changes are unlikely to get accepted. You can still try but prepare to be disappointed.
Contents
This section covers the following topics:
For an overview on contributing to the Black, please checkout The basics.
If you need a reference of the functions, classes, etc. available to you while developing Black, there’s the Developer reference docs.
Change Log¶
Unreleased¶
Moved from
appdirsdependency toplatformdirs(#2375)
21.7b0¶
Black¶
Configuration files using TOML features higher than spec v0.5.0 are now supported (#2301)
Add primer support and test for code piped into black via STDIN (#2315)
Fix internal error when
FORCE_OPTIONAL_PARENTHESESfeature is enabled (#2332)Accept empty stdin (#2346)
Provide a more useful error when parsing fails during AST safety checks (#2304)
Docker¶
Add new
latest_releasetag automation to follow latest black release on docker images (#2374)
Integrations¶
The vim plugin now searches upwards from the directory containing the current buffer instead of the current working directory for pyproject.toml. (#1871)
The vim plugin now reads the correct string normalization option in pyproject.toml (#1869)
The vim plugin no longer crashes Black when there’s boolean values in pyproject.toml (#1869)
21.6b0¶
Black¶
Fix failure caused by
fmt: skipand indentation (#2281)Account for += assignment when deciding whether to split string (#2312)
Correct max string length calculation when there are string operators (#2292)
Fixed option usage when using the
--codeflag (#2259)Do not call
uvloop.install()when Black is used as a library (#2303)Added
--required-versionoption to require a specific version to be running (#2300)Fix incorrect custom breakpoint indices when string group contains fake f-strings (#2311)
Fix regression where
Rprefixes would be lowercased for docstrings (#2285)Fix handling of named escapes (
\N{...}) when--experimental-string-processingis used (#2319)
Integrations¶
The official Black action now supports choosing what version to use, and supports the major 3 OSes. (#1940)
21.5b2¶
Black¶
A space is no longer inserted into empty docstrings (#2249)
Fix handling of .gitignore files containing non-ASCII characters on Windows (#2229)
Respect
.gitignorefiles in all levels, not onlyroot/.gitignorefile (apply.gitignorerules likegitdoes) (#2225)Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
Add extra uvloop install + import support if in python env (#2258)
Fix –experimental-string-processing crash when matching parens are not found (#2283)
Make sure to split lines that start with a string operator (#2286)
Fix regular expression that black uses to identify f-expressions (#2287)
Blackd¶
Add a lower bound for the
aiohttp-corsdependency. Only 0.4.0 or higher is supported. (#2231)
Packaging¶
Release self-contained x86_64 MacOS binaries as part of the GitHub release pipeline (#2198)
Always build binaries with the latest available Python (#2260)
Documentation¶
Add discussion of magic comments to FAQ page (#2272)
--experimental-string-processingwill be enabled by default in the future (#2273)Fix typos discovered by codespell (#2228)
Fix Vim plugin installation instructions. (#2235)
Add new Frequently Asked Questions page (#2247)
Fix encoding + symlink issues preventing proper build on Windows (#2262)
21.5b1¶
Black¶
Refactor
src/black/__init__.pyinto many files (#2206)
Documentation¶
Replaced all remaining references to the
masterbranch with themainbranch. Some additional changes in the source code were also made. (#2210)Sigificantly reorganized the documentation to make much more sense. Check them out by heading over to the stable docs on RTD. (#2174)
21.5b0¶
Black¶
Set
--pyimode if--stdin-filenameends in.pyi(#2169)Stop detecting target version as Python 3.9+ with pre-PEP-614 decorators that are being called but with no arguments (#2182)
Black-Primer¶
Add
--no-diffto black-primer to suppress formatting changes (#2187)
21.4b2¶
Black¶
Fix crash if the user configuration directory is inaccessible. (#2158)
Clarify circumstances in which Black may change the AST (#2159)
Allow
.gitignorerules to be overridden by specifyingexcludeinpyproject.tomlor on the command line. (#2170)
Packaging¶
Install
primer.json(used byblack-primerby default) with black. (#2154)
21.4b1¶
Black¶
Fix crash on docstrings ending with “\ “. (#2142)
Fix crash when atypical whitespace is cleaned out of dostrings (#2120)
Reflect the
--skip-magic-trailing-commaand--experimental-string-processingflags in the name of the cache file. Without this fix, changes in these flags would not take effect if the cache had already been populated. (#2131)Don’t remove necessary parentheses from assignment expression containing assert / return statements. (#2143)
Packaging¶
Bump pathspec to >= 0.8.1 to solve invalid .gitignore exclusion handling
21.4b0¶
Black¶
Fixed a rare but annoying formatting instability created by the combination of optional trailing commas inserted by
Blackand optional parentheses looking at pre-existing “magic” trailing commas. This fixes issue #1629 and all of its many many duplicates. (#2126)Blacknow processes one-line docstrings by stripping leading and trailing spaces, and adding a padding space when needed to break up “”””. (#1740)Blacknow cleans up leading non-breaking spaces in comments (#2092)Blacknow respects--skip-string-normalizationwhen normalizing multiline docstring quotes (#1637)Blackno longer removes all empty lines between non-function code and decorators when formatting typing stubs. NowBlackenforces a single empty line. (#1646)Blackno longer adds an incorrect space after a parenthesized assignment expression in if/while statements (#1655)Added
--skip-magic-trailing-comma/-Cto avoid using trailing commas as a reason to split lines (#1824)fixed a crash when PWD=/ on POSIX (#1631)
fixed “I/O operation on closed file” when using –diff (#1664)
Prevent coloured diff output being interleaved with multiple files (#1673)
Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
Added parsing support for unparenthesized tuples and yield expressions in annotated assignments (#1835)
added
--extend-excludeargument (PR #2005)speed up caching by avoiding pathlib (#1950)
--diffcorrectly indicates when a file doesn’t end in a newline (#1662)Added
--stdin-filenameargument to allow stdin to respect--force-excluderules (#1780)Lines ending with
fmt: skipwill now be not formatted (#1800)PR #2053: Black no longer relies on typed-ast for Python 3.8 and higher
PR #2053: Python 2 support is now optional, install with
python3 -m pip install black[python2]to maintain support.Exclude
venvdirectory by default (#1683)Fixed “Black produced code that is not equivalent to the source” when formatting Python 2 docstrings (#2037)
Packaging¶
Self-contained native Black binaries are now provided for releases via GitHub Releases (#1743)
20.8b1¶
Packaging¶
explicitly depend on Click 7.1.2 or newer as
Blackno longer works with versions older than 7.0
20.8b0¶
Black¶
re-implemented support for explicit trailing commas: now it works consistently within any bracket pair, including nested structures (#1288 and duplicates)
Blacknow reindents docstrings when reindenting code around it (#1053)Blacknow shows colored diffs (#1266)Blackis now packaged using ‘py3’ tagged wheels (#1388)Blacknow supports Python 3.8 code, e.g. star expressions in return statements (#1121)Blackno longer normalizes capital R-string prefixes as those have a community-accepted meaning (#1244)Blacknow uses exit code 2 when specified configuration file doesn’t exit (#1361)Blacknow works on AWS Lambda (#1141)added
--force-excludeargument (#1032)removed deprecated
--py36option (#1236)fixed
--diffoutput when EOF is encountered (#526)fixed
# fmt: offhandling around decorators (#560)fixed unstable formatting with some
# type: ignorecomments (#1113)fixed invalid removal on organizing brackets followed by indexing (#1575)
introduced
black-primer, a CI tool that allows us to run regression tests against existing open source users of Black (#1402)introduced property-based fuzzing to our test suite based on Hypothesis and Hypothersmith (#1566)
implemented experimental and disabled by default long string rewrapping (#1132), hidden under a
--experimental-string-processingflag while it’s being worked on; this is an undocumented and unsupported feature, you lose Internet points for depending on it (#1609)
Vim plugin¶
prefer virtualenv packages over global packages (#1383)
19.10b0¶
added support for PEP 572 assignment expressions (#711)
added support for PEP 570 positional-only arguments (#943)
added support for async generators (#593)
added support for pre-splitting collections by putting an explicit trailing comma inside (#826)
added
black -cas a way to format code passed from the command line (#761)–safe now works with Python 2 code (#840)
fixed grammar selection for Python 2-specific code (#765)
fixed feature detection for trailing commas in function definitions and call sites (#763)
# fmt: off/# fmt: oncomment pairs placed multiple times within the same block of code now behave correctly (#1005)Black no longer crashes on Windows machines with more than 61 cores (#838)
Black no longer crashes on standalone comments prepended with a backslash (#767)
Black no longer crashes on
from…importblocks with comments (#829)Black no longer crashes on Python 3.7 on some platform configurations (#494)
Black no longer fails on comments in from-imports (#671)
Black no longer fails when the file starts with a backslash (#922)
Black no longer merges regular comments with type comments (#1027)
Black no longer splits long lines that contain type comments (#997)
removed unnecessary parentheses around
yieldexpressions (#834)added parentheses around long tuples in unpacking assignments (#832)
added parentheses around complex powers when they are prefixed by a unary operator (#646)
fixed bug that led Black format some code with a line length target of 1 (#762)
Black no longer introduces quotes in f-string subexpressions on string boundaries (#863)
if Black puts parenthesis around a single expression, it moves comments to the wrapped expression instead of after the brackets (#872)
blackdnow returns the version of Black in the response headers (#1013)blackdcan now output the diff of formats on source code when theX-Diffheader is provided (#969)
19.3b0¶
new option
--target-versionto control which Python versions Black-formatted code should target (#618)deprecated
--py36(use--target-version=py36instead) (#724)Black no longer normalizes numeric literals to include
_separators (#696)long
delstatements are now split into multiple lines (#698)type comments are no longer mangled in function signatures
improved performance of formatting deeply nested data structures (#509)
Black now properly formats multiple files in parallel on Windows (#632)
Black now creates cache files atomically which allows it to be used in parallel pipelines (like
xargs -P8) (#673)Black now correctly indents comments in files that were previously formatted with tabs (#262)
blackdnow supports CORS (#622)
18.9b0¶
numeric literals are now formatted by Black (#452, #461, #464, #469):
numeric literals are normalized to include
_separators on Python 3.6+ codeadded
--skip-numeric-underscore-normalizationto disable the above behavior and leave numeric underscores as they were in the inputcode with
_in numeric literals is recognized as Python 3.6+most letters in numeric literals are lowercased (e.g., in
1e10,0x01)hexadecimal digits are always uppercased (e.g.
0xBADC0DE)
added
blackd, see its documentation for more info (#349)adjacent string literals are now correctly split into multiple lines (#463)
trailing comma is now added to single imports that don’t fit on a line (#250)
cache is now populated when
--checkis successful for a file which speeds up consecutive checks of properly formatted unmodified files (#448)whitespace at the beginning of the file is now removed (#399)
fixed mangling pweave and Spyder IDE special comments (#532)
fixed unstable formatting when unpacking big tuples (#267)
fixed parsing of
__future__imports with renames (#389)fixed scope of
# fmt: offwhen directly precedingyieldand other nodes (#385)fixed formatting of lambda expressions with default arguments (#468)
fixed
async forstatements: Black no longer breaks them into separate lines (#372)note: the Vim plugin stopped registering
,=as a default chord as it turned out to be a bad idea (#415)
18.6b4¶
hotfix: don’t freeze when multiple comments directly precede
# fmt: off(#371)
18.6b3¶
typing stub files (
.pyi) now have blank lines added after constants (#340)# fmt: offand# fmt: onare now much more dependable:they now work also within bracket pairs (#329)
they now correctly work across function/class boundaries (#335)
they now work when an indentation block starts with empty lines or misaligned comments (#334)
made Click not fail on invalid environments; note that Click is right but the likelihood we’ll need to access non-ASCII file paths when dealing with Python source code is low (#277)
fixed improper formatting of f-strings with quotes inside interpolated expressions (#322)
fixed unnecessary slowdown when long list literals where found in a file
fixed unnecessary slowdown on AST nodes with very many siblings
fixed cannibalizing backslashes during string normalization
fixed a crash due to symbolic links pointing outside of the project directory (#338)
18.6b2¶
added
--config(#65)added
-hequivalent to--help(#316)fixed improper unmodified file caching when
-Swas usedfixed extra space in string unpacking (#305)
fixed formatting of empty triple quoted strings (#313)
fixed unnecessary slowdown in comment placement calculation on lines without comments
18.6b1¶
hotfix: don’t output human-facing information on stdout (#299)
hotfix: don’t output cake emoji on non-zero return code (#300)
18.6b0¶
added
--includeand--exclude(#270)added
--skip-string-normalization(#118)added
--verbose(#283)the header output in
--diffnow actually conforms to the unified diff specfixed long trivial assignments being wrapped in unnecessary parentheses (#273)
fixed unnecessary parentheses when a line contained multiline strings (#232)
fixed stdin handling not working correctly if an old version of Click was used (#276)
Black now preserves line endings when formatting a file in place (#258)
18.5b1¶
added
--pyi(#249)added
--py36(#249)Python grammar pickle caches are stored with the formatting caches, making Black work in environments where site-packages is not user-writable (#192)
Black now enforces a PEP 257 empty line after a class-level docstring (and/or fields) and the first method
fixed invalid code produced when standalone comments were present in a trailer that was omitted from line splitting on a large expression (#237)
fixed optional parentheses being removed within
# fmt: offsections (#224)fixed invalid code produced when stars in very long imports were incorrectly wrapped in optional parentheses (#234)
fixed unstable formatting when inline comments were moved around in a trailer that was omitted from line splitting on a large expression (#238)
fixed extra empty line between a class declaration and the first method if no class docstring or fields are present (#219)
fixed extra empty line between a function signature and an inner function or inner class (#196)
18.5b0¶
call chains are now formatted according to the fluent interfaces style (#67)
data structure literals (tuples, lists, dictionaries, and sets) are now also always exploded like imports when they don’t fit in a single line (#152)
slices are now formatted according to PEP 8 (#178)
parentheses are now also managed automatically on the right-hand side of assignments and return statements (#140)
math operators now use their respective priorities for delimiting multiline expressions (#148)
optional parentheses are now omitted on expressions that start or end with a bracket and only contain a single operator (#177)
empty parentheses in a class definition are now removed (#145, #180)
string prefixes are now standardized to lowercase and
uis removed on Python 3.6+ only code and Python 2.7+ code with theunicode_literalsfuture import (#188, #198, #199)typing stub files (
.pyi) are now formatted in a style that is consistent with PEP 484 (#207, #210)progress when reformatting many files is now reported incrementally
fixed trailers (content with brackets) being unnecessarily exploded into their own lines after a dedented closing bracket (#119)
fixed an invalid trailing comma sometimes left in imports (#185)
fixed non-deterministic formatting when multiple pairs of removable parentheses were used (#183)
fixed multiline strings being unnecessarily wrapped in optional parentheses in long assignments (#215)
fixed not splitting long from-imports with only a single name
fixed Python 3.6+ file discovery by also looking at function calls with unpacking. This fixed non-deterministic formatting if trailing commas where used both in function signatures with stars and function calls with stars but the former would be reformatted to a single line.
fixed crash on dealing with optional parentheses (#193)
fixed “is”, “is not”, “in”, and “not in” not considered operators for splitting purposes
fixed crash when dead symlinks where encountered
18.4a4¶
don’t populate the cache on
--check(#175)
18.4a3¶
added a “cache”; files already reformatted that haven’t changed on disk won’t be reformatted again (#109)
--checkand--diffare no longer mutually exclusive (#149)generalized star expression handling, including double stars; this fixes multiplication making expressions “unsafe” for trailing commas (#132)
Black no longer enforces putting empty lines behind control flow statements (#90)
Black now splits imports like “Mode 3 + trailing comma” of isort (#127)
fixed comment indentation when a standalone comment closes a block (#16, #32)
fixed standalone comments receiving extra empty lines if immediately preceding a class, def, or decorator (#56, #154)
fixed
--diffnot showing entire path (#130)fixed parsing of complex expressions after star and double stars in function calls (#2)
fixed invalid splitting on comma in lambda arguments (#133)
fixed missing splits of ternary expressions (#141)
18.4a2¶
fixed parsing of unaligned standalone comments (#99, #112)
fixed placement of dictionary unpacking inside dictionary literals (#111)
Vim plugin now works on Windows, too
fixed unstable formatting when encountering unnecessarily escaped quotes in a string (#120)
18.4a1¶
added
--quiet(#78)added automatic parentheses management (#4)
added pre-commit integration (#103, #104)
fixed reporting on
--checkwith multiple files (#101, #102)fixed removing backslash escapes from raw strings (#100, #105)
18.4a0¶
added
--diff(#87)add line breaks before all delimiters, except in cases like commas, to better comply with PEP 8 (#73)
standardize string literals to use double quotes (almost) everywhere (#75)
fixed handling of standalone comments within nested bracketed expressions; Black will no longer produce super long lines or put all standalone comments at the end of the expression (#22)
fixed 18.3a4 regression: don’t crash and burn on empty lines with trailing whitespace (#80)
fixed 18.3a4 regression:
# yapf: disableusage as trailing comment would cause Black to not emit the rest of the file (#95)when CTRL+C is pressed while formatting many files, Black no longer freaks out with a flurry of asyncio-related exceptions
only allow up to two empty lines on module level and only single empty lines within functions (#74)
18.3a4¶
# fmt: offand# fmt: onare implemented (#5)automatic detection of deprecated Python 2 forms of print statements and exec statements in the formatted file (#49)
use proper spaces for complex expressions in default values of typed function arguments (#60)
only return exit code 1 when –check is used (#50)
don’t remove single trailing commas from square bracket indexing (#59)
don’t omit whitespace if the previous factor leaf wasn’t a math operator (#55)
omit extra space in kwarg unpacking if it’s the first argument (#46)
omit extra space in Sphinx auto-attribute comments (#68)
18.3a3¶
don’t remove single empty lines outside of bracketed expressions (#19)
added ability to pipe formatting from stdin to stdin (#25)
restored ability to format code with legacy usage of
asyncas a name (#20, #42)even better handling of numpy-style array indexing (#33, again)
18.3a2¶
changed positioning of binary operators to occur at beginning of lines instead of at the end, following a recent change to PEP 8 (#21)
ignore empty bracket pairs while splitting. This avoids very weirdly looking formattings (#34, #35)
remove a trailing comma if there is a single argument to a call
if top level functions were separated by a comment, don’t put four empty lines after the upper function
fixed unstable formatting of newlines with imports
fixed unintentional folding of post scriptum standalone comments into last statement if it was a simple statement (#18, #28)
fixed missing space in numpy-style array indexing (#33)
fixed spurious space after star-based unary expressions (#31)
18.3a1¶
added
--checkonly put trailing commas in function signatures and calls if it’s safe to do so. If the file is Python 3.6+ it’s always safe, otherwise only safe if there are no
*argsor**kwargsused in the signature or call. (#8)fixed invalid spacing of dots in relative imports (#6, #13)
fixed invalid splitting after comma on unpacked variables in for-loops (#23)
fixed spurious space in parenthesized set expressions (#7)
fixed spurious space after opening parentheses and in default arguments (#14, #17)
fixed spurious space after unary operators when the operand was a complex expression (#15)
18.3a0¶
first published version, Happy 🍰 Day 2018!
alpha quality
date-versioned (see: https://calver.org/)
Authors¶
Glued together by Łukasz Langa.
Maintained with Carol Willing, Carl Meyer, Jelle Zijlstra, Mika Naylor, Zsolt Dollenstein, Cooper Lees, and Richard Si.
Multiple contributions by:
Anders-Petter Ljungquist
Batuhan Taşkaya
Charles Reid
Codey Oxley
Daniele Esposti
dylanjblack
Francisco
Gustavo Camargo
hauntsaninja
Hugo van Kemenade
Jim Brännlund
Katrin Leinweber
Lawrence Chan
Mahmoud Hossam
Mariatta
Max Smolens
MomIsBestFriend
pmacosta
Russell Davis
Sergi
Shantanu
springstan
Toby Fleming
utsav-dbx
vezeli
Yazdan