]> git.madduck.net Git - etc/vim.git/blobdiff - README.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Add .eggs to default exclusions (#629)
[etc/vim.git] / README.md
index cf9db966016b785e796522787d90d4f07f6bb9b2..7be809371ede219d5d093e408913e75228801287 100644 (file)
--- a/README.md
+++ b/README.md
@@ -6,7 +6,8 @@
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></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="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></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="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
-<a href="https://pypi.python.org/pypi/black"><img alt="PyPI" src="https://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
+<a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
+<a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></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>
 
 <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>
 
@@ -26,16 +27,19 @@ content instead.
 *Black* makes code review faster by producing the smallest diffs
 possible.
 
 *Black* makes code review faster by producing the smallest diffs
 possible.
 
+Try it out now using the [Black Playground](https://black.now.sh).
+
 ---
 
 *Contents:* **[Installation and usage](#installation-and-usage)** |
 ---
 
 *Contents:* **[Installation and usage](#installation-and-usage)** |
-**[The *Black* code style](#the-black-code-style)** |
+**[Code style](#the-black-code-style)** |
+**[pyproject.toml](#pyprojecttoml)** |
 **[Editor integration](#editor-integration)** |
 **[Editor integration](#editor-integration)** |
+**[blackd](#blackd)** |
 **[Version control integration](#version-control-integration)** |
 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
 **[Testimonials](#testimonials)** |
 **[Show your style](#show-your-style)** |
 **[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)**
 **[Contributing](#contributing-to-black)** |
 **[Change Log](#change-log)** |
 **[Authors](#authors)**
@@ -77,6 +81,8 @@ Options:
                               source on standard input).
   -S, --skip-string-normalization
                               Don't normalize string quotes or prefixes.
                               source on standard input).
   -S, --skip-string-normalization
                               Don't normalize string quotes or prefixes.
+  -N, --skip-numeric-underscore-normalization
+                              Don't normalize underscores in numeric literals.
   --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
   --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
@@ -94,8 +100,8 @@ Options:
                               directories that should be excluded on
                               recursive searches. On Windows, use forward
                               slashes for directories.  [default:
                               directories that should be excluded on
                               recursive searches. On Windows, use forward
                               slashes for directories.  [default:
-                              build/|buck-out/|dist/|_build/|\.git/|\.hg/|
-                              \.mypy_cache/|\.tox/|\.venv/]
+                              build/|buck-out/|dist/|_build/|\.eggs/|\.git/|
+                              \.hg/|\.mypy_cache/|\.nox/|\.tox/|\.venv/]
   -q, --quiet                 Don't emit non-error messages to stderr. Errors
                               are still emitted, silence those with
                               2>/dev/null.
   -q, --quiet                 Don't emit non-error messages to stderr. Errors
                               are still emitted, silence those with
                               2>/dev/null.
@@ -103,6 +109,7 @@ Options:
                               that were not changed or were ignored due to
                               --exclude=.
   --version                   Show the version and exit.
                               that were not changed or were ignored due to
                               --exclude=.
   --version                   Show the version and exit.
+  --config PATH               Read configuration from PATH.
   --help                      Show this message and exit.
 ```
 
   --help                      Show this message and exit.
 ```
 
@@ -136,7 +143,8 @@ original.  This slows it down.  If you're feeling confident, use
 
 *Black* reformats entire files in place.  It is not configurable.  It
 doesn't take previous formatting into account.  It doesn't reformat
 
 *Black* reformats entire files in place.  It is not configurable.  It
 doesn't take previous formatting into account.  It doesn't reformat
-blocks that start with `# fmt: off` and end with `# fmt: on`.  It also
+blocks that start with `# fmt: off` and end with `# fmt: on`. `# fmt: on/off`
+have to be on the same level of indentation. It also
 recognizes [YAPF](https://github.com/google/yapf)'s block comments to
 the same effect, as a courtesy for straddling code.
 
 recognizes [YAPF](https://github.com/google/yapf)'s block comments to
 the same effect, as a courtesy for straddling code.
 
@@ -230,13 +238,13 @@ the following configuration.
 multi_line_output=3
 include_trailing_comma=True
 force_grid_wrap=0
 multi_line_output=3
 include_trailing_comma=True
 force_grid_wrap=0
-combine_as_imports=True
+use_parentheses=True
 line_length=88
 ```
 
 The equivalent command line is:
 ```
 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 ]
+$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --use-parentheses --line-width=88 [ file.py ]
 ```
 </details>
 
 ```
 </details>
 
@@ -272,7 +280,8 @@ ignore = E501
 ```
 
 You'll find *Black*'s own .flake8 config file is configured like this.
 ```
 
 You'll find *Black*'s own .flake8 config file is configured like this.
-If you're curious about the reasoning behind B950, Bugbear's documentation
+If you're curious about the reasoning behind B950, 
+[Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
 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".
 
 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".
 
@@ -350,8 +359,8 @@ 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
 [#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
+text.  They match the docstring standard described in [PEP 257](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring).
+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.
 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.
@@ -367,6 +376,19 @@ human-readable strings"](https://stackoverflow.com/a/56190)), you can
 pass `--skip-string-normalization` on the command line.  This is meant as
 an adoption helper, avoid using this for new projects.
 
 pass `--skip-string-normalization` on the command line.  This is meant as
 an adoption helper, avoid using this for new projects.
 
+### Numeric literals
+
+*Black* standardizes most numeric literals to use lowercase letters for the
+syntactic parts and uppercase letters for the digits themselves: `0xAB`
+instead of `0XAB` and `1e10` instead of `1E10`. Python 2 long literals are
+styled as `2L` instead of `2l` to avoid confusion between `l` and `1`. In
+Python 3.6+, *Black* adds underscores to long numeric literals to aid
+readability: `100000000` becomes `100_000_000`.
+
+For regions where numerals are grouped differently (like [India](https://en.wikipedia.org/wiki/Indian_numbering_system)
+and [China](https://en.wikipedia.org/wiki/Chinese_numerals#Whole_numbers)),
+the `-N` or `--skip-numeric-underscore-normalization` command line option
+makes *Black* preserve underscores in numeric literals.
 
 ### Line breaks & binary operators
 
 
 ### Line breaks & binary operators
 
@@ -487,6 +509,101 @@ a future version of the formatter:
 * use `float` instead of `Union[int, float]`.
 
 
 * use `float` instead of `Union[int, float]`.
 
 
+## pyproject.toml
+
+*Black* is able to read project-specific default values for its
+command line options from a `pyproject.toml` file.  This is
+especially useful for specifying custom `--include` and `--exclude`
+patterns for your project.
+
+**Pro-tip**: If you're asking yourself "Do I need to configure anything?"
+the answer is "No".  *Black* is all about sensible defaults.
+
+
+### What on Earth is a `pyproject.toml` file?
+
+[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines
+`pyproject.toml` as a configuration file to store build system
+requirements for Python projects.  With the help of tools
+like [Poetry](https://poetry.eustace.io/) or
+[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the
+need for `setup.py` and `setup.cfg` files.
+
+
+### Where *Black* looks for the file
+
+By default *Black* looks for `pyproject.toml` starting from the common
+base directory of all files and directories passed on the command line.
+If it's not there, it looks in parent directories.  It stops looking
+when it finds the file, or a `.git` directory, or a `.hg` directory,
+or the root of the file system, whichever comes first.
+
+If you're formatting standard input, *Black* will look for configuration
+starting from the current working directory.
+
+You can also explicitly specify the path to a particular file that you
+want with `--config`.  In this situation *Black* will not look for any
+other file.
+
+If you're running with `--verbose`, you will see a blue message if
+a file was found and used.
+
+Please note `blackd` will not use `pyproject.toml` configuration.
+
+
+### Configuration format
+
+As the file extension suggests, `pyproject.toml` is a [TOML](https://github.com/toml-lang/toml) file.  It contains separate
+sections for different tools.  *Black* is using the `[tool.black]`
+section.  The option keys are the same as long names of options on
+the command line.
+
+Note that you have to use single-quoted strings in TOML for regular
+expressions. It's the equivalent of r-strings in Python.  Multiline
+strings are treated as verbose regular expressions by Black.  Use `[ ]`
+to denote a significant space character.
+
+<details>
+<summary>Example `pyproject.toml`</summary>
+
+```toml
+[tool.black]
+line-length = 88
+py36 = true
+include = '\.pyi?$'
+exclude = '''
+/(
+    \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+
+  # The following are specific to Black, you probably don't want those.
+  | blib2to3
+  | tests/data
+)/
+'''
+```
+
+</details>
+
+### Lookup hierarchy
+
+Command-line options have defaults that you can see in `--help`.
+A `pyproject.toml` can override those defaults.  Finally, options
+provided by the user on the command line override both.
+
+*Black* will only ever use one `pyproject.toml` file during an entire
+run. It doesn't look for multiple files, and doesn't compose
+configuration from different levels of the file hierarchy.
+
+
 ## Editor integration
 
 ### Emacs
 ## Editor integration
 
 ### Emacs
@@ -524,17 +641,28 @@ $ where black
     - Name: Black
     - Description: Black is the uncompromising Python code formatter.
     - Program: <install_location_from_step_2>
     - Name: Black
     - Description: Black is the uncompromising Python code formatter.
     - Program: <install_location_from_step_2>
-    - Arguments: $FilePath$
+    - Arguments: `$FilePath$`
 
 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
     - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap -> External Tools -> External Tools - Black`.
 
 
 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
     - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap -> External Tools -> External Tools - Black`.
 
+6. Optionally, run Black on every file save:
+
+    1. Make sure you have the [File Watcher](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin installed.
+    2. Go to `Preferences -> Tools -> File Watchers` and click `+` to add a new watcher:
+        - Name: Black
+        - File type: Python
+        - Scope: Project Files
+        - Program: <install_location_from_step_2>
+        - Arguments: `$FilePath$`
+        - Output paths to refresh: `$FilePathRelativeToProjectRoot$`
+        - Working directory: `$ProjectFileDir$`
 
 ### Vim
 
 Commands and shortcuts:
 
 
 ### Vim
 
 Commands and shortcuts:
 
-* `,=` or `:Black` to format the entire file (ranges not supported);
+* `: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.
 * `:BlackUpgrade` to upgrade *Black* inside the virtualenv;
 * `:BlackVersion` to get the current version of *Black* inside the
   virtualenv.
@@ -542,12 +670,13 @@ Commands and shortcuts:
 Configuration:
 * `g:black_fast` (defaults to `0`)
 * `g:black_linelength` (defaults to `88`)
 Configuration:
 * `g:black_fast` (defaults to `0`)
 * `g:black_linelength` (defaults to `88`)
+* `g:black_skip_string_normalization` (defaults to `0`)
 * `g:black_virtualenv` (defaults to `~/.vim/black`)
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 ```
 * `g:black_virtualenv` (defaults to `~/.vim/black`)
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 ```
-Plug 'ambv/black',
+Plug 'ambv/black'
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
@@ -576,7 +705,7 @@ The plugin will use it.
 To run *Black* on save, add the following line to `.vimrc` or `init.vim`:
 
 ```
 To run *Black* on save, add the following line to `.vimrc` or `init.vim`:
 
 ```
-autocmd BufWritePost *.py execute ':Black'
+autocmd BufWritePre *.py execute ':Black'
 ```
 
 **How to get Vim with Python 3.6?**
 ```
 
 **How to get Vim with Python 3.6?**
@@ -590,8 +719,7 @@ to do this.
 ### Visual Studio Code
 
 Use the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
 ### Visual Studio Code
 
 Use the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-([instructions](https://code.visualstudio.com/docs/python/editing#_formatting))
-or [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
 
 
 ### SublimeText 3
 
 
 ### SublimeText 3
@@ -599,15 +727,27 @@ or [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 
-### IPython Notebook Magic
+### Jupyter Notebook Magic
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
 
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
 
+### Python Language Server
+
+If your editor supports the [Language Server Protocol](https://langserver.org/)
+(Atom, Sublime Text, Visual Studio Code and many more), you can use
+the [Python Language Server](https://github.com/palantir/python-language-server) with the
+[pyls-black](https://github.com/rupert/pyls-black) plugin.
+
+
+### Atom/Nuclide
+
+Use [python-black](https://atom.io/packages/python-black).
+
+
 ### Other editors
 
 ### Other editors
 
-Atom/Nuclide integration is planned by the author, others will
-require external contributions.
+Other editors will require external contributions.
 
 Patches welcome! ✨ 🍰 ✨
 
 
 Patches welcome! ✨ 🍰 ✨
 
@@ -619,6 +759,78 @@ affect your use case.
 
 This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
 
 
 This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
 
+## blackd
+
+`blackd` is a small HTTP server that exposes *Black*'s functionality over
+a simple protocol. The main benefit of using it is to avoid paying the
+cost of starting up a new *Black* process every time you want to blacken
+a file.
+
+### Usage
+
+`blackd` is not packaged alongside *Black* by default because it has additional
+dependencies. You will need to do `pip install black[d]` to install it.
+
+You can start the server on the default port, binding only to the local interface
+by running `blackd`. You will see a single line mentioning the server's version,
+and the host and port it's listening on. `blackd` will then print an access log
+similar to most web servers on standard output, merged with any exception traces
+caused by invalid formatting requests.
+
+`blackd` provides even less options than *Black*. You can see them by running
+`blackd --help`:
+
+```text
+Usage: blackd [OPTIONS]
+
+Options:
+  --bind-host TEXT                Address to bind the server to.
+  --bind-port INTEGER             Port to listen on
+  --version                       Show the version and exit.
+  -h, --help                      Show this message and exit.
+```
+
+### Protocol
+
+`blackd` only accepts `POST` requests at the `/` path. The body of the request
+should contain the python source code to be formatted, encoded
+according to the `charset` field in the `Content-Type` request header. If no
+`charset` is specified, `blackd` assumes `UTF-8`.
+
+There are a few HTTP headers that control how the source is formatted. These
+correspond to command line flags for *Black*. There is one exception to this:
+`X-Protocol-Version` which if present, should have the value `1`, otherwise the
+request is rejected with `HTTP 501` (Not Implemented).
+
+The headers controlling how code is formatted are:
+
+ - `X-Line-Length`: corresponds to the `--line-length` command line flag.
+ - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
+    command line flag. If present and its value is not the empty string, no string
+    normalization will be performed.
+ - `X-Skip-Numeric-Underscore-Normalization`: corresponds to the
+    `--skip-numeric-underscore-normalization` command line flag.
+ - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as *Black* does when
+    passed the `--fast` command line flag.
+ - `X-Python-Variant`: if set to `pyi`, `blackd` will act as *Black* does when
+    passed the `--pyi` command line flag. Otherwise, its value must correspond to
+    a Python version. If this value represents at least Python 3.6, `blackd` will
+    act as *Black* does when passed the `--py36` command line flag.
+
+If any of these headers are set to invalid values, `blackd` returns a `HTTP 400`
+error response, mentioning the name of the problematic header in the message body.
+
+Apart from the above, `blackd` can produce the following response codes:
+
+ - `HTTP 204`: If the input is already well-formatted. The response body is
+       empty.
+ - `HTTP 200`: If formatting was needed on the input. The response body
+       contains the blackened Python code, and the `Content-Type` header is set
+       accordingly.
+ - `HTTP 400`: If the input contains a syntax error. Details of the error are
+       returned in the response body.
+ - `HTTP 500`: If there was any kind of error while trying to format the input.
+       The response body contains a textual representation of the error.
 
 ## Version control integration
 
 
 ## Version control integration
 
@@ -631,16 +843,18 @@ repos:
     rev: stable
     hooks:
     - id: black
     rev: stable
     hooks:
     - id: black
-      args: [--line-length=88, --safe]
       language_version: python3.6
 ```
 Then run `pre-commit install` and you're ready to go.
 
       language_version: python3.6
 ```
 Then run `pre-commit install` and you're ready to go.
 
-`args` in the above config is optional but shows you how you can change
-the line length if you really need to.  If you're already using Python
-3.7, switch the `language_version` accordingly. Finally, `stable` is a tag
-that is pinned to the latest release on PyPI.  If you'd rather run on
-master, this is also an option.
+Avoid using `args` in the hook.  Instead, store necessary configuration
+in `pyproject.toml` so that editors and command-line usage of Black all
+behave consistently for your project.  See *Black*'s own `pyproject.toml`
+for an example.
+
+If you're already using Python 3.7, switch the `language_version`
+accordingly. Finally, `stable` is a tag that is pinned to the latest
+release on PyPI.  If you'd rather run on master, this is also an option.
 
 
 ## Ignoring unmodified files
 
 
 ## Ignoring unmodified files
@@ -651,9 +865,12 @@ location of the file depends on the *Black* version and the system on which *Bla
 is run. The file is non-portable. The standard location on common operating systems
 is:
 
 is run. The file is non-portable. The standard location on common operating systems
 is:
 
-* Windows: `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.pickle`
-* macOS: `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.pickle`
-* Linux: `/home/<username>/.cache/black/<version>/cache.<line-length>.pickle`
+* Windows: `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.<file-mode>.pickle`
+* macOS: `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickle`
+* Linux: `/home/<username>/.cache/black/<version>/cache.<line-length>.<file-mode>.pickle`
+
+`file-mode` is an int flag that determines whether the file was formatted as 3.6+ only,
+as .pyi, and whether string normalization was omitted.
 
 
 ## Testimonials
 
 
 ## Testimonials
@@ -662,7 +879,7 @@ is:
 
 > *Black* is opinionated so you don't have to be.
 
 
 > *Black* is opinionated so you don't have to be.
 
-**Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core
+**Hynek Schlawack**, [creator of `attrs`](https://www.attrs.org/), core
 developer of Twisted and CPython:
 
 > An auto-formatter that doesn't suck is all I want for Xmas!
 developer of Twisted and CPython:
 
 > An auto-formatter that doesn't suck is all I want for Xmas!
@@ -685,6 +902,12 @@ Use the badge in your project's README.md:
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 ```
 
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 ```
 
+Using the badge in README.rst:
+```
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/ambv/black
+```
+
 Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 
 Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 
@@ -711,6 +934,100 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
 
 ## Change Log
 
+### 18.9b0
+
+* numeric literals are now formatted by *Black* (#452, #461, #464, #469):
+
+  * numeric literals are normalized to include `_` separators on Python 3.6+ code
+
+  * added `--skip-numeric-underscore-normalization` to disable the above behavior and
+    leave numeric underscores as they were in the input
+
+  * code with `_` in numeric literals is recognized as Python 3.6+
+
+  * most letters in numeric literals are lowercased (e.g., in `1e10`, `0x01`)
+
+  * hexadecimal digits are always uppercased (e.g. `0xBADC0DE`)
+
+* added `blackd`, see [its documentation](#blackd) for more info (#349)
+
+* adjacent string literals are now correctly split into multiple lines (#463)
+
+* trailing comma is now added to single imports that don't fit on a line (#250)
+
+* cache is now populated when `--check` is successful for a file which speeds up
+  consecutive checks of properly formatted unmodified files (#448)
+
+* whitespace at the beginning of the file is now removed (#399)
+
+* fixed mangling [pweave](http://mpastell.com/pweave/) and
+  [Spyder IDE](https://pythonhosted.org/spyder/) special comments (#532)
+
+* fixed unstable formatting when unpacking big tuples (#267)
+
+* fixed parsing of `__future__` imports with renames (#389)
+
+* fixed scope of `# fmt: off` when directly preceding `yield` and other nodes (#385)
+
+* fixed formatting of lambda expressions with default arguments (#468)
+
+* fixed ``async for`` statements: *Black* no longer breaks them into separate
+  lines (#372)
+
+* note: the Vim plugin stopped registering ``,=`` as a default chord as it turned out
+  to be a bad idea (#415)
+
+
+### 18.6b4
+
+* hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)
+
+
+### 18.6b3
+
+* typing stub files (`.pyi`) now have blank lines added after constants (#340)
+
+* `# fmt: off` and `# fmt: on` are now much more dependable:
+
+  * they now work also within bracket pairs (#329)
+
+  * they now correctly work across function/class boundaries (#335)
+
+  * they now work when an indentation block starts with empty lines or misaligned
+    comments (#334)
+
+* made Click not fail on invalid environments; note that Click is right but the
+  likelihood we'll need to access non-ASCII file paths when dealing with Python source
+  code is low (#277)
+
+* fixed improper formatting of f-strings with quotes inside interpolated
+  expressions (#322)
+
+* fixed unnecessary slowdown when long list literals where found in a file
+
+* fixed unnecessary slowdown on AST nodes with very many siblings
+
+* fixed cannibalizing backslashes during string normalization
+
+* fixed a crash due to symbolic links pointing outside of the project directory (#338)
+
+
+### 18.6b2
+
+* added `--config` (#65)
+
+* added `-h` equivalent to `--help` (#316)
+
+* fixed improper unmodified file caching when `-S` was used
+
+* fixed extra space in string unpacking (#305)
+
+* fixed formatting of empty triple quoted strings (#313)
+
+* fixed unnecessary slowdown in comment placement calculation on lines without
+  comments
+
+
 ### 18.6b1
 
 * hotfix: don't output human-facing information on stdout (#299)
 ### 18.6b1
 
 * hotfix: don't output human-facing information on stdout (#299)
@@ -954,7 +1271,7 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 ### 18.3a2
 
 * changed positioning of binary operators to occur at beginning of lines
 ### 18.3a2
 
 * changed positioning of binary operators to occur at beginning of lines
-  instead of at the end, following [a recent change to PEP8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
+  instead of at the end, following [a recent change to PEP 8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
   (#21)
 
 * ignore empty bracket pairs while splitting. This avoids very weirdly
   (#21)
 
 * ignore empty bracket pairs while splitting. This avoids very weirdly
@@ -1013,6 +1330,7 @@ Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
 
 Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
 [Carl Meyer](mailto:carl@oddbird.net),
 
 Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
 [Carl Meyer](mailto:carl@oddbird.net),
+[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
 [Mika Naylor](mailto:mail@autophagy.io), and
 [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com).
 
 [Mika Naylor](mailto:mail@autophagy.io), and
 [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com).
 
@@ -1021,30 +1339,17 @@ Multiple contributions by:
 * [Artem Malyshev](mailto:proofit404@gmail.com)
 * [Christian Heimes](mailto:christian@python.org)
 * [Daniel M. Capella](mailto:polycitizen@gmail.com)
 * [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)
+* [Eli Treuherz](mailto:eli@treuherz.com)
 * Hugo van Kemenade
 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
 * Hugo van Kemenade
 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
-* [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
 * [Jonas Obrist](mailto:ojiidotch@gmail.com)
 * [Luka Sterbic](mailto:luka.sterbic@gmail.com)
 * [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
 * [Jonas Obrist](mailto:ojiidotch@gmail.com)
 * [Luka Sterbic](mailto:luka.sterbic@gmail.com)
 * [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
+* [Miroslav Shubernetskiy](mailto:miroslav@miki725.com)
+* [Neraste](neraste.herr10@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
 * [Peter Bengtsson](mailto:mail@peterbe.com)
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
 * [Peter Bengtsson](mailto:mail@peterbe.com)
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [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)**
+* [Chuck Wooters](mailto:chuck.wooters@microsoft.com)