X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/7ad9445caf53f236dde8f654aa61308f18aa4313..3c62b9cada3f4c603cf17b3ab47259fc9d3ff131:/README.md?ds=sidebyside diff --git a/README.md b/README.md index 61498b2..ac4caa1 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,16 @@ -# black +![Black Logo](https://raw.githubusercontent.com/ambv/black/master/docs/_static/logo2-readme.png) +

The Uncompromising Code Formatter

-[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black) +

+Build Status +Documentation Status +Coverage Status +License: MIT +PyPI +Code style: black +

-> Any color you like. +> “Any color you like.” *Black* is the uncompromising Python code formatter. By using it, you @@ -19,43 +27,68 @@ content instead. possible. -## NOTE: This is an early pre-release +## Installation and Usage -*Black* can already successfully format itself and the standard library. -It also sports a decent test suite. However, it is still very new. -Things will probably be wonky for a while. This is made explicit by the -"Alpha" trove classifier, as well as by the "a" in the version number. -What this means for you is that **until the formatter becomes stable, -you should expect some formatting to change in the future**. +### Installation -Also, as a temporary safety measure, *Black* will check that the -reformatted code still produces a valid AST that is equivalent to the -original. This slows it down. If you're feeling confident, use -``--fast``. +*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. -## Usage +### Usage -*Black* can be installed by running `pip install black`. +To get started right away with sensible defaults: ``` +black {source_file_or_directory} +``` + +### Command line options + +Black doesn't provide many options. You can list them by running +`black --help`: + +```text 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). + + +### NOTE: This is an early pre-release + +*Black* can already successfully format itself and the standard library. +It also sports a decent test suite. However, it is still very new. +Things will probably be wonky for a while. This is made explicit by the +"Alpha" trove classifier, as well as by the "a" in the version number. +What this means for you is that **until the formatter becomes stable, +you should expect some formatting to change in the future**. + +Also, as a temporary safety measure, *Black* will check that the +reformatted code still produces a valid AST that is equivalent to the +original. This slows it down. If you're feeling confident, use +``--fast``. + -## The philosophy behind *Black* +## The *Black* code style *Black* reformats entire files in place. It is not configurable. It doesn't take previous formatting into account. It doesn't reformat @@ -64,24 +97,27 @@ recognizes [YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a courtesy for straddling code. -### How *Black* formats files +### How *Black* wraps lines *Black* ignores previous formatting and applies uniform horizontal and vertical whitespace to your code. The rules for horizontal whitespace are pretty obvious and can be summarized as: do whatever -makes `pycodestyle` happy. +makes `pycodestyle` happy. The coding style used by *Black* can be +viewed as a strict subset of PEP 8. As for vertical whitespace, *Black* tries to render one full expression 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 +125,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 +144,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, ): @@ -132,20 +171,6 @@ between two distinct sections of the code that otherwise share the same indentation level (like the arguments list and the docstring in the example above). -Unnecessary trailing commas are removed if an expression fits in one -line. This makes it 1% more likely that your line won't exceed the -allotted line length limit. - -*Black* avoids spurious vertical whitespace. This is in the spirit of -PEP 8 which says that in-function vertical whitespace should only be -used sparingly. One exception is control flow statements: *Black* will -always emit an extra empty line after ``return``, ``raise``, ``break``, -``continue``, and ``yield``. This is to make changes in control flow -more prominent to readers of your code. - -That's it. The rest of the whitespace formatting rules follow PEP 8 and -are designed to keep `pycodestyle` quiet. - ### Line length @@ -184,14 +209,124 @@ 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". -### Editor integration +### Empty lines + +*Black* avoids spurious vertical whitespace. This is in the spirit of +PEP 8 which says that in-function vertical whitespace should only be +used sparingly. One exception is control flow statements: *Black* will +always emit an extra empty line after ``return``, ``raise``, ``break``, +``continue``, and ``yield``. This is to make changes in control flow +more prominent to readers of your code. + +*Black* will allow single empty lines inside functions, and single and +double empty lines on module level left by the original editors, except +when they're 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. + -There is currently no integration with any text editors. Vim and -Atom/Nuclide integration is planned by the author, others will require -external contributions. +### Trailing commas + +*Black* will add trailing commas to expressions that are split +by comma where each element is on its own line. This includes function +signatures. + +Unnecessary trailing commas are removed if an expression fits in one +line. This makes it 1% more likely that your line won't exceed the +allotted line length limit. Moreover, in this scenario, if you added +another argument to your call, you'd probably fit it in the same line +anyway. That doesn't make diffs any larger. + +One exception to removing trailing commas is tuple expressions with +just one element. In this case *Black* won't touch the single trailing +comma as this would unexpectedly change the underlying data type. Note +that this is also the case when commas are used while indexing. This is +a tuple in disguise: ```numpy_array[3, ]```. + +One exception to adding trailing commas is function signatures +containing `*`, `*args`, or `**kwargs`. In this case a trailing comma +is only safe to use on Python 3.6. *Black* will detect if your file is +already 3.6+ only and use trailing commas in this situation. If you +wonder how it knows, it looks for f-strings and existing use of trailing +commas in function signatures that have stars in them. In other words, +if you'd like a trailing comma in this situation and *Black* didn't +recognize it was safe to do so, put it there manually and *Black* will +keep it. + + +## Editor integration + +### Emacs + +Use [proofit404/blacken](https://github.com/proofit404/blacken). + + +### Vim + +Commands and shortcuts: + +* `,=` or `: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. + +Configuration: +* `g:black_fast` (defaults to `0`) +* `g:black_linelength` (defaults to `88`) +* `g:black_virtualenv` (defaults to `~/.vim/black`) + +To install, copy the plugin from [vim/plugin/black.vim](https://github.com/ambv/black/tree/master/vim/plugin/black.vim). +Let me know if this requires any changes to work with Vim 8's builtin +`packadd`, or Pathogen, or Vundle, and so on. + +This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It +needs Python 3.6 to be able to run *Black* inside the Vim process which +is much faster than calling an external command. + +On first run, the plugin creates its own virtualenv using the right +Python version and automatically installs *Black*. You can upgrade it later +by calling `:BlackUpgrade` and restarting Vim. + +If you need to do anything special to make your virtualenv work and +install *Black* (for example you want to run a version from master), just +create a virtualenv manually and point `g:black_virtualenv` to it. +The plugin will use it. + +**How to get Vim with Python 3.6?** +On Ubuntu 17.10 Vim comes with Python 3.6 by default. +On macOS with HomeBrew run: `brew install vim --with-python3`. +When building Vim from source, use: +`./configure --enable-python3interp=yes`. There's many guides online how +to do this. + + +### Visual Studio Code + +Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode). + + +### Other editors + +Atom/Nuclide integration is planned by the author, others 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)). +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). + ## Testimonials @@ -214,25 +349,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 @@ -240,7 +365,7 @@ f-strings) instead of wasting cycles on Unicode compatibility, and so on. MIT -## Contributing +## Contributing to Black In terms of inspiration, *Black* is about as configurable as *gofmt* and *rustfmt* are. This is deliberate. @@ -258,7 +383,53 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log -### 18.3a2 (unreleased) +### 18.3a5 (unreleased) + +* fixed 18.3a4 regression: don't crash and burn on empty lines with + trailing whitespace (#80) + +* only allow up to two empty lines on module level and only single empty + lines within functions (#74) + + +### 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) @@ -269,6 +440,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 +488,14 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Authors Glued together by [Łukasz Langa](mailto:lukasz@langa.pl). + +Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com) +and [Carl Meyer](mailto:carl@oddbird.net). + +Multiple contributions by: +* [Artem Malyshev](mailto:proofit404@gmail.com) +* [Daniel M. Capella](mailto:polycitizen@gmail.com) +* [Eli Treuherz](mailto:eli.treuherz@cgi.com) +* Hugo van Kemenade +* [Mika⠙](mailto:mail@autophagy.io) +* [Osaetin Daniel](mailto:osaetindaniel@gmail.com)