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