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