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 put those empty lines also
-between the function definition and any standalone comments that
-immediately precede the given function. If you want to comment on the
-entire function, use a docstring or put a leading comment in the function
-body.
+after module-level functions. *Black* will not put empty lines between
+function/class definitions and standalone comments that immediately precede
+the given function/class.
### Trailing commas
key. My recommendation here is to keep using whatever is faster to type
and let *Black* handle the transformation.
+### 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
+recent changes in the [PEP 8](https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator)
+style guide, which emphasizes that this approach improves readability.
+
+This behaviour may raise ``W503 line break before binary operator`` warnings in
+style guide enforcement tools like Flake8. Since ``W503`` 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
+be wrapped in a pair of parentheses to form an atom. There are a few
+interesting cases:
+
+- `if (...):`
+- `while (...):`
+- `for (...) in (...):`
+- `assert (...), (...)`
+- `from X import (...)`
+
+In those cases, parentheses are removed when the entire statement fits
+in one line, or if the inner expression doesn't have any delimiters to
+further split on. Otherwise, the parentheses are always added.
+
## Editor integration
Use [proofit404/blacken](https://github.com/proofit404/blacken).
+### PyCharm
+
+1. Install `black`.
+
+ $ pip install black
+
+2. Locate your `black` installation folder.
+
+ On MacOS / Linux / BSD:
+
+ $ which black
+ /usr/local/bin/black # possible location
+
+ On Windows:
+
+ $ where black
+ %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
+
+3. Open External tools in PyCharm with `File -> Settings -> Tools -> External Tools`.
+
+4. Click the + icon to add a new external tool with the following values:
+ - Name: Black
+ - Description: Black is the uncompromising Python code formatter.
+ - Program: <install_location_from_step_2>
+ - 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`.
+
+
### Vim
Commands and shortcuts:
* `g:black_linelength` (defaults to `88`)
* `g:black_virtualenv` (defaults to `~/.vim/black`)
-To install, copy the plugin from [vim/plugin/black.vim](https://github.com/ambv/black/tree/master/vim/plugin/black.vim).
+To install with [vim-plug](https://github.com/junegunn/vim-plug):
+
+```
+Plug 'ambv/black',
+```
+
+or with [Vundle](https://github.com/VundleVim/Vundle.vim):
+
+```
+Plugin 'ambv/black'
+```
+
+or you can copy the plugin from [plugin/black.vim](https://github.com/ambv/black/tree/master/plugin/black.vim).
Let me know if this requires any changes to work with Vim 8's builtin
-`packadd`, or Pathogen, or Vundle, and so on.
+`packadd`, or Pathogen, and so on.
This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It
needs Python 3.6 to be able to run *Black* inside the Vim process which
Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+### SublimeText 3
+
+Use [sublack plugin](https://github.com/jgirardet/sublack).
### Other editors
This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
+## Version control integration
+
+Use [pre-commit](https://pre-commit.com/). Once you [have it
+installed](https://pre-commit.com/#install), add this to the
+`.pre-commit-config.yaml` in your repository:
+```yaml
+repos:
+- repo: https://github.com/ambv/black
+ rev: stable
+ hooks:
+ - id: black
+ args: [--line-length=88, --safe]
+ python_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
+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
+
+*Black* remembers files it 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
+is:
+
+* Windows: `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.pickle`
+* macOS: `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.pickle`
+* Linux: `/home/<username>/.cache/black/<version>/cache.<line-length>.pickle`
+
+
## Testimonials
**Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
## Change Log
+### 18.4a3 (unreleased)
+
+* added a "cache"; files already reformatted that haven't changed on disk
+ won't be reformatted again (#109)
+
+* `--check` and `--diff` are no longer mutually exclusive (#149)
+
+* generalized star expression handling, including double stars; this
+ fixes multiplication making expressions "unsafe" for trailing commas (#132)
+
+* fixed comment indentation when a standalone comment closes a block (#16, #32)
+
+* fixed standalone comments receiving extra empty lines if immediately preceding
+ a class, def, or decorator (#56, #154)
+
+* fixed `--diff` not showing entire path (#130)
+
+* fixed parsing of complex expressions after star and double stars in
+ function calls (#2)
+
+* fixed invalid splitting on comma in lambda arguments (#133)
+
+### 18.4a2
+
+* fixed parsing of unaligned standalone comments (#99, #112)
+
+* fixed placement of dictionary unpacking inside dictionary literals (#111)
+
+* Vim plugin now works on Windows, too
+
+* fixed unstable formatting when encountering unnecessarily escaped quotes
+ in a string (#120)
+
+
### 18.4a1
* added `--quiet` (#78)
+* added automatic parentheses management (#4)
+
+* added [pre-commit](https://pre-commit.com) integration (#103, #104)
+
+* fixed reporting on `--check` with multiple files (#101, #102)
+
+* fixed removing backslash escapes from raw strings (#100, #105)
+
+
### 18.4a0
* added `--diff` (#87)
Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
-Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com)
-and [Carl Meyer](mailto:carl@oddbird.net).
+Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
+[Carl Meyer](mailto:carl@oddbird.net),
+[Mika Naylor](mailto:mail@autophagy.io), and
+[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com).
Multiple contributions by:
+* [Anthony Sottile](mailto:asottile@umich.edu)
* [Artem Malyshev](mailto:proofit404@gmail.com)
* [Daniel M. Capella](mailto:polycitizen@gmail.com)
* [Eli Treuherz](mailto:eli.treuherz@cgi.com)
* Hugo van Kemenade
-* [Mika Naylor](mailto:mail@autophagy.io)
+* [Ivan Katanić](mailto:ivan.katanic@gmail.com)
+* [Jonas Obrist](mailto:ojiidotch@gmail.com)
* [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
-* [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com)
+* [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
projects / etc / vim.git / blobdiff