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_ with the `d` extra.
  14
  15    ```console
  16    $ pip install 'black[d]'
  17    ```
  18
  19 1. Install
  20    [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect).
  21
  22 1. Open plugin configuration in PyCharm/IntelliJ IDEA
  23
  24    On macOS:
  25
  26    `PyCharm -> Preferences -> Tools -> BlackConnect`
  27
  28    On Windows / Linux / BSD:
  29
  30    `File -> Settings -> Tools -> BlackConnect`
  31
  32 1. In `Local Instance (shared between projects)` section:
  33
  34    1. Check `Start local blackd instance when plugin loads`.
  35    1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
  36       executable.
  37
  38 1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
  39    reformatting with _Black_.
  40
  41 1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
  42    shortcut.
  43
  44 1. Optionally, to run _Black_ on every file save:
  45
  46    - In `Trigger Settings` section of plugin configuration check
  47      `Trigger when saving changed files`.
  48
  49 ## Wing IDE
  50
  51 Wing IDE supports `black` via **Preference Settings** for system wide settings and
  52 **Project Properties** for per-project or workspace specific settings, as explained in
  53 the Wing documentation on
  54 [Auto-Reformatting](https://wingware.com/doc/edit/auto-reformatting). The detailed
  55 procedure is:
  56
  57 ### Prerequistes
  58
  59 - Wing IDE version 8.0+
  60
  61 - Install `black`.
  62
  63   ```console
  64   $ pip install black
  65   ```
  66
  67 - Make sure it runs from the command line, e.g.
  68
  69   ```console
  70   $ black --help
  71   ```
  72
  73 ### Preference Settings
  74
  75 If you want Wing IDE to always reformat with `black` for every project, follow these
  76 steps:
  77
  78 1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
  79
  80 1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
  81    `Whole files before save`.
  82
  83 1. Set **Reformatter** from `PEP8` (default) to `Black`.
  84
  85 ### Project Properties
  86
  87 If you want to just reformat for a specific project and not intervene with Wing IDE
  88 global setting, follow these steps:
  89
  90 1. In menubar navigate to `Project -> Project Properties -> Options`.
  91
  92 1. Set **Auto-Reformat** from `Use Preferences setting` (default) to `Line after edit`
  93    or `Whole files before save`.
  94
  95 1. Set **Reformatter** from `Use Preferences setting` (default) to `Black`.
  96
  97 ## Vim
  98
  99 ### Official plugin
 100
 101 Commands and shortcuts:
 102
 103 - `:Black` to format the entire file (ranges not supported);
 104   - you can optionally pass `target_version=<version>` with the same values as in the
 105     command line.
 106 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
 107 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
 108
 109 Configuration:
 110
 111 - `g:black_fast` (defaults to `0`)
 112 - `g:black_linelength` (defaults to `88`)
 113 - `g:black_skip_string_normalization` (defaults to `0`)
 114 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 115 - `g:black_quiet` (defaults to `0`)
 116
 117 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 118
 119 ```
 120 Plug 'psf/black', { 'branch': 'stable' }
 121 ```
 122
 123 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 124
 125 ```
 126 Plugin 'psf/black'
 127 ```
 128
 129 and execute the following in a terminal:
 130
 131 ```console
 132 $ cd ~/.vim/bundle/black
 133 $ git checkout origin/stable -b stable
 134 ```
 135
 136 or you can copy the plugin files from
 137 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and
 138 [autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim).
 139
 140 ```
 141 mkdir -p ~/.vim/pack/python/start/black/plugin
 142 mkdir -p ~/.vim/pack/python/start/black/autoload
 143 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
 144 curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim
 145 ```
 146
 147 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 148 Pathogen, and so on.
 149
 150 This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
 151 be able to run _Black_ inside the Vim process which is much faster than calling an
 152 external command.
 153
 154 On first run, the plugin creates its own virtualenv using the right Python version and
 155 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
 156 restarting Vim.
 157
 158 If you need to do anything special to make your virtualenv work and install _Black_ (for
 159 example you want to run a version from main), create a virtualenv manually and point
 160 `g:black_virtualenv` to it. The plugin will use it.
 161
 162 To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
 163
 164 ```
 165 augroup black_on_save
 166   autocmd!
 167   autocmd BufWritePre *.py Black
 168 augroup end
 169 ```
 170
 171 To run _Black_ on a key press (e.g. F9 below), add this:
 172
 173 ```
 174 nnoremap <F9> :Black<CR>
 175 ```
 176
 177 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
 178 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
 179 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
 180 this.
 181
 182 **I get an import error when using _Black_ from a virtual environment**: If you get an
 183 error message like this:
 184
 185 ```text
 186 Traceback (most recent call last):
 187   File "<string>", line 63, in <module>
 188   File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
 189     from typed_ast import ast3, ast27
 190   File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
 191     from typed_ast import _ast3
 192 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
 193 ```
 194
 195 Then you need to install `typed_ast` directly from the source code. The error happens
 196 because `pip` will download [Python wheels](https://pythonwheels.com/) if they are
 197 available. Python wheels are a new standard of distributing Python packages and packages
 198 that have Cython and extensions written in C are already compiled, so the installation
 199 is much more faster. The problem here is that somehow the Python environment inside Vim
 200 does not match with those already compiled C extensions and these kind of errors are the
 201 result. Luckily there is an easy fix: installing the packages from the source code.
 202
 203 The package that causes problems is:
 204
 205 - [typed-ast](https://pypi.org/project/typed-ast/)
 206
 207 Now remove those two packages:
 208
 209 ```console
 210 $ pip uninstall typed-ast -y
 211 ```
 212
 213 And now you can install them with:
 214
 215 ```console
 216 $ pip install --no-binary :all: typed-ast
 217 ```
 218
 219 The C extensions will be compiled and now Vim's Python environment will match. Note that
 220 you need to have the GCC compiler and the Python development files installed (on
 221 Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
 222
 223 If you later want to update _Black_, you should do it like this:
 224
 225 ```console
 226 $ pip install -U black --no-binary typed-ast
 227 ```
 228
 229 ### With ALE
 230
 231 1. Install [`ale`](https://github.com/dense-analysis/ale)
 232
 233 1. Install `black`
 234
 235 1. Add this to your vimrc:
 236
 237    ```vim
 238    let g:ale_fixers = {}
 239    let g:ale_fixers.python = ['black']
 240    ```
 241
 242 ## Gedit
 243
 244 gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
 245 as
 246
 247 ```console
 248 $ gedit <file_name>
 249 ```
 250
 251 1. `Go to edit > preferences > plugins`
 252 1. Search for `external tools` and activate it.
 253 1. In `Tools menu -> Manage external tools`
 254 1. Add a new tool using `+` button.
 255 1. Copy the below content to the code window.
 256
 257 ```console
 258 #!/bin/bash
 259 Name=$GEDIT_CURRENT_DOCUMENT_NAME
 260 black $Name
 261 ```
 262
 263 - Set a keyboard shortcut if you like, Ex. `ctrl-B`
 264 - Save: `Nothing`
 265 - Input: `Nothing`
 266 - Output: `Display in bottom pane` if you like.
 267 - Change the name of the tool if you like.
 268
 269 Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
 270 close and reopen your File, _Black_ will be done with its job.
 271
 272 ## Visual Studio Code
 273
 274 - Use the
 275   [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
 276   ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
 277
 278 - Alternatively the pre-release
 279   [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)
 280   extension can be used which runs a [Language Server Protocol](https://langserver.org/)
 281   server for Black. Formatting is much more responsive using this extension, **but the
 282   minimum supported version of Black is 22.3.0**.
 283
 284 ## SublimeText 3
 285
 286 Use [sublack plugin](https://github.com/jgirardet/sublack).
 287
 288 ## Python LSP Server
 289
 290 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 291 Sublime Text, Visual Studio Code and many more), you can use the
 292 [Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
 293 [python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
 294
 295 ## Atom/Nuclide
 296
 297 Use [python-black](https://atom.io/packages/python-black) or
 298 [formatters-python](https://atom.io/packages/formatters-python).
 299
 300 ## Gradle (the build tool)
 301
 302 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
 303
 304 ## Kakoune
 305
 306 Add the following hook to your kakrc, then run _Black_ with `:format`.
 307
 308 ```
 309 hook global WinSetOption filetype=python %{
 310     set-option window formatcmd 'black -q  -'
 311 }
 312 ```
 313
 314 ## Thonny
 315
 316 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).