The uncompromising code formatter

“Any color you like.”

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.

Note

Black is licensed under the MIT license.

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:

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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.

The rest of this document describes the current formatting style. If you’re interested in trying out where the style is heading, see future style and try running black --preview.

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. Prefix characters are made lowercase with the exception of capital “R” prefixes, unicode literal markers (u) are removed because they are meaningless in Python 3, and in the case of multiple characters “r” is put first as in spoken language: “raw f-string”.

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.

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.

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 ... over pass;

• 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, use Optional[] explicitly;

• use float instead of Union[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:

1. 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.

2. Black manages optional parentheses for some statements. In the case of the del statement, presence of wrapping parentheses or lack of thereof changes the resulting AST but is semantically equivalent in the interpreter.

3. 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.

Preview style

Experimental, potentially disruptive style changes are gathered under the --preview CLI flag. At the end of each year, these changes may be adopted into the default style, as described in The Black Code Style. Because the functionality is experimental, feedback and issue reports are highly encouraged!

Improved string processing

Black will split long string literals and merge short ones. Parentheses are used where appropriate. 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. The stability and status of this feature is tracked in this issue.

Black is a PEP 8 compliant opinionated formatter with its own style.

While keeping the style unchanged throughout releases has always been a goal, the Black code style isn’t set in stone. It evolves to accommodate for new features in the Python language and, occasionally, in response to user feedback.

Stability Policy

The following policy applies for the Black code style, in non pre-release versions of Black:

• The same code, formatted with the same options, will produce the same output for all releases in a given calendar year.

  This means projects can safely use black ~= 22.0 without worrying about major formatting changes disrupting their project in 2022. We may still fix bugs where Black crashes on some code, and make other improvements that do not affect formatting.

• The first release in a new calendar year may contain formatting changes, although these will be minimised as much as possible. This is to allow for improved formatting enabled by newer Python language syntax as well as due to improvements in the formatting logic.

• The --preview flag is exempt from this policy. There are no guarantees around the stability of the output with that flag passed into Black. This flag is intended for allowing experimentation with the proposed changes to the Black code style.

Documentation for both the current and future styles can be found:

• The Black code style

• The (future of the) Black code style

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. If you want to format Jupyter Notebooks, install with pip install black[jupyter].

If you can’t wait for the latest hotness and want to install from GitHub, use:

pip install git+https://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 --check was 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

The CLI options of Black can be displayed by expanding the view below or by running black --help. While Black has quite a few knobs these days, it is still opinionated so style options are deliberately limited and rarely added.

CLI reference

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 [py33|py34|py35|py36|py37|py38|py39|py310]
                                  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).
  --ipynb                         Format all input files like Jupyter
                                  Notebooks regardless of file extension
                                  (useful when piping source on standard
                                  input).
  --python-cell-magics TEXT       When processing Jupyter Notebooks, add the
                                  given magic to the list of known python-
                                  magics (timeit, prun, python3, time,
                                  capture, python, pypy). Useful for
                                  formatting cells with custom python magics.
  -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.
  --preview                       Enable potentially disruptive style changes
                                  that will be added to Black's main
                                  functionality in the next major release.
  --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.
  -W, --workers INTEGER RANGE     Number of parallel workers  [default: 2;
                                  x>=1]
  -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

Standard Input

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.

As a string

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.

Exit code

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

Diffs

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.12b0

An option to require a specific version to be running is also provided.

$ black --required-version 21.9b0 -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: ~\.black

