X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/7ad9445caf53f236dde8f654aa61308f18aa4313..9e3175428470403d01cdee9c710d5d38e8610860:/README.md diff --git a/README.md b/README.md index 61498b2..d5c88f4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # black -[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black) +[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black) ![License: MIT](https://img.shields.io/github/license/ambv/black.svg) ![PyPI](https://img.shields.io/pypi/v/black.svg) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) > Any color you like. @@ -34,9 +34,16 @@ original. This slows it down. If you're feeling confident, use ``--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]... @@ -44,16 +51,24 @@ 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* @@ -76,12 +91,14 @@ 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 +106,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,16 +125,17 @@ 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): + +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, ): @@ -184,9 +204,33 @@ 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". +### 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. @@ -214,25 +258,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 @@ -258,7 +292,44 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log -### 18.3a2 (unreleased) +### 18.3a4 (unreleased) + +* `# 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) @@ -269,6 +340,14 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). * 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) @@ -309,3 +388,6 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Authors Glued together by [Łukasz Langa](mailto:lukasz@langa.pl). + +[Model T logo](https://thenounproject.com/term/model-t/16785/) by Alex +Valdivia from the Noun Project.