black

Auto-format a file or entire directory

$ black [path/to/file_or_directory]

$ black [[-c|--code]] "[code]"

$ black --check [path/to/file_or_directory]

$ black --diff [path/to/file_or_directory]

$ black [[-q|--quiet]] [path/to/file_or_directory]

$ black [[-S|--skip-string-normalization]] [path/to/file_or_directory]

black [OPTIONS] [PATH ...]

--line-length INTEGER
    The preferred line length. Defaults to 88.

--target-version PYTHON_VERSION
    Python versions that should be supported by Black's output. The command can support multiple versions at once. Example: py37,py38,py39.

--skip-string-normalization
    Don't normalize string quotes or prefixes.

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

--diff
    Instead of writing to the file, print a diff to standard output.

--include PATTERN
    A regular expression that matches files and directories that should be included.
May be specified multiple times.

--exclude PATTERN
    A regular expression that matches files and directories that should be excluded.
May be specified multiple times.

--extend-exclude PATTERN
    Like --exclude, but adds to the default exclusion regex.

--force-exclude PATTERN
    Like --exclude, but excludes even when --include is used.

--fast
    Skip sanity checks.

--verbose
    Show more output.

--quiet
    Don't emit non-error messages to stderr. Errors are still emitted; silence those with 2>/dev/null.

--version
    Show the version and exit.

PATH
    Files and directories to format. If no path is specified, Black will attempt to discover and format all Python files in the current directory.

The `black` command, *hypothetically*, automatically formats Python code to adhere to the Black code style. It prioritizes consistency and readability by enforcing a single, uncompromising code style. `black` automates the formatting process, saving developers time and ensuring code consistency across projects. It modifies files in-place by default, which significantly speeds up development workflow. The command is designed to be opinionated, avoiding configuration options that would allow developers to deviate from the standard style.

Beyond formatting, `black` also aims to minimize diffs by prioritizing horizontal alignment for multiline statements and reformatting code to reduce semantic changes.

Modifies files in-place unless `--check` or `--diff` is used. Requires Python 3.6+ to run. Relies on stable AST transformations, which can sometimes lead to unexpected formatting changes in edge cases.

The `black` command returns 0 if no changes are needed or if formatting was successful. It returns 1 if changes were needed and the `--check` flag was used. Any other non-zero exit code indicates an error.

Format a single file: black my_file.py
Format all Python files in the current directory: black .
Check if a file needs formatting without modifying it: black --check my_file.py
Show the diff of changes that would be made: black --diff my_file.py

The `black` command was conceived with the aim of providing a completely opinionated code formatter, eliminating debates about code style. First released, it quickly gained popularity within the Python community due to its ease of use and its consistent formatting results.

autopep8(1), flake8(1), pylint(1)