• Unix-like (Linux, MacOS, etc.): $XDG_CONFIG_HOME/black (~/.config/black if the XDG_CONFIG_HOME environment 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>.pickle

• macOS: /Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickle

• Linux: /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-length command line flag.

• X-Skip-String-Normalization: corresponds to the --skip-string-normalization command 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-comma command 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 to fast, blackd will act as Black does when passed the --fast command line flag.

• X-Python-Variant: if set to pyi, blackd will act as Black does when passed the --pyi command line flag. Otherwise, its value must correspond to a Python version or a set of comma-separated Python versions, optionally prefixed with py. For example, to request code that is compatible with Python 3.5 and 3.6, set the header to py3.5,py3.6.

• X-Diff: corresponds to the --diff command 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 the Content-Type header 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.

Black Docker image

Official Black Docker images are available on Docker Hub: https://hub.docker.com/r/pyfound/black

Black images with the following tags are available:

• release numbers, e.g. 21.5b2, 21.6b0, 21.7b0 etc.
  ℹ Recommended for users who want to use a particular version of Black.

• latest_release - tag created when a new version of Black is released.
  ℹ Recommended for users who want to use released versions of Black. It maps to the latest release of Black.

• latest - tag used for the newest image of Black.
  ℹ Recommended for users who always want to use the latest version of Black, even before it is released.

There is one more tag used for Black Docker images - latest_non_release. It is created for all unreleased commits on the main branch. This tag is not meant to be used by external users.

Usage

A permanent container doesn’t have to be created to use Black as a Docker image. It’s enough to run Black commands for the chosen image denoted as :tag. In the below examples, the latest_release tag is used. If :tag is omitted, the latest tag will be used.

More about Black usage can be found in Usage and Configuration: The basics.

Check Black version

$ docker run --rm pyfound/black:latest_release black --version

Check code

$ docker run --rm --volume $(pwd):/src --workdir /src pyfound/black:latest_release black --check .

Remark: besides regular Black exit codes returned by --check option, Docker exit codes should also be considered.

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:

• The basics

• File collection and discovery

• Black as a server (blackd)

• Black Docker image

Integrations

Editor integration

Emacs

Options include the following:

• wbolster/emacs-python-black

• proofit404/blacken

• Elpy.

PyCharm/IntelliJ IDEA

1. Install black.

   $ pip install black
   

2. Locate your black installation 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 black is $PyInterpreterDirectory$/black.

3. Open External tools in PyCharm/IntelliJ IDEA

   On macOS:

   PyCharm -> Preferences -> Tools -> External Tools

   On Windows / Linux / BSD:

   File -> Settings -> Tools -> External Tools

4. Click 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$"

5. 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.

6. Optionally, run Black on every file save:

   1. Make sure you have the File Watchers plugin installed.

   2. Go to Preferences or Settings -> Tools -> File Watchers and 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 IDE supports black via Preference Settings for system wide settings and Project Properties for per-project or workspace specific settings, as explained in the Wing documentation on Auto-Reformatting. The detailed procedure is:

Prerequistes

• Wing IDE version 8.0+

• Install black.

  $ pip install black
  

• Make sure it runs from the command line, e.g.

  $ black --help
  

Preference Settings

If you want Wing IDE to always reformat with black for every project, follow these steps:

1. In menubar navigate to Edit -> Preferences -> Editor -> Reformatting.

2. Set Auto-Reformat from disable (default) to Line after edit or Whole files before save.

3. Set Reformatter from PEP8 (default) to Black.

Project Properties

If you want to just reformat for a specific project and not intervene with Wing IDE global setting, follow these steps:

1. In menubar navigate to Project -> Project Properties -> Options.

2. Set Auto-Reformat from Use Preferences setting (default) to Line after edit or Whole files before save.

3. Set Reformatter from Use Preferences setting (default) to Black.

Vim

Official plugin

Commands and shortcuts:

• :Black to format the entire file (ranges not supported);

  • you can optionally pass target_version=<version> with the same values as in the command line.

• :BlackUpgrade to upgrade Black inside the virtualenv;

• :BlackVersion to get the current version of Black inside the virtualenv.

Configuration:

• g:black_fast (defaults to 0)

• g:black_linelength (defaults to 88)

• g:black_skip_string_normalization (defaults to 0)

• g:black_virtualenv (defaults to ~/.vim/black or ~/.local/share/nvim/black)

• g:black_quiet (defaults to 0)

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 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 package that causes problems is:

• typed-ast

Now remove those two packages:

$ pip uninstall typed-ast -y

And now you can install them with:

$ pip install --no-binary :all: 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 typed-ast

With ALE

1. Install ale

2. Install black

3. Add this to your vimrc:

   let g:ale_fixers = {}
   let g:ale_fixers.python = ['black']
   

Gedit

gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit as

$ gedit <file_name>

1. Go to edit > preferences > plugins

2. Search for external tools and activate it.

3. In Tools menu -> Manage external tools

4. Add a new tool using + button.

5. 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-B

• Save: Nothing

• Input: Nothing

• Output: Display in bottom pane if 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.

Python LSP Server

If your editor supports the Language Server Protocol (Atom, Sublime Text, Visual Studio Code and many more), you can use the Python LSP Server with the python-lsp-black plugin.

Atom/Nuclide

Use python-black or formatters-python.

Gradle (the build tool)

Use the Spotless plugin.

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

Use Thonny-black-code-format.

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 the colorama extra so the --color flag should work fine.

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: 21.12b0
    hooks:
      - id: black
        # It is recommended to specify the latest version of Python
        # supported by your project here, or alternatively use
        # pre-commit's default_language_version, see
        # https://pre-commit.com/#top_level-default_language_version
        language_version: python3.9

Feel free to switch out the rev value to something else, like another tag/version or even a specific commit. Although we discourage the use of branches or other mutable refs since the hook won’t auto update as you may expect.

If you want support for Jupyter Notebooks as well, then replace id: black with id: black-jupyter (though note that it’s only available from version 21.8b0 onwards).

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:

• Editor / IDE

• GitHub Actions

• Source version control

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.

Profile

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"

Custom Configuration

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

Why those options above?

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.

Formats

.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.

Configuration

max-line-length = 88
extend-ignore = E203

Why those options above?

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.

Formats

.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.

Configuration

disable = C0330, C0326
max-line-length = 88

Why those options above?

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.

Formats

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:

• Introducing Black to your project

• Using Black with other tools

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.

Starting in 2022, the formatting output will be stable for the releases made in the same year (other than unintentional bugs). It is possible to opt-in to the latest formatting styles, using the --preview flag.

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 is my Jupyter Notebook cell not formatted?

Black is timid about formatting Jupyter Notebooks. Cells containing any of the following will not be formatted:

• automagics (e.g. pip install black)

• non-Python cell magics (e.g. %%writeline)

• multiline magics, e.g.:

  %timeit f(1, \
          2, \
          3)
  

• code which IPython’s TransformerManager would transform magics into, e.g.:

  get_ipython().system('ls')
  

• invalid syntax, as it can’t be safely distinguished from automagics in the absence of a running IPython kernel.

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?

Support for formatting Python 2 code was removed in version 22.0.

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.

Can I run Black with PyPy?

Yes, there is support for PyPy 3.7 and higher.

Why does Black not detect syntax errors in my code?

Black is an autoformatter, not a Python linter or interpreter. Detecting all syntax errors is not a goal. It can format all code accepted by CPython (if you find an example where that doesn’t hold, please report a bug!), but it may also format some code that CPython doesn’t accept.

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 development dependencies inside a virtual environment of your choice, for example:

$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv)$ pip install -r test_requirements.txt
(.venv)$ pip install -e .[d]
(.venv)$ pre-commit install

