black
black documentation
- Version in MegaLinter: 22.3.0
- Visit Official Web Site
- See How to configure black rules
- If custom
pyproject.tomlconfig file is not 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 auto-fixes 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_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_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 |
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 | 97 |   |
| python | Optimized for PYTHON based projects | 49 |   |
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
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]
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 (capture, prun, pypy, python3,
python, time, timeit). 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 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.
--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|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn
|_build|buck-
out|build|dist|__pypackages__)/]
--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.
Installation on mega-linter Docker image
- PIP packages (Python):
Example success log
Results of black linter (version 19.10)
See documentation on https://megalinter.github.io/descriptors/python_black/
-----------------------------------------------
[SUCCESS] .automation/test/python/python_good_1.py
All done! ✨ 🍰 ✨
1 file would be left unchanged.
Example error log
Results of black linter (version 19.10)
See documentation on https://megalinter.github.io/descriptors/python_black/
-----------------------------------------------
[ERROR] .automation/test/python/python_bad_1.py
error: cannot format .automation/test/python/python_bad_1.py: Cannot parse: 15:23: if github_token is None
Oh no! 💥 💔 💥
1 file would fail to reformat.