X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/52fda8b0e9e52e94aae6cb3170c9b1b492a2d8b4..e9a940d69e789ce8caf1f3c1ded786dc102df2fd:/README.md?ds=inline diff --git a/README.md b/README.md index e2f91ef..8212e42 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,10 @@

Build Status -Documentation Status +Documentation Status Coverage Status -License: MIT -PyPI +License: MIT +PyPI Code style: black

@@ -14,7 +14,7 @@ *Black* is the uncompromising Python code formatter. By using it, you -agree to cease control over minutiae of hand-formatting. In return, +agree to cede control over minutiae of hand-formatting. In return, *Black* gives you speed, determinism, and freedom from `pycodestyle` nagging about formatting. You will save time and mental energy for more important matters. @@ -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. ``` @@ -74,18 +96,20 @@ Options: * it will read from standard input and write to standard output if `-` is used as the filename; * it only outputs messages to users on standard error; -* exits with code 0 unless an internal error occured (or `--check` was +* exits with code 0 unless an internal error occurred (or `--check` was 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 @@ -106,9 +130,9 @@ the same effect, as a courtesy for straddling code. *Black* ignores previous formatting and applies uniform horizontal and vertical whitespace to your code. The rules for horizontal -whitespace are pretty obvious and can be summarized as: do whatever -makes `pycodestyle` happy. The coding style used by *Black* can be -viewed as a strict subset of PEP 8. +whitespace can be summarized as: do whatever makes `pycodestyle` happy. +The coding style used by *Black* can be viewed as a strict subset of +PEP 8. As for vertical whitespace, *Black* tries to render one full expression or simple statement per line. If this fits the allotted line length, @@ -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,6 +200,14 @@ 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 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/). Use +`multi_line_output=3`, `include_trailing_comma=True`, +`force_grid_wrap=0`, and `line_length=88` in your isort config. + ### Line length @@ -218,10 +250,7 @@ bother you if you overdo it by a few km/h". *Black* avoids spurious vertical whitespace. This is in the spirit of PEP 8 which says that in-function vertical whitespace should only be -used sparingly. One exception is control flow statements: *Black* will -always emit an extra empty line after ``return``, ``raise``, ``break``, -``continue``, and ``yield``. This is to make changes in control flow -more prominent to readers of your code. +used sparingly. *Black* will allow single empty lines inside functions, and single and double empty lines on module level left by the original editors, except @@ -263,12 +292,18 @@ 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. +*Black* also standardizes string prefixes, making them always lowercase. +On top of that, if your code is already Python 3.6+ only or it's using +the `unicode_literals` future import, *Black* will remove `u` from the +string prefix as it is meaningless in those scenarios. + 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 @@ -287,7 +322,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 @@ -298,6 +334,21 @@ 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) +to treat ``:`` in slices as a binary operator with the lowest priority, and to +leave an equal amount of space on either side, except if a parameter is omitted +(e.g. ``ham[1 + 1 :]``). It also states that for extended slices, both ``:`` +operators have to have the same amount of spacing, except if a parameter is +omitted (``ham[1 + 1 ::]``). *Black* enforces these rules consistently. + +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 @@ -309,10 +360,86 @@ interesting cases: - `for (...) in (...):` - `assert (...), (...)` - `from X import (...)` +- assignments like: + - `target = (...)` + - `target: type = (...)` + - `some, *un, packing = (...)` + - `augmented += (...)` 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. +further split on. If there is only a single delimiter and the expression +starts or ends with a bracket, the parenthesis can also be successfully +omitted since the existing bracket pair will organize the expression +neatly anyway. Otherwise, the parentheses are added. + +Please note that *Black* does not add or remove any additional nested +parentheses that you might want to have for clarity or further +code organization. For example those parentheses are not going to be +removed: +```py3 +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 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 +def example(session): + result = ( + session.query(models.Customer.id) + .filter( + models.Customer.account_id == account_id, + models.Customer.email == email_address, + ) + .order_by(models.Customer.id.asc()) + .all() + ) +``` + + +### Typing stub files + +PEP 484 describes the syntax for type hints in Python. One of the +use cases for typing is providing type annotations for modules which +cannot contain them directly (they might be written in C, or they might +be third-party, or their implementation may be overly dynamic, and so on). + +To solve this, [stub files with the `.pyi` file +extension](https://www.python.org/dev/peps/pep-0484/#stub-files) can be +used to describe typing information for an external module. Those stub +files omit the implementation of classes and functions they +describe, instead they only contain the structure of the file (listing +globals, functions, and classes with their members). The recommended +code style for those files is more terse than PEP 8: + +* prefer `...` on the same line as the class/function signature; +* avoid vertical whitespace between consecutive module-level functions, + names, or methods and fields within a single class; +* use a single blank line between top-level class definitions, or none + if the classes are very small. + +*Black* enforces the above rules. There are additional guidelines for +formatting `.pyi` file that are not enforced yet but might be in +a future version of the formatter: + +* all function bodies should be empty (contain `...` instead of the body); +* do not use docstrings; +* prefer `...` over `pass`; +* for arguments with a default, use `...` instead of the actual default; +* avoid using string literals in type annotations, stub files support + forward references natively (like Python 3.7 code with `from __future__ + import annotations`); +* use variable annotations instead of type comments, even for stubs that + target older versions of Python; +* for arguments that default to `None`, use `Optional[]` explicitly; +* use `float` instead of `Union[int, float]`. ## Editor integration @@ -326,19 +453,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`. @@ -391,13 +524,13 @@ Python version and automatically installs *Black*. You can upgrade it later by calling `:BlackUpgrade` and restarting Vim. If you need to do anything special to make your virtualenv work and -install *Black* (for example you want to run a version from master), just +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. **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. @@ -407,10 +540,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 @@ -450,17 +590,17 @@ 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 is: -* Windows: `C:\\Users\\AppData\Local\black\black\Cache\\cache.pickle` -* macOS: `/Users//Library/Caches/black//cache.pickle` -* Linux: `/home//.cache/black//cache.pickle` +* Windows: `C:\\Users\\AppData\Local\black\black\Cache\\cache..pickle` +* macOS: `/Users//Library/Caches/black//cache..pickle` +* Linux: `/home//.cache/black//cache..pickle` ## Testimonials @@ -502,8 +642,8 @@ MIT ## Contributing to Black -In terms of inspiration, *Black* is about as configurable as *gofmt* and -*rustfmt* are. This is deliberate. +In terms of inspiration, *Black* is about as configurable as *gofmt*. +This is deliberate. Bug reports and fixes are always welcome! However, before you suggest a new feature or configuration knob, ask yourself why you want it. If it @@ -518,7 +658,92 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log -### 18.4a3 (unreleased) +### 18.5b1 (unreleased) + +* added `--pyi` (#249) + +* added `--py36` (#249) + +* 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) + +* parentheses are now also managed automatically on the right-hand side + of assignments and return statements (#140) + +* math operators now use their respective priorities for delimiting multiline + expressions (#148) + +* optional parentheses are now omitted on expressions that start or end + with a bracket and only contain a single operator (#177) + +* empty parentheses in a class definition are now removed (#145, #180) + +* string prefixes are now standardized to lowercase and `u` is removed + on Python 3.6+ only code and Python 2.7+ code with the `unicode_literals` + future import (#188, #198, #199) + +* typing stub files (`.pyi`) are now formatted in a style that is consistent + with PEP 484 (#207, #210) + +* progress when reformatting many files is now reported incrementally + +* fixed trailers (content with brackets) being unnecessarily exploded + into their own lines after a dedented closing bracket (#119) + +* fixed an invalid trailing comma sometimes left in imports (#185) + +* fixed non-deterministic formatting when multiple pairs of removable parentheses + were used (#183) + +* fixed multiline strings being unnecessarily wrapped in optional + parentheses in long assignments (#215) + +* fixed not splitting long from-imports with only a single name + +* fixed Python 3.6+ file discovery by also looking at function calls with + unpacking. This fixed non-deterministic formatting if trailing commas + where used both in function signatures with stars and function calls + with stars but the former would be reformatted to a single line. + +* fixed crash on dealing with optional parentheses (#193) + +* fixed "is", "is not", "in", and "not in" not considered operators for + splitting purposes + +* fixed crash when dead symlinks where encountered + + +### 18.4a4 + +* don't populate the cache on `--check` (#175) + + +### 18.4a3 * added a "cache"; files already reformatted that haven't changed on disk won't be reformatted again (#109) @@ -528,6 +753,11 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). * generalized star expression handling, including double stars; this fixes multiplication making expressions "unsafe" for trailing commas (#132) +* Black no longer enforces putting empty lines behind control flow statements + (#90) + +* Black now splits imports like "Mode 3 + trailing comma" of isort (#127) + * fixed comment indentation when a standalone comment closes a block (#16, #32) * fixed standalone comments receiving extra empty lines if immediately preceding @@ -540,6 +770,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). * fixed invalid splitting on comma in lambda arguments (#133) +* fixed missing splits of ternary expressions (#141) + + ### 18.4a2 * fixed parsing of unaligned standalone comments (#99, #112) @@ -697,10 +930,29 @@ Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com), Multiple contributions by: * [Anthony Sottile](mailto:asottile@umich.edu) * [Artem Malyshev](mailto:proofit404@gmail.com) +* [Christian Heimes](mailto:christian@python.org) * [Daniel M. Capella](mailto:polycitizen@gmail.com) * [Eli Treuherz](mailto:eli.treuherz@cgi.com) * Hugo van Kemenade * [Ivan Katanić](mailto:ivan.katanic@gmail.com) +* [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com) * [Jonas Obrist](mailto:ojiidotch@gmail.com) +* [Miguel Gaiowski](mailto:miggaiowski@gmail.com) * [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)**