Before submitting pull requests, run lints and tests with the following commands from the root of the black repo:

# Linting
(.venv)$ pre-commit run -a

# Unit tests
(.venv)$ tox -e py

# Optional Fuzz testing
(.venv)$ tox -e fuzz

# Optional CI run to test your changes on many popular python projects
(.venv)$ 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. If the change is implemented with the --preview flag, please include the change in the future style document instead and write the changelog entry under a dedicated “Preview changes” heading.

Docs Testing

If you make changes to docs, you can test they still build locally too.

(.venv)$ pip install -r docs/requirements.txt
(.venv)$ pip install [-e] .[d]
(.venv)$ 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 + git in PATH

• Load projects from primer.json

• Run projects in parallel with --worker workers (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-dir so 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-
                         furo/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]
  --projects TEXT        Comma separated list of projects to run  [default: ST
                         DIN,aioexabgp,attrs,bandersnatch,channels,cpython,dja
                         ngo,flake8-bugbear,hypothesis,pandas,pillow,poetry,pt
                         r,pyanalyze,pyramid,pytest,scikit-
                         lego,tox,typeshed,virtualenv,warehouse]
  -R, --rebase           Rebase project if already checked out  [default:
                         False]
  -w, --workdir PATH     Directory path for repo checkouts  [default:
                         /tmp/primer.20220121224953]
  -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
  -h, --help             Show this message and exit.

diff-shades

diff-shades is a tool similar to black-primer, it also runs Black across a list of Git cloneable OSS projects recording the results. The intention is to eventually fully replace black-primer with diff-shades as it’s much more feature complete and supports our needs better.

