*Black* makes code review faster by producing the smallest diffs
possible.
+---
-## Installation and Usage
+*Contents:* **[Installation and usage](#installation-and-usage)** |
+**[The *Black* code style](#the-black-code-style)** |
+**[Editor integration](#editor-integration)** |
+**[Version control integration](#version-control-integration)** |
+**[Ignoring unmodified files](#ignoring-unmodified-files)** |
+**[Testimonials](#testimonials)** |
+**[Show your style](#show-your-style)** |
+**[License](#license)** |
+**[Contributing](#contributing-to-black)** |
+**[Change Log](#change-log)** |
+**[Authors](#authors)**
+
+---
+
+## Installation and usage
### Installation
Options:
-l, --line-length INTEGER Where to wrap around. [default: 88]
+ --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. [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
for each file on stdout.
--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. On Windows, use forward
+ slashes for directories. [default: \.pyi?$]
+ --exclude TEXT A regular expression that matches files and
+ directories that should be excluded on
+ recursive searches. On Windows, use forward
+ slashes for directories. [default:
+ build/|buck-out/|dist/|_build/|\.git/|\.hg/|
+ \.mypy_cache/|\.tox/|\.venv/]
-q, --quiet Don't emit non-error messages to stderr. Errors
are still emitted, silence those with
2>/dev/null.
used).
-### NOTE: This is an early pre-release
+### NOTE: This is a beta product
-*Black* can already successfully format itself and the standard library.
+*Black* is already successfully used by several projects, small and big.
It also sports a decent test suite. However, it is still very new.
Things will probably be wonky for a while. This is made explicit by the
-"Alpha" trove classifier, as well as by the "a" in the version number.
+"Beta" trove classifier, as well as by the "b" in the version number.
What this means for you is that **until the formatter becomes stable,
-you should expect some formatting to change in the future**.
+you should expect some formatting to change in the future**. That being
+said, no drastic stylistic changes are planned, 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
```py3
# in:
-l = [[n for n in list_bosses()], [n for n in list_employees()]]
+TracebackException.from_exception(exc, limit, lookup_lines, capture_locals)
# out:
-l = [
- [n for n in list_bosses()], [n for n in list_employees()]
-]
+TracebackException.from_exception(
+ exc, limit, lookup_lines, capture_locals
+)
```
If that still doesn't fit the bill, it will decompose the internal
indentation level (like the arguments list and the docstring in the
example above).
-If a line of "from" imports cannot fit in the allotted length, it's always split
-into one per line. Imports tend to change often and this minimizes diffs, as well
-as enables readers of code to easily find which commit introduced a particular
-import. This exception also makes *Black* compatible with
-[isort](https://pypi.org/p/isort/). Use `multi_line_output=3`,
-`include_trailing_comma=True`, `force_grid_wrap=0`, and `line_length=88` in your
-isort config.
+If a data structure literal (tuple, list, set, dict) or a line of "from"
+imports cannot fit in the allotted length, it's always split into one
+element per line. This minimizes diffs as well as enables readers of
+code to find which commit introduced a particular entry. This also
+makes *Black* compatible with [isort](https://pypi.org/p/isort/) with
+the following configuration.
+
+<details>
+<summary>A compatible `.isort.cfg`</summary>
+
+```
+[settings]
+multi_line_output=3
+include_trailing_comma=True
+force_grid_wrap=0
+combine_as_imports=True
+line_length=88
+```
+The equivalent command line is:
+```
+$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --combine-as --line-width=88 [ file.py ]
+```
+</details>
### Line length
It will also insert proper spacing before and after function definitions.
It's one line before and after inner functions and two lines before and
-after module-level functions. *Black* will not put empty lines between
-function/class definitions and standalone comments that immediately precede
-the given function/class.
+after module-level functions and classes. *Black* will not put empty
+lines between function/class definitions and standalone comments that
+immediately precede the given function/class.
+
+*Black* will enforce single empty lines between a class-level docstring
+and the first following field or method. This conforms to
+[PEP 257](https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings).
+
+*Black* won't insert empty lines after function docstrings unless that
+empty line is required due to an inner function starting immediately
+after.
### Trailing commas
recognize it was safe to do so, put it there manually and *Black* will
keep it.
+
### Strings
*Black* prefers double quotes (`"` and `"""`) over single quotes (`'`
key. My recommendation here is to keep using whatever is faster to type
and let *Black* handle the transformation.
-### Line Breaks & Binary Operators
+If you are adopting *Black* in a large project with pre-existing string
+conventions (like the popular ["single quotes for data, double quotes for
+human-readable strings"](https://stackoverflow.com/a/56190)), you can
+pass `--skip-string-normalization` on the command line. This is meant as
+an adoption helper, avoid using this for new projects.
+
+
+### Line breaks & binary operators
*Black* will break a line before a binary operator when splitting a block
of code over multiple lines. This is so that *Black* is compliant with the
style guide enforcement tools like Flake8. Since ``W503`` is not PEP 8 compliant,
you should tell Flake8 to ignore these warnings.
+
### Slices
PEP 8 [recommends](https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements)
enforcement tools like Flake8. Since ``E203`` is not PEP 8 compliant, you should
tell Flake8 to ignore these warnings.
+
### Parentheses
Some parentheses are optional in the Python grammar. Any expression can
decision = (maybe.this() and values > 0) or (maybe.that() and values < 0)
```
+
### Call chains
Some popular APIs, like ORMs, use call chaining. This API style is known
as a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface).
-*Black* formats those treating dots that follow a call or an indexing
+*Black* formats those by treating dots that follow a call or an indexing
operation like a very low priority delimiter. It's easier to show the
behavior than to explain it. Look at the example:
```py3
)
```
+
### Typing stub files
PEP 484 describes the syntax for type hints in Python. One of the
1. Install `black`.
- $ pip install black
+```console
+$ pip install black
+```
2. Locate your `black` installation folder.
- On MacOS / Linux / BSD:
+ On macOS / Linux / BSD:
- $ which black
- /usr/local/bin/black # possible location
+```console
+$ which black
+/usr/local/bin/black # possible location
+```
On Windows:
- $ where black
- %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
+```console
+$ where black
+%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
+```
3. Open External tools in PyCharm with `File -> Settings -> Tools -> External Tools`.
- Arguments: $FilePath$
5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
- - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap`.
+ - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap -> External Tools -> External Tools - Black`.
### Vim
create a virtualenv manually and point `g:black_virtualenv` to it.
The plugin will use it.
+To run *Black* on save, add the following line to `.vimrc` or `init.vim`:
+
+```
+autocmd BufWritePost *.py execute ':Black'
+```
+
**How to get Vim with Python 3.6?**
On Ubuntu 17.10 Vim comes with Python 3.6 by default.
-On macOS with HomeBrew run: `brew install vim --with-python3`.
+On macOS with Homebrew run: `brew install vim --with-python3`.
When building Vim from source, use:
`./configure --enable-python3interp=yes`. There's many guides online how
to do this.
Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+
### SublimeText 3
Use [sublack plugin](https://github.com/jgirardet/sublack).
+
### IPython Notebook Magic
Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
+
### Other editors
Atom/Nuclide integration is planned by the author, others will
hooks:
- id: black
args: [--line-length=88, --safe]
- python_version: python3.6
+ language_version: python3.6
```
Then run `pre-commit install` and you're ready to go.
`args` in the above config is optional but shows you how you can change
the line length if you really need to. If you're already using Python
-3.7, switch the `python_version` accordingly. Finally, `stable` is a tag
+3.7, switch the `language_version` accordingly. Finally, `stable` is a tag
that is pinned to the latest release on PyPI. If you'd rather run on
master, this is also an option.
-## Ignoring non-modified files
+## Ignoring unmodified files
-*Black* remembers files it already formatted, unless the `--diff` flag is used or
+*Black* remembers files it has already formatted, unless the `--diff` flag is used or
code is passed via standard input. This information is stored per-user. The exact
location of the file depends on the black version and the system on which black
is run. The file is non-portable. The standard location on common operating systems
## Change Log
-### 18.5a0 (unreleased)
+### 18.6b0
+
+* added `--include` and `--exclude` (#270)
+
+* added `--skip-string-normalization` (#118)
+
+* fixed stdin handling not working correctly if an old version of Click was
+ used (#276)
+
+
+### 18.5b1
+
+* added `--pyi` (#249)
+
+* added `--py36` (#249)
+
+* Python grammar pickle caches are stored with the formatting caches, making
+ *Black* work in environments where site-packages is not user-writable (#192)
-* call chains are now formatted according to the [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67)
+* *Black* now enforces a PEP 257 empty line after a class-level docstring
+ (and/or fields) and the first method
+
+* fixed invalid code produced when standalone comments were present in a trailer
+ that was omitted from line splitting on a large expression (#237)
+
+* fixed optional parentheses being removed within `# fmt: off` sections (#224)
+
+* fixed invalid code produced when stars in very long imports were incorrectly
+ wrapped in optional parentheses (#234)
+
+* fixed unstable formatting when inline comments were moved around in
+ a trailer that was omitted from line splitting on a large expression
+ (#238)
+
+* fixed extra empty line between a class declaration and the first
+ method if no class docstring or fields are present (#219)
+
+* fixed extra empty line between a function signature and an inner
+ function or inner class (#196)
+
+
+### 18.5b0
+
+* call chains are now formatted according to the
+ [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface)
+ style (#67)
+
+* data structure literals (tuples, lists, dictionaries, and sets) are
+ now also always exploded like imports when they don't fit in a single
+ line (#152)
* slices are now formatted according to PEP 8 (#178)
* [Ivan Katanić](mailto:ivan.katanic@gmail.com)
* [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
* [Jonas Obrist](mailto:ojiidotch@gmail.com)
+* [Luka Sterbic](mailto:luka.sterbic@gmail.com)
* [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
* [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
+* [Stavros Korokithakis](mailto:hi@stavros.io)
* [Sunil Kapil](mailto:snlkapil@gmail.com)
* [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
+
+---
+
+*Contents:*
+**[Installation and Usage](#installation-and-usage)** |
+**[The *Black* code style](#the-black-code-style)** |
+**[Editor integration](#editor-integration)** |
+**[Version control integration](#version-control-integration)** |
+**[Ignoring unmodified files](#ignoring-unmodified-files)** |
+**[Testimonials](#testimonials)** |
+**[Show your style](#show-your-style)** |
+**[License](#license)** |
+**[Contributing](#contributing-to-black)** |
+**[Change Log](#change-log)** |
+**[Authors](#authors)**
projects / etc / vim.git / blobdiff