X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/e94bda11c366818d24f864ae03abf076e8f5a297..e818260f1a223929d8f2056f484b73eaa8687622:/README.md diff --git a/README.md b/README.md index e192826..41ad465 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,23 @@ content instead. *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 @@ -65,6 +80,13 @@ Options: -q, --quiet Don't emit non-error messages to stderr. Errors are still emitted, silence those with 2>/dev/null. + --pyi Consider all input files typing stubs regardless + of file extension (useful when piping source on + standard input). + --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] --version Show the version and exit. --help Show this message and exit. ``` @@ -78,14 +100,16 @@ Options: 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 @@ -131,13 +155,13 @@ brackets and put that in a separate indented line. ```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 @@ -176,14 +200,30 @@ between two distinct sections of the code that otherwise share the same 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. +
+A compatible `.isort.cfg` + +``` +[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 ] +``` +
### Line length @@ -268,6 +308,7 @@ 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 (`'` @@ -297,7 +338,8 @@ 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 + +### 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 @@ -308,6 +350,7 @@ 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. + ### Slices PEP 8 [recommends](https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements) @@ -321,6 +364,7 @@ This behaviour may raise ``E203 whitespace before ':'`` warnings in style guide 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 @@ -354,11 +398,12 @@ return not (this or that) 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 @@ -374,6 +419,7 @@ def example(session): ) ``` + ### Typing stub files PEP 484 describes the syntax for type hints in Python. One of the @@ -423,19 +469,25 @@ Use [proofit404/blacken](https://github.com/proofit404/blacken). 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`. @@ -492,9 +544,15 @@ install *Black* (for example you want to run a version from master), 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. @@ -504,14 +562,17 @@ 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 @@ -551,9 +612,9 @@ 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 @@ -619,9 +680,37 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log -### 18.5a0 (unreleased) +### 18.5b1 (unreleased) + +* added `--pyi` (#249) + +* added `--py36` (#249) -* call chains are now formatted according to the [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67) +* Python grammar pickle caches are stored with the formatting caches, making + *Black* work in environments where site-packages is not user-writable (#192) + +* 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) + + +### 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) @@ -874,3 +963,18 @@ Multiple contributions by: * [Osaetin Daniel](mailto:osaetindaniel@gmail.com) * [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)**