-- [purcell/reformatter.el](https://github.com/purcell/reformatter.el)
-- [proofit404/blacken](https://github.com/proofit404/blacken)
-- [Elpy](https://github.com/jorgenschaefer/elpy).
-
-### PyCharm/IntelliJ IDEA
-
-1. Install `black`.
-
-```console
-$ pip install black
-```
-
-2. Locate your `black` installation folder.
-
-On macOS / Linux / BSD:
-
-```console
-$ which black
-/usr/local/bin/black # possible location
-```
-
-On Windows:
-
-```console
-$ where black
-%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
-```
-
-Note that if you are using a virtual environment detected by PyCharm, this is an
-unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
-
-3. Open External tools in PyCharm/IntelliJ IDEA
-
-On macOS:
-
-`PyCharm -> Preferences -> Tools -> External Tools`
-
-On Windows / Linux / BSD:
-
-`File -> Settings -> Tools -> External Tools`
-
-4. Click the + icon to add a new external tool with the following values:
-
- - Name: Black
- - Description: Black is the uncompromising Python code formatter.
- - Program: <install_location_from_step_2>
- - 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 or Settings -> Keymap -> External Tools -> External Tools - Black`.
-
-6. Optionally, run _Black_ on every file save:
-
- 1. Make sure you have the
- [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
- installed.
- 2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
- new watcher:
- - Name: Black
- - File type: Python
- - Scope: Project Files
- - Program: <install_location_from_step_2>
- - Arguments: `$FilePath$`
- - Output paths to refresh: `$FilePath$`
- - Working directory: `$ProjectFileDir$`
-
- - Uncheck "Auto-save edited files to trigger the watcher"
-
-### Wing IDE
-
-Wing supports black via the OS Commands tool, as explained in the Wing documentation on
-[pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
-
-1. Install `black`.
-
-```console
-$ pip install black
-```
-
-2. Make sure it runs from the command line, e.g.
-
-```console
-$ black --help
-```
-
-3. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
- execute black on the currently selected file:
-
-- Use the Tools -> OS Commands menu selection
-- click on **+** in **OS Commands** -> New: Command line..
- - Title: black
- - Command Line: black %s
- - I/O Encoding: Use Default
- - Key Binding: F1
- - [x] Raise OS Commands when executed
- - [x] Auto-save files before execution
- - [x] Line mode
-
-4. Select a file in the editor and press **F1** , or whatever key binding you selected
- in step 3, to reformat the file.
-
-### Vim
-
-Commands and shortcuts:
-
-- `: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_skip_string_normalization` (defaults to `0`)
-- `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
-
-To install with [vim-plug](https://github.com/junegunn/vim-plug):
-
-```
-Plug 'psf/black', { 'branch': 'stable' }
-```
-
-or with [Vundle](https://github.com/VundleVim/Vundle.vim):
-
-```
-Plugin 'psf/black'
-```
-
-and execute the following in a terminal:
-
-```console
-$ cd ~/.vim/bundle/black
-$ git checkout origin/stable -b stable
-```
-
-or you can copy the plugin from
-[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
-
-```
-mkdir -p ~/.vim/pack/python/start/black/plugin
-curl https://raw.githubusercontent.com/psf/black/master/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
-```
-
-Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
-Pathogen, 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), create a virtualenv manually and point
-`g:black_virtualenv` to it. The plugin will use it.
-
-To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
-
-```
-autocmd BufWritePre *.py execute ':Black'
-```
-
-To run _Black_ on a key press (e.g. F9 below), add this:
-
-```
-nnoremap <F9> :Black<CR>
-```
-
-**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`. When building Vim from source,
-use: `./configure --enable-python3interp=yes`. There's many guides online how to do
-this.
-
-**I get an import error when using _Black_ from a virtual environment**: If you get an
-error message like this:
-
-```text
-Traceback (most recent call last):
- File "<string>", line 63, in <module>
- File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
- from typed_ast import ast3, ast27
- File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
- from typed_ast import _ast3
-ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
-```
-
-Then you need to install `typed_ast` and `regex` directly from the source code. The
-error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if
-they are available. Python wheels are a new standard of distributing Python packages and
-packages that have Cython and extensions written in C are already compiled, so the
-installation is much more faster. The problem here is that somehow the Python
-environment inside Vim does not match with those already compiled C extensions and these
-kind of errors are the result. Luckily there is an easy fix: installing the packages
-from the source code.
-
-The two packages that cause the problem are:
-
-- [regex](https://pypi.org/project/regex/)
-- [typed-ast](https://pypi.org/project/typed-ast/)
-
-Now remove those two packages:
-
-```console
-$ pip uninstall regex typed-ast -y
-```
-
-And now you can install them with:
-
-```console
-$ pip install --no-binary :all: regex typed-ast
-```
-
-The C extensions will be compiled and now Vim's Python environment will match. Note that
-you need to have the GCC compiler and the Python development files installed (on
-Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
-
-If you later want to update _Black_, you should do it like this:
-
-```console
-$ pip install -U black --no-binary regex,typed-ast
-```
-
-### 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)).
-
-### SublimeText 3
-
-Use [sublack plugin](https://github.com/jgirardet/sublack).
-
-### Jupyter Notebook Magic
-
-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 [python-black](https://atom.io/packages/python-black).
-
-### Kakoune
-
-Add the following hook to your kakrc, then run black with `:format`.
-
-```
-hook global WinSetOption filetype=python %{
- set-option window formatcmd 'black -q -'
-}
-```
-
-### Thonny
-
-Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).
-
-### Other editors
-
-Other editors will require external contributions.
-
-Patches welcome! ✨ 🍰 ✨
-
-Any tool that can pipe code through _Black_ using its stdio mode (just
-[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.
-
-This can be used for example with PyCharm's or IntelliJ's
-[File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
-
-## blackd
-
-`blackd` is a small HTTP server that exposes _Black_'s functionality over a simple
-protocol. The main benefit of using it is to avoid paying the cost of starting up a new
-_Black_ process every time you want to blacken a file.
-
-### Usage
-
-`blackd` is not packaged alongside _Black_ by default because it has additional
-dependencies. You will need to do `pip install black[d]` to install it.
-
-You can start the server on the default port, binding only to the local interface by
-running `blackd`. You will see a single line mentioning the server's version, and the
-host and port it's listening on. `blackd` will then print an access log similar to most
-web servers on standard output, merged with any exception traces caused by invalid
-formatting requests.
-
-`blackd` provides even less options than _Black_. You can see them by running
-`blackd --help`:
-
-```text
-Usage: blackd [OPTIONS]
-
-Options:
- --bind-host TEXT Address to bind the server to.
- --bind-port INTEGER Port to listen on
- --version Show the version and exit.
- -h, --help Show this message and exit.
-```
-
-There is no official blackd client tool (yet!). You can test that blackd is working
-using `curl`:
-
-```sh
-blackd --bind-port 9090 & # or let blackd choose a port
-curl -s -XPOST "localhost:9090" -d "print('valid')"
-```
-
-### Protocol
-
-`blackd` only accepts `POST` requests at the `/` path. The body of the request should
-contain the python source code to be formatted, encoded according to the `charset` field
-in the `Content-Type` request header. If no `charset` is specified, `blackd` assumes
-`UTF-8`.
-
-There are a few HTTP headers that control how the source is formatted. These correspond
-to command line flags for _Black_. There is one exception to this: `X-Protocol-Version`
-which if present, should have the value `1`, otherwise the request is rejected with
-`HTTP 501` (Not Implemented).
-
-The headers controlling how code is formatted are:
-
-- `X-Line-Length`: corresponds to the `--line-length` command line flag.
-- `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
- command line flag. If present and its value is not the empty string, no string
- normalization will be performed.
-- `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the
- `--fast` command line flag.
-- `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the
- `--pyi` command line flag. Otherwise, its value must correspond to a Python version or
- a set of comma-separated Python versions, optionally prefixed with `py`. For example,
- to request code that is compatible with Python 3.5 and 3.6, set the header to
- `py3.5,py3.6`.
-- `X-Diff`: corresponds to the `--diff` command line flag. If present, a diff of the
- formats will be output.
-
-If any of these headers are set to invalid values, `blackd` returns a `HTTP 400` error
-response, mentioning the name of the problematic header in the message body.
-
-Apart from the above, `blackd` can produce the following response codes:
-
-- `HTTP 204`: If the input is already well-formatted. The response body is empty.
-- `HTTP 200`: If formatting was needed on the input. The response body contains the
- blackened Python code, and the `Content-Type` header is set accordingly.
-- `HTTP 400`: If the input contains a syntax error. Details of the error are returned in
- the response body.
-- `HTTP 500`: If there was any kind of error while trying to format the input. The
- response body contains a textual representation of the error.
-
-The response headers include a `X-Black-Version` header containing the version of
-_Black_.
-
-## black-primer
-
-`black-primer` is a tool built for CI (and huumans) to have _Black_ `--check` a number
-of (configured in `primer.json`) Git accessible projects in parallel. _(A PR will be
-accepted to add Mercurial support.)_
-
-### Run flow
-
-- Ensure we have a `black` + `git` in PATH
-- Load projects from `primer.json`
-- Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
- - Checkout projects
- - Run black and record result
- - Clean up repository checkout _(can optionally be disabled via `--keep`)_
-- Display results summary to screen
-- Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
-- Return
- - 0 for successful run
- - < 0 for environment / internal error
- - > 0 for each project with an error
-
-### Speed up Runs 🏎
-
-If you're running locally yourself to test black on lots of code try:
-
-- Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
- each run
-
-### CLI Arguments
-
-```text
-Usage: black-primer [OPTIONS]
-
- primer - prime projects for blackening ... 🏴
-
-Options:
- -c, --config PATH JSON config file path [default: /Users/cooper/repos/
- black/src/black_primer/primer.json]
-
- --debug Turn on debug logging [default: False]
- -k, --keep Keep workdir + repos post run [default: False]
- -L, --long-checkouts Pull big projects to test [default: False]
- -R, --rebase Rebase project if already checked out [default:
- False]
-
- -w, --workdir PATH Directory Path for repo checkouts [default: /var/fol
- ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
- 517125229]
-
- -W, --workers INTEGER Number of parallel worker coroutines [default: 69]
- -h, --help Show this message and exit.
-```
-
-### primer config file
-
-The config is `JSON` format. It's main element is the `"projects"` dictionary. Below
-explains each parameter:
-
-```json
-{
- "projects": {
- "00_Example": {
- "cli_arguments": "List of extra CLI arguments to pass Black for this project",
- "expect_formatting_changes": "Boolean to indicate that the version of Black is expected to cause changes",
- "git_clone_url": "URL you would pass `git clone` to check out this repo",
- "long_checkout": "Boolean to have repo skipped by defauult unless `--long-checkouts` is specified",
- "py_versions": "List of major Python versions to run this project with - all will do as you'd expect - run on ALL versions"
- },
- "aioexabgp": {
- "cli_arguments": [],
- "expect_formatting_changes": true,
- "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
- "long_checkout": false,
- "py_versions": ["all", "3.8"] // "all" ignores all other versions
- }
- }
-}
-```
-
-### Example run
-
-```console
-cooper-mbp:black cooper$ ~/venvs/b/bin/black-primer
-[2020-05-17 13:06:40,830] INFO: 4 projects to run black over (lib.py:270)
-[2020-05-17 13:06:44,215] INFO: Analyzing results (lib.py:285)
--- primer results 📊 --
-
-3 / 4 succeeded (75.0%) ✅
-1 / 4 FAILED (25.0%) 💩
- - 0 projects Disabled by config
- - 0 projects skipped due to Python Version
- - 0 skipped due to long checkout
-
-Failed Projects:
-
-## flake8-bugbear:
- - Returned 1
- - stdout:
---- tests/b303_b304.py 2020-05-17 20:04:09.991227 +0000
-+++ tests/b303_b304.py 2020-05-17 20:06:42.753851 +0000
-@@ -26,11 +26,11 @@
- maxint = 5 # this is okay
- # the following shouldn't crash
- (a, b, c) = list(range(3))
- # it's different than this
- a, b, c = list(range(3))
-- a, b, c, = list(range(3))
-+ a, b, c = list(range(3))
- # and different than this
- (a, b), c = list(range(3))
- a, *b, c = [1, 2, 3, 4, 5]
- b[1:3] = [0, 0]
-
-would reformat tests/b303_b304.py
-Oh no! 💥 💔 💥
-1 file would be reformatted, 22 files would be left unchanged.
-```
-
-## Version control integration
-
-Use [pre-commit](https://pre-commit.com/). Once you
-[have it installed](https://pre-commit.com/#install), add this to the
-`.pre-commit-config.yaml` in your repository:
-
-```yaml
-repos:
- - repo: https://github.com/psf/black
- rev: stable
- hooks:
- - id: black
- language_version: python3.6
-```
-
-Then run `pre-commit install` and you're ready to go.
-
-Avoid using `args` in the hook. Instead, store necessary configuration in
-`pyproject.toml` so that editors and command-line usage of Black all behave consistently
-for your project. See _Black_'s own
-[pyproject.toml](https://github.com/psf/black/blob/master/pyproject.toml) for an
-example.
-
-If you're already using Python 3.7, switch the `language_version` accordingly. Finally,
-`stable` is a branch that tracks the latest release on PyPI. If you'd rather run on
-master, this is also an option.
-
-## Ignoring unmodified files
-
-_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_ is
-run. The file is non-portable. The standard location on common operating systems is:
-
-- Windows:
- `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.<file-mode>.pickle`
-- macOS:
- `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickle`
-- Linux:
- `/home/<username>/.cache/black/<version>/cache.<line-length>.<file-mode>.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.
-
-To override the location of these files on macOS or Linux, set the environment variable
-`XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache
-in the directory you're running _Black_ from, set `XDG_CACHE_HOME=.cache`. _Black_ will
-then write the above files to `.cache/black/<version>/`.
projects / etc / vim.git / blobdiff