X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/65c52a655fd67480a2017a79c99094039dcaffa3..b07ca2b7d5d03f5d890c1ce5f19b41065ba815c4:/README.md?ds=inline diff --git a/README.md b/README.md index 0a388b0..5be349e 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,9 @@ Options: for each file on stdout. --fast / --safe If --fast given, skip temporary sanity checks. [default: --safe] + -q, --quiet Don't emit non-error messages to stderr. Errors + are still emitted, silence those with + 2>/dev/null. --version Show the version and exit. --help Show this message and exit. ``` @@ -286,6 +289,33 @@ a bit easier than double quotes. The latter requires use of the Shift 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 @@ -294,6 +324,36 @@ and let *Black* handle the transformation. 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: + - 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: @@ -337,6 +397,9 @@ 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). ### Other editors @@ -354,6 +417,42 @@ affect your use case. 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\\AppData\Local\black\black\Cache\\cache.pickle` +* macOS: `/Users//Library/Caches/black//cache.pickle` +* Linux: `/home//.cache/black//cache.pickle` + + ## Testimonials **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips): @@ -409,6 +508,44 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log +### 18.4a3 (unreleased) + +* added a "cache"; files already reformatted that haven't changed on disk + won't be reformatted again (#109) + +* generalized star expression handling, including double stars; this + fixes multiplication making expressions "unsafe" for trailing commas (#132) + +* fixed parsing of complex expressions after star and double stars in + function parameters (#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) @@ -533,14 +670,17 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). 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)