X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/5d0a469e8e2a6b83163ea27c9da654cb97f05e8a..8e90e4620496785498730a136e7c3a6bb8b9c893:/README.md diff --git a/README.md b/README.md index 533a1f8..3899dc6 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,8 @@ Documentation Status Coverage Status License: MIT -PyPI +PyPI +Downloads Code style: black

@@ -26,6 +27,8 @@ 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)** | @@ -368,6 +371,13 @@ 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: `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`. ### Line breaks & binary operators @@ -617,17 +627,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. @@ -670,7 +691,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?** @@ -684,8 +705,7 @@ to do this. ### Visual Studio Code 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). +([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)). ### SublimeText 3 @@ -698,10 +718,22 @@ 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 [atom-black](https://github.com/hauntsaninja/atom-black). + + ### Other editors -Atom/Nuclide integration is planned by the author, others will -require external contributions. +Other editors will require external contributions. Patches welcome! ✨ 🍰 ✨ @@ -747,9 +779,12 @@ location of the file depends on the *Black* version and the system on which *Bla 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 @@ -781,6 +816,12 @@ Use the badge in your project's README.md: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) @@ -807,11 +848,65 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log +### 18.8b0 + +* adjacent string literals are now correctly split into multiple lines (#463) + +* numeric literals are now formatted by *Black* (#452, #461, #464, #469): + + * numeric literals are normalized to include `_` separators on Python 3.6+ code + + * code with `_` in numeric literals is recognized as Python 3.6+ + + * most letters in numeric literals are lowercased (e.g., in `1e10` or `0xab`) + +* cache is now populated when `--check` is successful for a file which speeds up + consecutive checks of properly formatted unmodified files (#448) + +* fixed parsing of `__future__` imports with renames (#389) + +* fixed scope of `# fmt: off` when directly preceding `yield` and other nodes (#385) + +* note: the Vim plugin stopped registering ``,=`` as a default chord as it turned out + to be a bad idea (#415) + +* fixed formatting of lambda expressions with default arguments (#468) + + +### 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) @@ -1071,7 +1166,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 @@ -1130,6 +1225,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). @@ -1138,13 +1234,14 @@ 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)