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 ### Official plugin
 115
 116 Commands and shortcuts:
 117
 118 - `:Black` to format the entire file (ranges not supported);
 119 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
 120 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
 121
 122 Configuration:
 123
 124 - `g:black_fast` (defaults to `0`)
 125 - `g:black_linelength` (defaults to `88`)
 126 - `g:black_skip_string_normalization` (defaults to `0`)
 127 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 128 - `g:black_quiet` (defaults to `0`)
 129
 130 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 131
 132 ```
 133 Plug 'psf/black', { 'branch': 'stable' }
 134 ```
 135
 136 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 137
 138 ```
 139 Plugin 'psf/black'
 140 ```
 141
 142 and execute the following in a terminal:
 143
 144 ```console
 145 $ cd ~/.vim/bundle/black
 146 $ git checkout origin/stable -b stable
 147 ```
 148
 149 or you can copy the plugin from
 150 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
 151
 152 ```
 153 mkdir -p ~/.vim/pack/python/start/black/plugin
 154 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
 155 ```
 156
 157 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 158 Pathogen, and so on.
 159
 160 This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
 161 be able to run _Black_ inside the Vim process which is much faster than calling an
 162 external command.
 163
 164 On first run, the plugin creates its own virtualenv using the right Python version and
 165 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
 166 restarting Vim.
 167
 168 If you need to do anything special to make your virtualenv work and install _Black_ (for
 169 example you want to run a version from master), create a virtualenv manually and point
 170 `g:black_virtualenv` to it. The plugin will use it.
 171
 172 To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
 173
 174 ```
 175 autocmd BufWritePre *.py execute ':Black'
 176 ```
 177
 178 To run _Black_ on a key press (e.g. F9 below), add this:
 179
 180 ```
 181 nnoremap <F9> :Black<CR>
 182 ```
 183
 184 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
 185 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
 186 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
 187 this.
 188
 189 **I get an import error when using _Black_ from a virtual environment**: If you get an
 190 error message like this:
 191
 192 ```text
 193 Traceback (most recent call last):
 194   File "<string>", line 63, in <module>
 195   File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
 196     from typed_ast import ast3, ast27
 197   File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
 198     from typed_ast import _ast3
 199 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
 200 ```
 201
 202 Then you need to install `typed_ast` and `regex` directly from the source code. The
 203 error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if
 204 they are available. Python wheels are a new standard of distributing Python packages and
 205 packages that have Cython and extensions written in C are already compiled, so the
 206 installation is much more faster. The problem here is that somehow the Python
 207 environment inside Vim does not match with those already compiled C extensions and these
 208 kind of errors are the result. Luckily there is an easy fix: installing the packages
 209 from the source code.
 210
 211 The two packages that cause the problem are:
 212
 213 - [regex](https://pypi.org/project/regex/)
 214 - [typed-ast](https://pypi.org/project/typed-ast/)
 215
 216 Now remove those two packages:
 217
 218 ```console
 219 $ pip uninstall regex typed-ast -y
 220 ```
 221
 222 And now you can install them with:
 223
 224 ```console
 225 $ pip install --no-binary :all: regex typed-ast
 226 ```
 227
 228 The C extensions will be compiled and now Vim's Python environment will match. Note that
 229 you need to have the GCC compiler and the Python development files installed (on
 230 Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
 231
 232 If you later want to update _Black_, you should do it like this:
 233
 234 ```console
 235 $ pip install -U black --no-binary regex,typed-ast
 236 ```
 237
 238 ### With ALE
 239
 240 1. Install [`ale`](https://github.com/dense-analysis/ale)
 241 2. Install `black`
 242 3. Add this to your vimrc:
 243
 244    ```vim
 245    let g:ale_fixers = {}
 246    let g:ale_fixers.python = ['black']
 247    ```
 248
 249 ## Gedit
 250
 251 gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
 252 as
 253
 254 ```console
 255 $ gedit <file_name>
 256 ```
 257
 258 1. `Go to edit > preferences > plugins`
 259 2. Search for `external tools` and activate it.
 260 3. In `Tools menu -> Manage external tools`
 261 4. Add a new tool using `+` button.
 262 5. Copy the below content to the code window.
 263
 264 ```console
 265 #!/bin/bash
 266 Name=$GEDIT_CURRENT_DOCUMENT_NAME
 267 black $Name
 268 ```
 269
 270 - Set a keyboard shortcut if you like, Ex. `ctrl-B`
 271 - Save: `Nothing`
 272 - Input: `Nothing`
 273 - Output: `Display in bottom pane` if you like.
 274 - Change the name of the tool if you like.
 275
 276 Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
 277 close and reopen your File, _Black_ will be done with its job.
 278
 279 ## Visual Studio Code
 280
 281 Use the
 282 [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
 283 ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
 284
 285 ## SublimeText 3
 286
 287 Use [sublack plugin](https://github.com/jgirardet/sublack).
 288
 289 ## Jupyter Notebook Magic
 290
 291 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 292
 293 ## Python Language Server
 294
 295 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 296 Sublime Text, Visual Studio Code and many more), you can use the
 297 [Python Language Server](https://github.com/palantir/python-language-server) with the
 298 [pyls-black](https://github.com/rupert/pyls-black) plugin.
 299
 300 ## Atom/Nuclide
 301
 302 Use [python-black](https://atom.io/packages/python-black) or
 303 [formatters-python](https://atom.io/packages/formatters-python).
 304
 305 ## Gradle (the build tool)
 306
 307 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
 308
 309 ## Kakoune
 310
 311 Add the following hook to your kakrc, then run _Black_ with `:format`.
 312
 313 ```
 314 hook global WinSetOption filetype=python %{
 315     set-option window formatcmd 'black -q  -'
 316 }
 317 ```
 318
 319 ## Thonny
 320
 321 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).
 322
 323 ## Other integrations
 324
 325 Other editors and tools will require external contributions.
 326
 327 Patches welcome! ✨ 🍰 ✨
 328
 329 Any tool that can pipe code through _Black_ using its stdio mode (just
 330 [use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
 331 The formatted code will be returned on stdout (unless `--check` was passed). _Black_
 332 will still emit messages on stderr but that shouldn't affect your use case.
 333
 334 This can be used for example with PyCharm's or IntelliJ's
 335 [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).