X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/a42aef780630bce97c01dbf33a1947ea108e6e29..cf8e998f46e89da39fa64029cc4550e2862f7ec2:/README.md diff --git a/README.md b/README.md index 205163f..06b7324 100644 --- a/README.md +++ b/README.md @@ -53,13 +53,18 @@ black [OPTIONS] [SRC]... Options: -l, --line-length INTEGER Where to wrap around. [default: 88] - --check Don't write back the files, just return the + --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 there was an internal error. + --diff Don't write the files back, just output a diff + 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. ``` @@ -262,12 +267,54 @@ keep it. ### Strings -*Black* prefers double quotes (`"` and `"""`), but only if this does not -result in more escaping. It will remove escape sequences as necessary as -part of moving to the other type of quote. This applies to all kinds of -prefixed strings, including *raw-strings* (`r""`), *byte literals* (`b""`), -and *formatted strings* (`f""`). The approach above strikes a good balance -between consistency and legibility. +*Black* prefers double quotes (`"` and `"""`) over single quotes (`'` +and `'''`). It will replace the latter with the former as long as it +does not result in more backslash escapes than before. + +The main reason to standardize on a single form of quotes is aesthetics. +Having one kind of quotes everywhere reduces reader distraction. +It will also enable a future version of *Black* to merge consecutive +string literals that ended up on the same line (see +[#26](https://github.com/ambv/black/issues/26) for details). + +Why settle on double quotes? They anticipate apostrophes in English +text. They match the docstring standard described in PEP 257. An +empty string in double quotes (`""`) is impossible to confuse with +a one double-quote regardless of fonts and syntax highlighting used. +On top of this, double quotes for strings are consistent with C which +Python interacts a lot with. + +On certain keyboard layouts like US English, typing single quotes is +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 @@ -277,6 +324,36 @@ between consistency and legibility. 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 +414,28 @@ 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. + ## Testimonials **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips): @@ -392,10 +491,27 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log -### 18.3a5 (unreleased) +### 18.4a1 + +* added `--quiet` (#78) -* add line breaks before all delimiters, except in cases like commas, to better - comply with PEP8 (#73) +* 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) + +* add line breaks before all delimiters, except in cases like commas, to + better comply with PEP 8 (#73) + +* standardize string literals to use double quotes (almost) everywhere + (#75) * fixed handling of standalone comments within nested bracketed expressions; Black will no longer produce super long lines or put all @@ -404,6 +520,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). * fixed 18.3a4 regression: don't crash and burn on empty lines with trailing whitespace (#80) +* fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment + would cause Black to not emit the rest of the file (#95) + * when CTRL+C is pressed while formatting many files, Black no longer freaks out with a flurry of asyncio-related exceptions @@ -508,13 +627,16 @@ 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) * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)