<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/stable/?badge=stable"><img alt="Documentation Status" src="http://readthedocs.org/projects/black/badge/?version=stable"></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="http://black.readthedocs.io/en/stable/_static/license.svg"></a>
-<a href="https://pypi.python.org/pypi/black"><img alt="PyPI" src="http://black.readthedocs.io/en/stable/_static/pypi.svg"></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://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
</p>
### 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
Options:
-l, --line-length INTEGER Where to wrap around. [default: 88]
+ --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]
+ --pyi Format all input files like typing stubs
+ regardless of file extension (useful when piping
+ source on standard input).
+ -S, --skip-string-normalization
+ Don't normalize string quotes or prefixes.
--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
for each file on stdout.
--fast / --safe If --fast given, skip temporary sanity checks.
[default: --safe]
+ --include TEXT A regular expression that matches files and
+ directories that should be included on
+ recursive searches. On Windows, use forward
+ slashes for directories. [default: \.pyi?$]
+ --exclude TEXT A regular expression that matches files and
+ 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/]
-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]
+ -v, --verbose Also emit messages to stderr about files
+ that were not changed or were ignored due to
+ --exclude=.
--version Show the version and exit.
--help Show this message and exit.
```
key. My recommendation here is to keep using whatever is faster to type
and let *Black* handle the transformation.
+If you are adopting *Black* in a large project with pre-existing string
+conventions (like the popular ["single quotes for data, double quotes for
+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.
+
### Line breaks & binary operators
- 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`.
+ - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap -> External Tools -> External Tools - Black`.
### Vim
### 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))
+or [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
### SublimeText 3
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.
hooks:
- id: black
args: [--line-length=88, --safe]
- python_version: python3.6
+ 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 `python_version` accordingly. Finally, `stable` is a tag
+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.
*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:
**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
developer of Twisted and CPython:
MIT
-## Contributing to Black
+## Contributing to *Black*
In terms of inspiration, *Black* is about as configurable as *gofmt*.
This is deliberate.
## Change Log
+### 18.6b1
+
+* hotfix: don't output human-facing information on stdout (#299)
+
+* hotfix: don't output cake emoji on non-zero return code (#300)
+
+
+### 18.6b0
+
+* added `--include` and `--exclude` (#270)
+
+* added `--skip-string-normalization` (#118)
+
+* added `--verbose` (#283)
+
+* the header output in `--diff` now actually conforms to the unified diff spec
+
+* fixed long trivial assignments being wrapped in unnecessary parentheses (#273)
+
+* fixed unnecessary parentheses when a line contained multiline strings (#232)
+
+* fixed stdin handling not working correctly if an old version of Click was
+ used (#276)
+
+* *Black* now preserves line endings when formatting a file in place (#258)
+
+
### 18.5b1
* added `--pyi` (#249)
* 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)
(#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
* [Luka Sterbic](mailto:luka.sterbic@gmail.com)
* [Miguel Gaiowski](mailto:miggaiowski@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)
projects / etc / vim.git / blobdiff