X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/10bb45c35e8e08215ad9a060aca33be91a98b864..bc6b912fcbaff08dd0044a844273757c00494305:/README.md?ds=inline diff --git a/README.md b/README.md index ac4caa1..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. ``` @@ -159,7 +164,7 @@ def very_important_function( debug: bool = False, ): """Applies `variables` to the `template` and writes to `file`.""" - with open(file, 'w') as f: + with open(file, "w") as f: ... ``` @@ -260,6 +265,57 @@ if you'd like a trailing comma in this situation and *Black* didn't 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 (`'` +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 @@ -268,6 +324,36 @@ keep it. 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: @@ -328,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): @@ -383,11 +491,41 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log -### 18.3a5 (unreleased) +### 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) + +* 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 + standalone comments at the end of the expression (#22) * 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 + * only allow up to two empty lines on module level and only single empty lines within functions (#74) @@ -489,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⠙](mailto:mail@autophagy.io) +* [Ivan Katanić](mailto:ivan.katanic@gmail.com) * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)