### Installation
-_Black_ can be installed by running `pip install black`. It requires Python 3.6.0+ to
-run but you can reformat Python 2 code with it, too.
+_Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
+run. If you want to format Python 2 code as well, install with
+`pip install black[python2]`.
#### Install from GitHub
split lines.
--check Don't write the files back, just return the
- status. Return code 0 means nothing would
- change. Return code 1 means some files
+ 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.
--include TEXT A regular expression that matches files and
directories that should be included on
- recursive searches. An empty value means
+ 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
+ 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
+ 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|\.
- hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
- ild|buck-out|build|dist)/]
+ later. [default: /(\.direnv|\.eggs|\.git|\.
+ hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.sv
+ n|_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
-v, --verbose Also emit messages to stderr about files
that were not changed or were ignored due to
- --exclude=.
+ exclusion patterns.
--version Show the version and exit.
--config FILE Read configuration from FILE path.
mostly responses to bug reports.
Also, as a temporary safety measure, _Black_ will check that the reformatted code still
-produces a valid AST that is equivalent to the original. This slows it down. If you're
-feeling confident, use `--fast`.
+produces a valid AST that is mostly equivalent to the original. This slows it down. If
+you're feeling confident, use `--fast`. In a few contexts, Black does make changes to
+the AST: it cleans up whitespace in docstrings, adds or removes parentheses in some
+`del` statements, and may move around type comments.
## The _Black_ code style
_Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
place. It is not configurable. It doesn't take previous formatting into account. Your
main option of configuring _Black_ is that it doesn't reformat blocks that start with
-`# fmt: off` and end with `# fmt: on`. `# fmt: on/off` have to be on the same level of
-indentation. To learn more about _Black_'s opinions, to go
+`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`. Pay
+attention that `# fmt: on/off` have to be on the same level of indentation. To learn
+more about _Black_'s opinions, to go
[the_black_code_style](https://github.com/psf/black/blob/master/docs/the_black_code_style.md).
Please refer to this document before submitting an issue. What seems like a bug might be
_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` patterns for your project.
+`--include` and `--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.
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.
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
-exclude = '''
+extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# in the root of the project.
-^/(
- (
- \.eggs # exclude a few common directories in the
- | \.git # root of the project
- | \.hg
- | \.mypy_cache
- | \.tox
- | \.venv
- | _build
- | buck-out
- | build
- | dist
- )/
- | foo.py # also separately exclude a file named foo.py 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)
'''
```
- uses: actions/setup-python@v2
- uses: psf/black@stable
with:
- black_args: ". --check"
+ args: ". --check"
```
### Inputs
The following notable open-source projects trust _Black_ with enforcing a consistent
code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
-every Datadog Agent Integration, Home Assistant.
+every Datadog Agent Integration, Home Assistant, Zulip.
The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora.
[Carl Meyer](mailto:carl@oddbird.net),
[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
[Mika Naylor](mailto:mail@autophagy.io),
-[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com), and
-[Cooper Lees](mailto:me@cooperlees.com).
+[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com),
+[Cooper Lees](mailto:me@cooperlees.com), and Richard Si.
Multiple contributions by:
- [Joseph Larson](mailto:larson.joseph@gmail.com)
- [Josh Bode](mailto:joshbode@fastmail.com)
- [Josh Holland](mailto:anowlcalledjosh@gmail.com)
+- [Joshua Cannon](mailto:joshdcannon@gmail.com)
- [José Padilla](mailto:jpadilla@webapplicate.com)
- [Juan Luis Cano Rodríguez](mailto:hello@juanlu.space)
- [kaiix](mailto:kvn.hou@gmail.com)
projects / etc / vim.git / blobdiff