X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/7395f55564a689a28db5ab3f82c079f7fc40eadf..fd9bd07fe551c88f0c1e2d6f411f48b73f3083fc:/README.md diff --git a/README.md b/README.md index 57f3ac2..a6d7de8 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. ``` @@ -301,7 +323,7 @@ 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 @@ -365,7 +387,7 @@ decision = (maybe.this() and values > 0) or (maybe.that() and values < 0) 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 @@ -431,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`. @@ -500,9 +528,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. @@ -562,9 +596,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 @@ -630,6 +664,28 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log +### 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 @@ -891,3 +947,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)**