---
_Contents:_ **[Installation and usage](#installation-and-usage)** |
-**[Code style](#the-black-code-style)** | **[pyproject.toml](#pyprojecttoml)** |
-**[Editor integration](#editor-integration)** | **[blackd](#blackd)** |
-**[Version control integration](#version-control-integration)** |
-**[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Used by](#used-by)** |
-**[Testimonials](#testimonials)** | **[Show your style](#show-your-style)** |
+**[Code style](#the-black-code-style)** | **[Pragmatism](#pragmatism)** |
+**[pyproject.toml](#pyprojecttoml)** | **[Editor integration](#editor-integration)** |
+**[blackd](#blackd)** | **[Version control integration](#version-control-integration)**
+| **[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Used by](#used-by)**
+| **[Testimonials](#testimonials)** | **[Show your style](#show-your-style)** |
**[Contributing](#contributing-to-black)** | **[Change Log](#change-log)** |
**[Authors](#authors)**
_Black_ doesn't provide many options. You can list them by running `black --help`:
```text
-black [OPTIONS] [SRC]...
+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 [py27|py33|py34|py35|py36|py37|py38]
Python versions that should be supported by
Black's output. [default: per-file auto-
detection]
- --py36 Allow using Python 3.6-only syntax on all
- input files. This will put trailing commas
- in function signatures and calls also after
- *args and **kwargs. Deprecated; use
- --target-version instead. [default: per-file
- auto-detection]
+
--pyi Format all input files like typing stubs
regardless of file extension (useful when
piping source on standard input).
+
-S, --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. Return code 123 means
+ 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]
+
--include TEXT A regular expression that matches files and
directories that should be included on
recursive searches. An empty value means
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
directories on all platforms (Windows, too).
Exclusions are calculated first, inclusions
later. [default: /(\.eggs|\.git|\.hg|\.mypy
- _cache|\.nox|\.tox|\.venv|_build|buck-
+ _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-
out|build|dist)/]
+
+ --force-exclude TEXT Like --exclude, but files and directories
+ matching this regex will be excluded even
+ when they are passed explicitly as arguments
+
-q, --quiet Don't emit non-error messages to stderr.
- Errors are still emitted, silence those with
+ 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
--exclude=.
+
--version Show the version and exit.
- --config PATH Read configuration from PATH.
+ --config FILE Read configuration from PATH.
-h, --help Show this message and exit.
```
- it only outputs messages to users on standard error;
- exits with code 0 unless an internal error occurred (or `--check` was used).
+### Using _Black_ with other tools
+
+While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
+about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
+[isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
+should be configured to neither warn about nor overwrite _Black_'s changes.
+
+Actual details on _Black_ compatible configurations for various tools can be found in
+[compatible_configs](./docs/compatible_configs.md).
+
### NOTE: This is a beta product
_Black_ is already [successfully used](#used-by) by many projects, small and big. It
- 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:
+
+```py3
+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.
+
+### 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](https://github.com/MagicStack/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.
+
## pyproject.toml
_Black_ is able to read project-specific default values for its command line options
%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:
To install with [vim-plug](https://github.com/junegunn/vim-plug):
```
-Plug 'psf/black'
+Plug 'psf/black', { 'branch': 'stable' }
```
or with [Vundle](https://github.com/VundleVim/Vundle.vim):
Plugin 'psf/black'
```
+and execute the following in a terminal:
+
+```console
+$ cd ~/.vim/bundle/black
+$ git checkout origin/stable -b stable
+```
+
or you can copy the plugin from
-[plugin/black.vim](https://github.com/psf/black/tree/master/plugin/black.vim).
+[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
```
mkdir -p ~/.vim/pack/python/start/black/plugin
Poetry, PyPA applications (Warehouse, Pipenv, virtualenv), pandas, Pillow, every Datadog
Agent Integration, Home Assistant.
+The following organizations use _Black_: Dropbox.
+
Are we missing anyone? Let us know.
## Testimonials
More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
+## Change Log
+
+The log's become rather long. It moved to its own file.
+
+See [CHANGES](CHANGES.md).
+
## Authors
Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
[Carl Meyer](mailto:carl@oddbird.net),
[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
-[Mika Naylor](mailto:mail@autophagy.io), and
-[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com).
+[Mika Naylor](mailto:mail@autophagy.io),
+[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com), and
+[Cooper Lees](mailto:me@cooperlees.com).
Multiple contributions by:
-- [Abdur-Rahmaan Janhangeer](mailto:cryptolabour@gmail.com)
+- [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
- [Adam Johnson](mailto:me@adamj.eu)
- [Alexander Huynh](mailto:github@grande.coffee)
- [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)
projects / etc / vim.git / blobdiff