X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/d9c6b9907390ca73130df1d8253481505eb2bce7..728c56c986bc5aea4d9897d3fce3159f89991b8e:/README.md

diff --git a/README.md b/README.md
index 1b83308..ac4caa1 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,16 @@
-# black
+![Black Logo](https://raw.githubusercontent.com/ambv/black/master/docs/_static/logo2-readme.png)
+<h2 align="center">The Uncompromising Code Formatter</h2>
 
-[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black)
+<p align="center">
+<a href="https://travis-ci.org/ambv/black"><img alt="Build Status" src="https://travis-ci.org/ambv/black.svg?branch=master"></a>
+<a href="http://black.readthedocs.io/en/latest/?badge=latest"><img alt="Documentation Status" src="http://readthedocs.org/projects/black/badge/?version=latest"></a>
+<a href="https://coveralls.io/github/ambv/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/ambv/black/badge.svg?branch=master"></a>
+<a href="https://github.com/ambv/black/blob/master/LICENSE"><img alt="License: MIT" src="http://black.readthedocs.io/en/latest/_static/license.svg"></a>
+<a href="https://pypi.python.org/pypi/black"><img alt="PyPI" src="http://black.readthedocs.io/en/latest/_static/pypi.svg"></a>
+<a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+</p>
 
-> Any color you like.
+> “Any color you like.”
 
 
 *Black* is the uncompromising Python code formatter.  By using it, you
@@ -19,43 +27,68 @@ content instead.
 possible.
 
 
-## NOTE: This is an early pre-release
+## Installation and Usage
 
-*Black* can already successfully format itself and the standard library.
-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.
-What this means for you is that **until the formatter becomes stable,
-you should expect some formatting to change in the future**.
+### Installation
 
-Also, as a temporary safety measure, *Black* will check that the
-reformatted code still produces a valid AST that is equivalent to the
-original.  This slows it down.  If you're feeling confident, use
-``--fast``.
+*Black* can be installed by running `pip install black`.  It requires
+Python 3.6.0+ to run but you can reformat Python 2 code with it, too.
 
 
-## Usage
+### Usage
 
-*Black* can be installed by running `pip install black`.
+To get started right away with sensible defaults:
 
 ```
+black {source_file_or_directory}
+```
+
+### Command line options
+
+Black doesn't provide many options.  You can list them by running
+`black --help`:
+
+```text
 black [OPTIONS] [SRC]...
 
 Options:
   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
   --check                     Don't write back the files, just return the
-                              status.  Return code 0 means nothing changed.
-                              Return code 1 means some files were reformatted.
-                              Return code 123 means there was an internal
-                              error.
+                              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.
   --fast / --safe             If --fast given, skip temporary sanity checks.
                               [default: --safe]
   --version                   Show the version and exit.
   --help                      Show this message and exit.
 ```
 
+*Black* is a well-behaved Unix-style command-line tool:
+* it does nothing if no sources are passed to it;
+* 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
+  used).
 
-## The philosophy behind *Black*
+
+### NOTE: This is an early pre-release
+
+*Black* can already successfully format itself and the standard library.
+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.
+What this means for you is that **until the formatter becomes stable,
+you should expect some formatting to change in the future**.
+
+Also, as a temporary safety measure, *Black* will check that the
+reformatted code still produces a valid AST that is equivalent to the
+original.  This slows it down.  If you're feeling confident, use
+``--fast``.
+
+
+## The *Black* code style
 
 *Black* reformats entire files in place.  It is not configurable.  It
 doesn't take previous formatting into account.  It doesn't reformat
@@ -64,24 +97,27 @@ recognizes [YAPF](https://github.com/google/yapf)'s block comments to
 the same effect, as a courtesy for straddling code.
 
 
-### How *Black* formats files
+### How *Black* wraps lines
 
 *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.
+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,
 great.
 ```py3
 # in:
+
 l = [1,
      2,
      3,
 ]
 
 # out:
+
 l = [1, 2, 3]
 ```
 
@@ -89,9 +125,11 @@ If not, *Black* will look at the contents of the first outer matching
 brackets and put that in a separate indented line.
 ```py3
 # in:
+
 l = [[n for n in list_bosses()], [n for n in list_employees()]]
 
 # out:
+
 l = [
     [n for n in list_bosses()], [n for n in list_employees()]
 ]
@@ -106,12 +144,14 @@ matching brackets.  If that doesn't work, it will put all of them in
 separate lines.
 ```py3
 # in:
+
 def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):
     """Applies `variables` to the `template` and writes to `file`."""
     with open(file, 'w') as f:
         ...
 
 # out:
+
 def very_important_function(
     template: str,
     *variables,
@@ -131,20 +171,6 @@ 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).
 
-Unnecessary trailing commas are removed if an expression fits in one
-line.  This makes it 1% more likely that your line won't exceed the
-allotted line length limit.
-
-*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.
-
-That's it.  The rest of the whitespace formatting rules follow PEP 8 and
-are designed to keep `pycodestyle` quiet.
-
 
 ### Line length
 
