X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/e5f8251704c22b143b79474905c6c4b7e10ddb47..4787294622f9053525fb2373db207dd4a35520dc:/README.md diff --git a/README.md b/README.md index 182e264..ff2c917 100644 --- a/README.md +++ b/README.md @@ -53,11 +53,13 @@ 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] --version Show the version and exit. @@ -159,7 +161,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,11 +262,88 @@ 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. + ## Editor integration -* Visual Studio Code: [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode) -* Emacs: [proofit404/blacken](https://github.com/proofit404/blacken) +### Emacs + +Use [proofit404/blacken](https://github.com/proofit404/blacken). + + +### Vim + +Commands and shortcuts: + +* `,=` or `:Black` to format the entire file (ranges not supported); +* `:BlackUpgrade` to upgrade *Black* inside the virtualenv; +* `:BlackVersion` to get the current version of *Black* inside the + virtualenv. + +Configuration: +* `g:black_fast` (defaults to `0`) +* `g:black_linelength` (defaults to `88`) +* `g:black_virtualenv` (defaults to `~/.vim/black`) + +To install, copy the plugin from [vim/plugin/black.vim](https://github.com/ambv/black/tree/master/vim/plugin/black.vim). +Let me know if this requires any changes to work with Vim 8's builtin +`packadd`, or Pathogen, or Vundle, and so on. + +This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It +needs Python 3.6 to be able to run *Black* inside the Vim process which +is much faster than calling an external command. + +On first run, the plugin creates its own virtualenv using the right +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 +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`. +When building Vim from source, use: +`./configure --enable-python3interp=yes`. There's many guides online how +to do this. + + +### Visual Studio Code + +Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode). + + +### Other editors + +Atom/Nuclide integration is planned by the author, others will +require external contributions. + +Patches welcome! ✨ 🍰 ✨ Any tool that can pipe code through *Black* using its stdio mode (just [use `-` as the file name](http://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)). @@ -272,10 +351,7 @@ The formatted code will be returned on stdout (unless `--check` was passed). *Black* will still emit messages on stderr but that shouldn't affect your use case. -Vim and Atom/Nuclide integration is planned by the author, others will -require external contributions. - -Patches welcome! ✨ 🍰 ✨ +This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html). ## Testimonials @@ -335,9 +411,24 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ### 18.3a5 (unreleased) +* 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) +* 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) @@ -447,5 +538,5 @@ Multiple contributions by: * [Daniel M. Capella](mailto:polycitizen@gmail.com) * [Eli Treuherz](mailto:eli.treuherz@cgi.com) * Hugo van Kemenade -* [Mika⠙](mailto:mail@autophagy.io) +* [Mika Naylor](mailto:mail@autophagy.io) * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)