The main highlight feature of diff-shades is being able to compare two revisions of Black. This is incredibly useful as it allows us to see what exact changes will occur, say merging a certain PR. Black-primer’s results would usually be filled with changes caused by pre-existing code in Black drowning out the (new) changes we want to see. It operates similarly to black-primer but crucially it saves the results as a JSON file which allows for the rich comparison features alluded to above.

For more information, please see the diff-shades documentation.

CI integration

diff-shades is also the tool behind the “diff-shades results comparing …” / “diff-shades reports zero changes …” comments on PRs. The project has a GitHub Actions workflow which runs diff-shades twice against two revisions of Black according to these rules:

	Baseline revision	Target revision
On PRs	latest commit on main	PR commit with main merged
On pushes (main only)	latest PyPI version	the pushed commit

Once finished, a PR comment will be posted embedding a summary of the changes and links to further information. If there’s a pre-existing diff-shades comment, it’ll be updated instead the next time the workflow is triggered on the same PR.

The workflow uploads 3-4 artifacts upon completion: the two generated analyses (they have the .json file extension), diff.html, and .pr-comment.json if triggered by a PR. The last one is downloaded by the diff-shades-comment workflow and shouldn’t be downloaded locally. diff.html comes in handy for push-based or manually triggered runs. And the analyses exist just in case you want to do further analysis using the collected data locally.

Note that the workflow will only fail intentionally if while analyzing a file failed to format. Otherwise a failure indicates a bug in the workflow.

Tip

Maintainers with write access or higher can trigger the workflow manually from the Actions tab using the workflow_dispatch event. Simply select “diff-shades” from the workflows list on the left, press “Run workflow”, and fill in which revisions and command line arguments to use.

Once finished, check the logs or download the artifacts for local use.

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:

1. the issue is waiting for triage

2. 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 repro or S: awaiting reponse)

3. confirmed - the issue can reproduced and necessary details have been provided

4. discussion - initial triage has been done and now the general details on how the issue should be best resolved are being hashed out

5. awaiting fix - no further discussion on the issue is necessary and a resolving PR is the next step

6. 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:

1. the issue is waiting for triage

2. identified - has been marked with a type label and other relevant labels

3. 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

4. accepted & awaiting PR - it’s been determined the suggested changes are OK and a PR would be welcomed (S: accepted)

5. 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:

1. Cut a new PR editing CHANGES.md and the docs to version the latest changes

   1. Example PR: #2616

   2. Example title: Update CHANGES.md for XX.X release

2. Once the release PR is merged ensure all CI passes

   1. If not, ensure there is an Issue open for the cause of failing CI (generally we’d want this fixed before cutting a release)

3. Open CHANGES.md and copy the raw markdown of the latest changes to use in the description of the GitHub Release.

4. Go and cut a release using the GitHub UI so that all workflows noted below are triggered.

   1. The release version and tag should be the CalVer version Black used for the current release e.g. 21.6 / 21.5b1

   2. Black uses setuptools scm to pull the current version for the package builds and release.

5. 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.

   1. 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.

Tag moving process

stable

From a rebased main checkout:

1. git tag -f stable VERSION_TAG

   1. e.g. git tag -f stable 21.5b1

2. git push --tags -f

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: typing.Dict[typing.Tuple[int, int], blib2to3.pytree.Leaf] = <factory>, delimiters: typing.Dict[int, int] = <factory>, previous: typing.Optional[blib2to3.pytree.Leaf] = None, _for_loop_depths: typing.List[int] = <factory>, _lambda_argument_depths: typing.List[int] = <factory>, invisible: typing.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.

any_open_brackets() → bool

Return True if there is an yet unmatched open bracket on the line.

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: typing.Optional[black.lines.Line] = None, previous_after: int = 0, previous_defs: typing.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: typing.List[blib2to3.pytree.Leaf] = <factory>, comments: typing.Dict[int, typing.List[blib2to3.pytree.Leaf]] = <factory>, bracket_tracker: black.brackets.BracketTracker = <factory>, inside_brackets: bool = False, should_split_rhs: bool = False, magic_trailing_comma: typing.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.

remove_trailing_comma() → None

Remove the trailing comma and moves the comments attached to it.

is_complex_subscript(leaf: blib2to3.pytree.Leaf) → bool

Return True iff leaf is part of a slice with non-trivial exprs.

enumerate_with_length(reversed: bool = False) → Iterator[Tuple[int, blib2to3.pytree.Leaf, int]]

