-# black
+
+<h2 align="center">The Uncompromising Code Formatter</h2>
-[](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
``--fast``.
+## Installation
+
+*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.
+*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.
+
+
## Usage
-*Black* can be installed by running `pip install black`.
```
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*
great.
```py3
# in:
+
l = [1,
2,
3,
]
# out:
+
l = [1, 2, 3]
```
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()]
]
separate lines.
```py3
# in:
-def very_important_function(template: str, *variables, *, file: os.PathLike, debug: bool = False):
+
+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,
- *,
file: os.PathLike,
debug: bool = False,
):
bother you if you overdo it by a few km/h".
+### Empty lines
+
+*Black* will allow single empty lines left by the original editors,
+except when they're added 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.
+
+
### Editor integration
-There is currently no integration with any text editors. Vim and
+* Visual Studio Code: [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode)
+
+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.
+
+There is currently no integration with any other text editors. Vim and
Atom/Nuclide integration is planned by the author, others will require
external contributions.
> 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
+[](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: [](https://github.com/ambv/black)
## License
ready to embrace *Black* yet. Such changes are unlikely to get accepted.
You can still try but prepare to be disappointed.
+More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
+
## Change Log
+### 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
+
+* 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)
+ (#21)
+
+* ignore empty bracket pairs while splitting. This avoids very weirdly
+ looking formattings (#34, #35)
+
+* remove a trailing comma if there is a single argument to a call
+
+* if top level functions were separated by a comment, don't put four
+ empty lines after the upper function
+
+* fixed unstable formatting of newlines with imports
+
+* fixed unintentional folding of post scriptum standalone comments
+ into last statement if it was a simple statement (#18, #28)
+
+* fixed missing space in numpy-style array indexing (#33)
+
+* fixed spurious space after star-based unary expressions (#31)
+
+
### 18.3a1
* added `--check`
+* only put trailing commas in function signatures and calls if it's
+ safe to do so. If the file is Python 3.6+ it's always safe, otherwise
+ only safe if there are no `*args` or `**kwargs` used in the signature
+ or call. (#8)
+
* fixed invalid spacing of dots in relative imports (#6, #13)
* fixed invalid splitting after comma on unpacked variables in for-loops
projects / etc / vim.git / blobdiff