black
black documentation
- Version in MegaLinter: 23.11.0
- Visit Official Web Site
- See How to configure black rules
- If custom
pyproject.tomlconfig file isn't found, pyproject.toml will be used
- If custom
Configuration in MegaLinter
- Enable black by adding
PYTHON_BLACKin ENABLE_LINTERS variable - Disable black by adding
PYTHON_BLACKin DISABLE_LINTERS variable
- Enable autofixes by adding
PYTHON_BLACKin APPLY_FIXES variable
| Variable | Description | Default value |
|---|---|---|
| PYTHON_BLACK_ARGUMENTS | User custom arguments to add in linter CLI call Ex: -s --foo "bar" |
|
| PYTHON_BLACK_COMMAND_REMOVE_ARGUMENTS | User custom arguments to remove from command line before calling the linter Ex: -s --foo "bar" |
|
| PYTHON_BLACK_FILTER_REGEX_INCLUDE | Custom regex including filter Ex: (src\|lib) |
Include every file |
| PYTHON_BLACK_FILTER_REGEX_EXCLUDE | Custom regex excluding filter Ex: (test\|examples) |
Exclude no file |
| PYTHON_BLACK_CLI_LINT_MODE | Override default CLI lint mode - file: Calls the linter for each file- list_of_files: Call the linter with the list of files as argument- project: Call the linter from the root of the project |
list_of_files |
| PYTHON_BLACK_FILE_EXTENSIONS | Allowed file extensions. "*" matches any extension, "" matches empty extension. Empty list excludes all filesEx: [".py", ""] |
[".py"] |
| PYTHON_BLACK_FILE_NAMES_REGEX | File name regex filters. Regular expression list for filtering files by their base names using regex full match. Empty list includes all files Ex: ["Dockerfile(-.+)?", "Jenkinsfile"] |
Include every file |
| PYTHON_BLACK_PRE_COMMANDS | List of bash commands to run before the linter | None |
| PYTHON_BLACK_POST_COMMANDS | List of bash commands to run after the linter | None |
| PYTHON_BLACK_UNSECURED_ENV_VARIABLES | List of env variables explicitly not filtered before calling PYTHON_BLACK and its pre/post commands | None |
| PYTHON_BLACK_CONFIG_FILE | black configuration file nameUse LINTER_DEFAULT to let the linter find it |
pyproject.toml |
| PYTHON_BLACK_RULES_PATH | Path where to find linter configuration file | Workspace folder, then MegaLinter default rules |
| PYTHON_BLACK_DISABLE_ERRORS | Run linter but consider errors as warnings | true |
| PYTHON_BLACK_DISABLE_ERRORS_IF_LESS_THAN | Maximum number of errors allowed | 0 |
| PYTHON_BLACK_CLI_EXECUTABLE | Override CLI executable | ['black'] |
IDE Integration
Use black in your favorite IDE to catch errors before MegaLinter !
MegaLinter Flavours
This linter is available in the following flavours
| Flavor | Description | Embedded linters | Info | |
|---|---|---|---|---|
 |
all | Default MegaLinter Flavor | 121 |   |
| cupcake | MegaLinter for the most commonly used languages | 85 |   |
|
| formatters | Contains only formatters | 17 |   |
|
| python | Optimized for PYTHON based projects | 62 |   |
Behind the scenes
How are identified applicable files
- File extensions:
.py
How the linting is performed
- black is called once with the list of files as arguments (
list_of_filesCLI lint mode)
Example calls
black --diff --check myfile.py
black --config pyproject.toml --diff --check myfile.py
black --config pyproject.toml myfile.py
Help content
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|py311|py312]
Python versions that should be supported by
Black's output. By default, Black will try
to infer this from the project metadata in
pyproject.toml. If this does not yield
conclusive results, Black will use 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 (capture, prun, pypy, python,
python3, time, timeit). Useful for
formatting cells with custom python magics.
-x, --skip-source-first-line Skip the first line of the source code.
-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 may 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.
--line-ranges START-END When specified, _Black_ will try its best to
only format these lines. This option can be
specified multiple times, and a union of the
lines will be formatted. Each range must be
specified as two integers connected by a
`-`: `<START>-<END>`. The `<START>` and
`<END>` integer indices are 1-based and
inclusive on both ends.
--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). It can be either a major version
number or an exact version.
--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?|\.ipynb)$]
--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|\.ipynb_checkpoints|\.mypy_cache|\.nox|\.p
ytest_cache|\.ruff_cache|\.tox|\.svn|\.venv|
\.vscode|__pypackages__|_build|buck-
out|build|dist|venv)/]
--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:
BLACK_NUM_WORKERS environment variable or
number of CPUs in the system] [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.
Installation on mega-linter Docker image
- PIP packages (Python):