Return an enumeration of leaves with their length.

Stops prematurely on multiline strings and standalone comments.

__str__() → str

Render the line.

__bool__() → bool

Return True if the line has leaves or comments.

LineGenerator

class black.LineGenerator(mode: black.mode.Mode)

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_match_case(node: blib2to3.pytree.Node) → Iterator[black.lines.Line]

Visit either a match or case statement.

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.Leaf so 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.

__str__() → str

Render a color report of the current state.

Use click.unstyle to remove colors.

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.

Enums

Changed

class black.Changed(value)

Bases: enum.Enum

An enumeration.

Mode

class black.Mode(target_versions: Set[black.mode.TargetVersion] = <factory>, line_length: int = 88, string_normalization: bool = True, is_pyi: bool = False, is_ipynb: bool = False, magic_trailing_comma: bool = True, experimental_string_processing: bool = False, python_cell_magics: Set[str] = <factory>, preview: bool = False)

Bases: object

WriteBack

class black.WriteBack(value)

Bases: enum.Enum

An enumeration.

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).

black.nodes.is_yield(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool

Return True if node holds a yield or yield from expression.

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() and assert_stable() on it. mode is passed to format_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() or format_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]) → Tuple[pathlib.Path, str]

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.

Returns a two-tuple with the first element as the project root path and the second element as a string describing the method by which the project root was discovered.

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], *, verbose: bool, quiet: bool) → 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.

black.read_pyproject_toml(ctx: click.core.Context, param: click.core.Parameter, value: Optional[str]) → Optional[str]

Inject Black configuration from “pyproject.toml” into defaults in ctx.

Returns the path to a successfully found and read configuration file, None otherwise.

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).

black.parsing.lib2to3_parse(src_txt: str, target_versions: Iterable[black.mode.TargetVersion] = ()) → blib2to3.pytree.Node

Given a string with source, return the lib2to3 Node.

black.parsing.lib2to3_unparse(node: blib2to3.pytree.Node) → str

Given a lib2to3 node, return its string representation.

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 CannotSplit if 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.numerics.format_float_or_int_string(text: str) → str

Formats a float string like “1.0”.

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() and visit_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 ProtoComment objects 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.

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) → str

Make all string prefixes lowercase.

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.strings.sub_twice(regex: Pattern[str], replacement: str, original: str) → str

Replace regex with replacement twice on original.

This is used by string normalization to perform replaces on overlapping matches.

black.nodes.whitespace(leaf: blib2to3.pytree.Leaf, *, complex_subscript: bool) → str

Return whitespace prefix if needed for the given leaf.

complex_subscript signals whether the given leaf is part of a subscription which has non-trivial arguments, like arithmetic expressions or function calls.

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 (which is to say, not very). This is deliberate. Black aims to provide a consistent style and take away opportunities for arguing about style.

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:

• The basics

• Gauging changes

• Release process

• Developer reference

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

Black