@@ -183,14 +209,124 @@ explains it.  The tl;dr is "it's like highway speed limits, we won't
 bother you if you overdo it by a few km/h".
 
 
-### Editor integration
+### Empty lines
+
+*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.
 
-There is currently no integration with any text editors. Vim and
-Atom/Nuclide integration is planned by the author, others will require
-external contributions.
+*Black* will allow single empty lines inside functions, and single and
+double empty lines on module level left by the original editors, except
+when they're within parenthesized expressions.  Since such expressions
+are always reformatted to fit minimal space, this whitespace is lost.
+
+It will also insert proper spacing before and after function definitions.
+It's one line before and after inner functions and two lines before and
+after module-level functions.  *Black* will put those empty lines also
+between the function definition and any standalone comments that
+immediately precede the given function.  If you want to comment on the
+entire function, use a docstring or put a leading comment in the function
+body.
+
+
+### Trailing commas
+
+*Black* will add trailing commas to expressions that are split
+by comma where each element is on its own line.  This includes function
+signatures.
+
+Unnecessary trailing commas are removed if an expression fits in one
+line.  This makes it 1% more likely that your line won't exceed the
+allotted line length limit.  Moreover, in this scenario, if you added
+another argument to your call, you'd probably fit it in the same line
+anyway.  That doesn't make diffs any larger.
+
+One exception to removing trailing commas is tuple expressions with
+just one element.  In this case *Black* won't touch the single trailing
+comma as this would unexpectedly change the underlying data type.  Note
+that this is also the case when commas are used while indexing.  This is
+a tuple in disguise: ```numpy_array[3, ]```.
+
+One exception to adding trailing commas is function signatures
+containing `*`, `*args`, or `**kwargs`.  In this case a trailing comma
+is only safe to use on Python 3.6.  *Black* will detect if your file is
+already 3.6+ only and use trailing commas in this situation.  If you
+wonder how it knows, it looks for f-strings and existing use of trailing
+commas in function signatures that have stars in them.  In other words,
+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.
+
+
+## Editor integration
+
+### 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)).
+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.
+
+This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
+
 
 ## Testimonials
 
@@ -213,25 +349,15 @@ and [`pipenv`](https://docs.pipenv.org/):
 > This vastly improves the formatting of our code. Thanks a ton!
 
 
-## Tests
+## Show your style
 
-Just run:
+Use the badge in your project's README.md:
 
+```markdown
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 ```
-python setup.py test
-```
-
-## This tool requires Python 3.6.0+ to run
 
-But you can reformat Python 2 code with it, too.  *Black* is able to parse
-all of the new syntax supported on Python 3.6 but also *effectively all*
-the Python 2 syntax at the same time, as long as you're not using print
-statements.
-
-By making the code exclusively Python 3.6+, I'm able to focus on the
-quality of the formatting and re-use all the nice features of the new
-releases (check out [pathlib](https://docs.python.org/3/library/pathlib.html) or
-f-strings) instead of wasting cycles on Unicode compatibility, and so on.
+Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 
 ## License
@@ -239,7 +365,7 @@ f-strings) instead of wasting cycles on Unicode compatibility, and so on.
 MIT
 
 
-## Contributing
+## Contributing to Black
 
 In terms of inspiration, *Black* is about as configurable as *gofmt* and
 *rustfmt* are.  This is deliberate.
@@ -257,13 +383,51 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
+### 18.3a5 (unreleased)
+
+* fixed 18.3a4 regression: don't crash and burn on empty lines with
+  trailing whitespace (#80)
+
+* only allow up to two empty lines on module level and only single empty
+  lines within functions (#74)
+
+
+### 18.3a4
+
+* `# fmt: off` and `# fmt: on` are implemented (#5)
+
+* automatic detection of deprecated Python 2 forms of print statements
+  and exec statements in the formatted file (#49)
+
+* use proper spaces for complex expressions in default values of typed
+  function arguments (#60)
+
+* only return exit code 1 when --check is used (#50)
+
+* don't remove single trailing commas from square bracket indexing
+  (#59)
+
+* don't omit whitespace if the previous factor leaf wasn't a math
+  operator (#55)
+
+* omit extra space in kwarg unpacking if it's the first argument (#46)
+
+* omit extra space in [Sphinx auto-attribute comments](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute)
+  (#68)
+
+
 ### 18.3a3
 
+* don't remove single empty lines outside of bracketed expressions
+  (#19)
+
 * added ability to pipe formatting from stdin to stdin (#25)
 
 * restored ability to format code with legacy usage of `async` as
   a name (#20, #42)
 
+* even better handling of numpy-style array indexing (#33, again)
+
 
 ### 18.3a2
 
@@ -324,3 +488,14 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 ## Authors
 
 Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
+
+Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com)
+and [Carl Meyer](mailto:carl@oddbird.net).
+
+Multiple contributions by:
+* [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)
+* [Osaetin Daniel](mailto:osaetindaniel@gmail.com)