X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/ed50737290662f6ef4016a7ea44da78ee1eff1e2..99c97c3d7fa8532faf11f818bf1fcf08e991e62c:/README.md?ds=inline
diff --git a/README.md b/README.md
index d6e76cd..afb160e 100644
--- a/README.md
+++ b/README.md
@@ -3,10 +3,11 @@
-
+
-
-
+
+
+
@@ -26,16 +27,19 @@ content instead.
*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)** |
-**[The *Black* code style](#the-black-code-style)** |
+**[Code style](#the-black-code-style)** |
+**[pyproject.toml](#pyprojecttoml)** |
**[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)** |
-**[License](#license)** |
**[Contributing](#contributing-to-black)** |
**[Change Log](#change-log)** |
**[Authors](#authors)**
@@ -60,7 +64,7 @@ black {source_file_or_directory}
### Command line options
-Black doesn't provide many options. You can list them by running
+*Black* doesn't provide many options. You can list them by running
`black --help`:
```text
@@ -77,6 +81,8 @@ Options:
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
@@ -95,7 +101,7 @@ Options:
recursive searches. On Windows, use forward
slashes for directories. [default:
build/|buck-out/|dist/|_build/|\.git/|\.hg/|
- \.mypy_cache/|\.tox/|\.venv/]
+ \.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.
@@ -103,6 +109,7 @@ Options:
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.
```
@@ -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
-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.
@@ -272,7 +280,8 @@ ignore = E501
```
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".
@@ -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.
+### 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
@@ -487,6 +509,100 @@ a future version of the formatter:
* 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.
+
+
+Example `pyproject.toml`
+
+```toml
+[tool.black]
+line-length = 88
+py36 = true
+include = '\.pyi?$'
+exclude = '''
+/(
+ \.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
+)/
+'''
+```
+
+
+
+### 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
@@ -524,17 +640,28 @@ $ where black
- Name: Black
- Description: Black is the uncompromising Python code formatter.
- Program:
- - 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`.
+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:
+ - Arguments: `$FilePath$`
+ - Output paths to refresh: `$FilePathRelativeToProjectRoot$`
+ - Working directory: `$ProjectFileDir$`
### 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.
@@ -542,12 +669,13 @@ Commands and shortcuts:
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):
```
-Plug 'ambv/black',
+Plug 'ambv/black'
```
or with [Vundle](https://github.com/VundleVim/Vundle.vim):
@@ -576,7 +704,7 @@ The plugin will use it.
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?**
@@ -589,7 +717,8 @@ to do this.
### Visual Studio Code
-Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+Use the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
### SublimeText 3
@@ -602,21 +731,105 @@ Use [sublack plugin](https://github.com/jgirardet/sublack).
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
-Atom/Nuclide integration is planned by the author, others will
-require external contributions.
+Other editors 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)).
+[use `-` as the file name](https://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).
+## 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
@@ -629,38 +842,43 @@ repos:
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.
-`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
*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
+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`
+
+`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
**Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
-> 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!
@@ -683,6 +901,12 @@ Use the badge in your project's README.md:
[](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: [](https://github.com/ambv/black)
@@ -691,7 +915,7 @@ Looks like this: [.
## 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)
@@ -840,10 +1158,10 @@ 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
+* *Black* no longer enforces putting empty lines behind control flow statements
(#90)
-* Black now splits imports like "Mode 3 + trailing comma" of isort (#127)
+* *Black* now splits imports like "Mode 3 + trailing comma" of isort (#127)
* fixed comment indentation when a standalone comment closes a block (#16, #32)
@@ -896,16 +1214,16 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
(#75)
* fixed handling of standalone comments within nested bracketed
- expressions; Black will no longer produce super long lines or put all
+ 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)
* fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment
- would cause Black to not emit the rest of the file (#95)
+ would cause *Black* to not emit the rest of the file (#95)
-* when CTRL+C is pressed while formatting many files, Black no longer
+* 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
@@ -952,7 +1270,7 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
### 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
@@ -1011,6 +1329,7 @@ Glued together by [Åukasz Langa](mailto:lukasz@langa.pl).
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).
@@ -1019,29 +1338,16 @@ Multiple contributions by:
* [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)
-* [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)
+* [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)
-
----
-
-*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)**