• Remove Python 2 support (#2740)

• Do not accept bare carriage return line endings in pyproject.toml (#2408)

• Improve error message for invalid regular expression (#2678)

• Improve error message when parsing fails during AST safety check by embedding the underlying SyntaxError (#2693)

• Fix mapping cases that contain as-expressions, like case {"key": 1 | 2 as password} (#2686)

• Fix cases that contain multiple top-level as-expressions, like case 1 as a, 2 as b (#2716)

• Fix call patterns that contain as-expressions with keyword arguments, like case Foo(bar=baz as quux) (#2749)

• No longer color diff headers white as it’s unreadable in light themed terminals (#2691)

• Tuple unpacking on return and yield constructs now implies 3.8+ (#2700)

• Unparenthesized tuples on annotated assignments (e.g values: Tuple[int, ...] = 1, 2, 3) now implies 3.8+ (#2708)

• Text coloring added in the final statistics (#2712)

• For stubs, one blank line between class attributes and methods is now kept if there’s at least one pre-existing blank line (#2736)

• Verbose mode also now describes how a project root was discovered and which paths will be formatted. (#2526)

• Speed-up the new backtracking parser about 4X in general (enabled when --target-version is set to 3.10 and higher). (#2728)

• Fix handling of standalone match() or case() when there is a trailing newline or a comment inside of the parentheses. (#2760)

• Black now normalizes string prefix order (#2297)

• Add configuration option (python-cell-magics) to format cells with custom magics in Jupyter Notebooks (#2744)

• Deprecate --experimental-string-processing and move the functionality under --preview (#2789)

Packaging

• All upper version bounds on dependencies have been removed (#2718)

• typing-extensions is no longer a required dependency in Python 3.10+ (#2772)

• Set click lower bound to 8.0.0 (#2791)

Preview style

• Introduce the --preview flag (#2752)

• Add --experimental-string-processing to the preview style (#2789)

Integrations

• Update GitHub action to support containerized runs (#2748)

Documentation

• Change protocol in pip installation instructions to https:// (#2761)

• Change HTML theme to Furo primarily for its responsive design and mobile support (#2793)

21.12b0

Black

• Fix determination of f-string expression spans (#2654)

• Fix bad formatting of error messages about EOF in multi-line statements (#2343)

• Functions and classes in blocks now have more consistent surrounding spacing (#2472)

• from __future__ import annotations statement now implies Python 3.7+ (#2690)

Jupyter Notebook support

• Cell magics are now only processed if they are known Python cell magics. Earlier, all cell magics were tokenized, leading to possible indentation errors e.g. with %%writefile. (#2630)

• Fix assignment to environment variables in Jupyter Notebooks (#2642)

Python 3.10 support

• Point users to using --target-version py310 if we detect 3.10-only syntax (#2668)

• Fix match statements with open sequence subjects, like match a, b: or match a, *b: (#2639) (#2659)

• Fix match/case statements that contain match/case soft keywords multiple times, like match re.match() (#2661)

• Fix case statements with an inline body (#2665)

• Fix styling of starred expressions inside match subject (#2667)

• Fix parser error location on invalid syntax in a match statement (#2649)

• Fix Python 3.10 support on platforms without ProcessPoolExecutor (#2631)

• Improve parsing performance on code that uses match under --target-version py310 up to ~50% (#2670)

Packaging

• Remove dependency on regex (#2644) (#2663)

21.11b1

Black

• Bumped regex version minimum to 2021.4.4 to fix Pattern class usage (#2621)

21.11b0

Black

• Warn about Python 2 deprecation in more cases by improving Python 2 only syntax detection (#2592)

• Add experimental PyPy support (#2559)

• Add partial support for the match statement. As it’s experimental, it’s only enabled when --target-version py310 is explicitly specified (#2586)

• Add support for parenthesized with (#2586)

• Declare support for Python 3.10 for running Black (#2562)

Integrations

• Fixed vim plugin with Python 3.10 by removing deprecated distutils import (#2610)

• The vim plugin now parses skip_magic_trailing_comma from pyproject.toml (#2613)

21.10b0

Black

• Document stability policy, that will apply for non-beta releases (#2529)

• Add new --workers parameter (#2514)

• Fixed feature detection for positional-only arguments in lambdas (#2532)

• Bumped typed-ast version minimum to 1.4.3 for 3.10 compatibility (#2519)

• Fixed a Python 3.10 compatibility issue where the loop argument was still being passed even though it has been removed (#2580)

• Deprecate Python 2 formatting support (#2523)

Blackd

• Remove dependency on aiohttp-cors (#2500)

• Bump required aiohttp version to 3.7.4 (#2509)

Black-Primer

• Add primer support for –projects (#2555)

• Print primer summary after individual failures (#2570)

Integrations

• Allow to pass target_version in the vim plugin (#1319)

• Install build tools in docker file and use multi-stage build to keep the image size down (#2582)

21.9b0

Packaging

• Fix missing modules in self-contained binaries (#2466)

• Fix missing toml extra used during installation (#2475)

21.8b0

Black

• Add support for formatting Jupyter Notebook files (#2357)

• Move from appdirs dependency to platformdirs (#2375)

• Present a more user-friendly error if .gitignore is invalid (#2414)

• The failsafe for accidentally added backslashes in f-string expressions has been hardened to handle more edge cases during quote normalization (#2437)

• Avoid changing a function return type annotation’s type to a tuple by adding a trailing comma (#2384)

• Parsing support has been added for unparenthesized walruses in set literals, set comprehensions, and indices (#2447).

• Pin setuptools-scm build-time dependency version (#2457)

• Exclude typing-extensions version 3.10.0.1 due to it being broken on Python 3.10 (#2460)

Blackd

• Replace sys.exit(-1) with raise ImportError as it plays more nicely with tools that scan installed packages (#2440)

Integrations

• The provided pre-commit hooks no longer specify language_version to avoid overriding default_language_version (#2430)

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_PARENTHESES feature is enabled (#2332)

• Accept empty stdin (#2346)

• Provide a more useful error when parsing fails during AST safety checks (#2304)

Docker

• Add new latest_release tag 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: skip and 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 --code flag (#2259)

• Do not call uvloop.install() when Black is used as a library (#2303)

• Added --required-version option 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 R prefixes would be lowercased for docstrings (#2285)

• Fix handling of named escapes (\N{...}) when --experimental-string-processing is 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 .gitignore files in all levels, not only root/.gitignore file (apply .gitignore rules like git does) (#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-cors dependency. 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-processing will 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__.py into many files (#2206)

Documentation

• Replaced all remaining references to the master branch with the main branch. 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 --pyi mode if --stdin-filename ends 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-diff to 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 .gitignore rules to be overridden by specifying exclude in pyproject.toml or on the command line. (#2170)

Packaging

• Install primer.json (used by black-primer by 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-comma and --experimental-string-processing flags 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 Black and optional parentheses looking at pre-existing “magic” trailing commas. This fixes issue #1629 and all of its many many duplicates. (#2126)

• Black now processes one-line docstrings by stripping leading and trailing spaces, and adding a padding space when needed to break up “”””. (#1740)

• Black now cleans up leading non-breaking spaces in comments (#2092)

• Black now respects --skip-string-normalization when normalizing multiline docstring quotes (#1637)

• Black no longer removes all empty lines between non-function code and decorators when formatting typing stubs. Now Black enforces a single empty line. (#1646)

• Black no longer adds an incorrect space after a parenthesized assignment expression in if/while statements (#1655)

• Added --skip-magic-trailing-comma / -C to 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-exclude argument (PR #2005)

• speed up caching by avoiding pathlib (#1950)

• --diff correctly indicates when a file doesn’t end in a newline (#1662)

• Added --stdin-filename argument to allow stdin to respect --force-exclude rules (#1780)

• Lines ending with fmt: skip will 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 venv directory 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 Black no 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)

• Black now reindents docstrings when reindenting code around it (#1053)

• Black now shows colored diffs (#1266)

• Black is now packaged using ‘py3’ tagged wheels (#1388)

• Black now supports Python 3.8 code, e.g. star expressions in return statements (#1121)

• Black no longer normalizes capital R-string prefixes as those have a community-accepted meaning (#1244)

• Black now uses exit code 2 when specified configuration file doesn’t exit (#1361)

• Black now works on AWS Lambda (#1141)

• added --force-exclude argument (#1032)

• removed deprecated --py36 option (#1236)

• fixed --diff output when EOF is encountered (#526)

• fixed # fmt: off handling around decorators (#560)

• fixed unstable formatting with some # type: ignore comments (#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-processing flag 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 -c as 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: on comment 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 … import blocks 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 yield expressions (#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)

• blackd now returns the version of Black in the response headers (#1013)

• blackd can now output the diff of formats on source code when the X-Diff header is provided (#969)

19.3b0

• new option --target-version to control which Python versions Black-formatted code should target (#618)

• deprecated --py36 (use --target-version=py36 instead) (#724)

• Black no longer normalizes numeric literals to include _ separators (#696)

• long del statements 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)

• blackd now 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+ code

  • added --skip-numeric-underscore-normalization to disable the above behavior and leave numeric underscores as they were in the input

  • code 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 --check is 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: off when directly preceding yield and other nodes (#385)

• fixed formatting of lambda expressions with default arguments (#468)

• fixed async for statements: 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: off and # fmt: on are 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 -h equivalent to --help (#316)

• fixed improper unmodified file caching when -S was used

• fixed 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 --include and --exclude (#270)

• added --skip-string-normalization (#118)

• added --verbose (#283)

• the header output in --diff now actually conforms to the unified diff spec

• fixed 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: off sections (#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 u is removed on Python 3.6+ only code and Python 2.7+ code with the unicode_literals future 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)

• --check and --diff are 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 --diff not 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 --check with 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: disable usage 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: off and # fmt: on are 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 async as 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 --check

• only 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 *args or **kwargs used 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:

• Abdur-Rahmaan Janhangeer

• Adam Johnson

• Adam Williamson

• Alexander Huynh

• Alex Vandiver

• Allan Simon

• Anders-Petter Ljungquist

• Andrew Thorp

• Andrew Zhou

• Andrey

• Andy Freeland

• Anthony Sottile

• Arjaan Buijk

• Arnav Borbornah

• Artem Malyshev

• Asger Hautop Drewsen

• Augie Fackler

• Aviskar KC

• Batuhan Taşkaya

• Benjamin Wohlwend

• Benjamin Woodruff

• Bharat Raghunathan

• Brandt Bucher

• Brett Cannon

• Bryan Bugyi

• Bryan Forbes

• Calum Lind

• Charles

• Charles Reid

• Christian Clauss

• Christian Heimes

• Chuck Wooters

• Chris Rose

• Codey Oxley

• Cong

• Cooper Ry Lees

• Dan Davison

• Daniel Hahler

• Daniel M. Capella

• Daniele Esposti

• David Hotham

• David Lukes

• David Szotten

• Denis Laxalde

• Douglas Thor

• dylanjblack

• Eli Treuherz

• Emil Hessman

• Felix Kohlgrüber

• Florent Thiery

• Francisco

• Giacomo Tagliabue

• Greg Gandenberger

• Gregory P. Smith

• Gustavo Camargo

• hauntsaninja

• Hadi Alqattan

• Hassan Abouelela

• Heaford

• Hugo Barrera

• Hugo van Kemenade

• Hynek Schlawack

• Ivan Katanić

• Jakub Kadlubiec

• Jakub Warczarek

• Jan Hnátek

• Jason Fried

• Jason Friedland

• jgirardet

• Jim Brännlund

• Jimmy Jia

• Joe Antonakakis

• Jon Dufresne

• Jonas Obrist

• Jonty Wareing

• Jose Nazario

• Joseph Larson

• Josh Bode

• Josh Holland

• Joshua Cannon

• José Padilla

• Juan Luis Cano Rodríguez

• kaiix

• Katie McLaughlin

• Katrin Leinweber

• Keith Smiley

• Kenyon Ralph

• Kevin Kirsche

• Kyle Hausmann

• Kyle Sunden

• Lawrence Chan

• Linus Groh

• Loren Carvalho

• Luka Sterbic

• LukasDrude

• Mahmoud Hossam

• Mariatta

• Matt VanEseltine

• Matthew Clapp

• Matthew Walster

• Max Smolens

• Michael Aquilina

• Michael Flaxman

• Michael J. Sullivan

• Michael McClimon

• Miguel Gaiowski

• Mike

• mikehoyio

• Min ho Kim

• Miroslav Shubernetskiy

• MomIsBestFriend

• Nathan Goldbaum

• Nathan Hunt

• Neraste

• Nikolaus Waxweiler

• Ofek Lev

• Osaetin Daniel

• otstrel

• Pablo Galindo

• Paul Ganssle

• Paul Meinhardt

• Peter Bengtsson

• Peter Grayson

• Peter Stensmyr

• pmacosta

• Quentin Pradet

• Ralf Schmitt

• Ramón Valles

• Richard Fearn

• Rishikesh Jha

• Rupert Bedford

• Russell Davis

• Rémi Verschelde

• Sami Salonen

• Samuel Cormier-Iijima

• Sanket Dasgupta

• Sergi

• Scott Stevenson

• Shantanu

• shaoran

• Shinya Fujino

• springstan

• Stavros Korokithakis

• Stephen Rosen

• Steven M. Vascellaro

• Sunil Kapil

• Sébastien Eustace

• Tal Amuyal

• Terrance

• Thom Lu

• Thomas Grainger

• Tim Gates

• Tim Swast

• Timo

• Toby Fleming

• Tom Christie

• Tony Narlock

• Tsuyoshi Hombashi

• Tushar Chandra

• Tzu-ping Chung

• Utsav Shah

• utsav-dbx

• vezeli

• Ville Skyttä

• Vishwas B Sharma

• Vlad Emelianov

• williamfzc

• wouter bolsterlee

• Yazdan

• Yngve Høiseth

• Yurii Karabas

• Zac Hatfield-Dodds

Indices and tables

• Index

• Search Page