docs/editor_integration.md

   1 # Editor integration
   2
   3 ## Emacs
   4
   5 Options include the following:
   6
   7 - [purcell/reformatter.el](https://github.com/purcell/reformatter.el)
   8 - [proofit404/blacken](https://github.com/pythonic-emacs/blacken)
   9 - [Elpy](https://github.com/jorgenschaefer/elpy).
  10
  11 ## PyCharm/IntelliJ IDEA
  12
  13 1. Install `black`.
  14
  15 ```console
  16 $ pip install black
  17 ```
  18
  19 2. Locate your `black` installation folder.
  20
  21 On macOS / Linux / BSD:
  22
  23 ```console
  24 $ which black
  25 /usr/local/bin/black  # possible location
  26 ```
  27
  28 On Windows:
  29
  30 ```console
  31 $ where black
  32 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
  33 ```
  34
  35 Note that if you are using a virtual environment detected by PyCharm, this is an
  36 unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
  37
  38 3. Open External tools in PyCharm/IntelliJ IDEA
  39
  40 On macOS:
  41
  42 `PyCharm -> Preferences -> Tools -> External Tools`
  43
  44 On Windows / Linux / BSD:
  45
  46 `File -> Settings -> Tools -> External Tools`
  47
  48 4. Click the + icon to add a new external tool with the following values:
  49
  50    - Name: Black
  51    - Description: Black is the uncompromising Python code formatter.
  52    - Program: <install_location_from_step_2>
  53    - Arguments: `"$FilePath$"`
  54
  55 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
  56
  57    - Alternatively, you can set a keyboard shortcut by navigating to
  58      `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
  59
  60 6. Optionally, run _Black_ on every file save:
  61
  62    1. Make sure you have the
  63       [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
  64       installed.
  65    2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
  66       new watcher:
  67       - Name: Black
  68       - File type: Python
  69       - Scope: Project Files
  70       - Program: <install_location_from_step_2>
  71       - Arguments: `$FilePath$`
  72       - Output paths to refresh: `$FilePath$`
  73       - Working directory: `$ProjectFileDir$`
  74
  75    - Uncheck "Auto-save edited files to trigger the watcher" in Advanced Options
  76
  77 ## Wing IDE
  78
  79 Wing supports black via the OS Commands tool, as explained in the Wing documentation on
  80 [pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
  81
  82 1. Install `black`.
  83
  84 ```console
  85 $ pip install black
  86 ```
  87
  88 2. Make sure it runs from the command line, e.g.
  89
  90 ```console
  91 $ black --help
  92 ```
  93
  94 3. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
  95    execute black on the currently selected file:
  96
  97 - Use the Tools -> OS Commands menu selection
  98 - click on **+** in **OS Commands** -> New: Command line..
  99   - Title: black
 100   - Command Line: black %s
 101   - I/O Encoding: Use Default
 102   - Key Binding: F1
 103   - [x] Raise OS Commands when executed
 104   - [x] Auto-save files before execution
 105   - [x] Line mode
 106
 107 4. Select a file in the editor and press **F1** , or whatever key binding you selected
 108    in step 3, to reformat the file.
 109
 110 ## Vim
 111
 112 Commands and shortcuts:
 113
 114 - `:Black` to format the entire file (ranges not supported);
 115 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
 116 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
 117
 118 Configuration:
 119
 120 - `g:black_fast` (defaults to `0`)
 121 - `g:black_linelength` (defaults to `88`)
 122 - `g:black_skip_string_normalization` (defaults to `0`)
 123 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 124
 125 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 126
 127 ```
 128 Plug 'psf/black', { 'branch': 'stable' }
 129 ```
 130
 131 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 132
 133 ```
 134 Plugin 'psf/black'
 135 ```
 136
 137 and execute the following in a terminal:
 138
 139 ```console
 140 $ cd ~/.vim/bundle/black
 141 $ git checkout origin/stable -b stable
 142 ```
 143
 144 or you can copy the plugin from
 145 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
 146
 147 ```
 148 mkdir -p ~/.vim/pack/python/start/black/plugin
 149 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
 150 ```
 151
 152 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 153 Pathogen, and so on.
 154
 155 This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
 156 be able to run _Black_ inside the Vim process which is much faster than calling an
 157 external command.
 158
 159 On first run, the plugin creates its own virtualenv using the right Python version and
 160 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
 161 restarting Vim.
 162
 163 If you need to do anything special to make your virtualenv work and install _Black_ (for
 164 example you want to run a version from master), create a virtualenv manually and point
 165 `g:black_virtualenv` to it. The plugin will use it.
 166
 167 To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
 168
 169 ```
 170 autocmd BufWritePre *.py execute ':Black'
 171 ```
 172
 173 To run _Black_ on a key press (e.g. F9 below), add this:
 174
 175 ```
 176 nnoremap <F9> :Black<CR>
 177 ```
 178
 179 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
 180 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
 181 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
 182 this.
 183
 184 **I get an import error when using _Black_ from a virtual environment**: If you get an
 185 error message like this:
 186
 187 ```text
 188 Traceback (most recent call last):
 189   File "<string>", line 63, in <module>
 190   File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
 191     from typed_ast import ast3, ast27
 192   File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
 193     from typed_ast import _ast3
 194 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
 195 ```
 196
 197 Then you need to install `typed_ast` and `regex` directly from the source code. The
 198 error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if
 199 they are available. Python wheels are a new standard of distributing Python packages and
 200 packages that have Cython and extensions written in C are already compiled, so the
 201 installation is much more faster. The problem here is that somehow the Python
 202 environment inside Vim does not match with those already compiled C extensions and these
 203 kind of errors are the result. Luckily there is an easy fix: installing the packages
 204 from the source code.
 205
 206 The two packages that cause the problem are:
 207
 208 - [regex](https://pypi.org/project/regex/)
 209 - [typed-ast](https://pypi.org/project/typed-ast/)
 210
 211 Now remove those two packages:
 212
 213 ```console
 214 $ pip uninstall regex typed-ast -y
 215 ```
 216
 217 And now you can install them with:
 218
 219 ```console
 220 $ pip install --no-binary :all: regex typed-ast
 221 ```
 222
 223 The C extensions will be compiled and now Vim's Python environment will match. Note that
 224 you need to have the GCC compiler and the Python development files installed (on
 225 Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
 226
 227 If you later want to update _Black_, you should do it like this:
 228
 229 ```console
 230 $ pip install -U black --no-binary regex,typed-ast
 231 ```
 232
 233 ## Visual Studio Code
 234
 235 Use the
 236 [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
 237 ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
 238
 239 ## SublimeText 3
 240
 241 Use [sublack plugin](https://github.com/jgirardet/sublack).
 242
 243 ## Jupyter Notebook Magic
 244
 245 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 246
 247 ## Python Language Server
 248
 249 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 250 Sublime Text, Visual Studio Code and many more), you can use the
 251 [Python Language Server](https://github.com/palantir/python-language-server) with the
 252 [pyls-black](https://github.com/rupert/pyls-black) plugin.
 253
 254 ## Atom/Nuclide
 255
 256 Use [python-black](https://atom.io/packages/python-black).
 257
 258 ## Kakoune
 259
 260 Add the following hook to your kakrc, then run _Black_ with `:format`.
 261
 262 ```
 263 hook global WinSetOption filetype=python %{
 264     set-option window formatcmd 'black -q  -'
 265 }
 266 ```
 267
 268 ## Thonny
 269
 270 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).
 271
 272 ## Other editors
 273
 274 Other editors will require external contributions.
 275
 276 Patches welcome! ✨ 🍰 ✨
 277
 278 Any tool that can pipe code through _Black_ using its stdio mode (just
 279 [use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
 280 The formatted code will be returned on stdout (unless `--check` was passed). _Black_
 281 will still emit messages on stderr but that shouldn't affect your use case.
 282
 283 This can be used for example with PyCharm's or IntelliJ's
 284 [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).