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