docs/integrations/editors.md

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