[//]: # (NOTE: THIS FILE IS AUTOGENERATED FROM README.md)

# Editor integration

## Emacs

Use [proofit404/blacken](https://github.com/proofit404/blacken).


## 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
```

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 Watcher](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"

## 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`)

To install with [vim-plug](https://github.com/junegunn/vim-plug):

```
Plug 'ambv/black'
```

or with [Vundle](https://github.com/VundleVim/Vundle.vim):

```
Plugin 'ambv/black'
```

or you can copy the plugin from [plugin/black.vim](https://github.com/ambv/black/tree/master/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'
```

**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 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).


## 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).

