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 There are three different ways you can use _Black_ from PyCharm:
  14
  15 1. As local server using the BlackConnect plugin
  16 1. As external tool
  17 1. As file watcher
  18
  19 The first option is the simplest to set up and formats the fastest (by spinning up
  20 {doc}`Black's HTTP server </usage_and_configuration/black_as_a_server>`, avoiding the
  21 startup cost on subsequent formats), but if you would prefer to not install a
  22 third-party plugin or blackd's extra dependencies, the other two are also great options.
  23
  24 ### As local server
  25
  26 1. Install _Black_ with the `d` extra.
  27
  28    ```console
  29    $ pip install 'black[d]'
  30    ```
  31
  32 1. Install
  33    [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect).
  34
  35 1. Open plugin configuration in PyCharm/IntelliJ IDEA
  36
  37    On macOS:
  38
  39    `PyCharm -> Preferences -> Tools -> BlackConnect`
  40
  41    On Windows / Linux / BSD:
  42
  43    `File -> Settings -> Tools -> BlackConnect`
  44
  45 1. In `Local Instance (shared between projects)` section:
  46
  47    1. Check `Start local blackd instance when plugin loads`.
  48    1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
  49       executable.
  50
  51 1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
  52    reformatting with _Black_.
  53
  54 1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
  55    shortcut.
  56
  57 1. Optionally, to run _Black_ on every file save:
  58
  59    - In `Trigger Settings` section of plugin configuration check
  60      `Trigger when saving changed files`.
  61
  62 ### As external tool
  63
  64 1. Install `black`.
  65
  66    ```console
  67    $ pip install black
  68    ```
  69
  70 1. Locate your `black` installation folder.
  71
  72    On macOS / Linux / BSD:
  73
  74    ```console
  75    $ which black
  76    /usr/local/bin/black  # possible location
  77    ```
  78
  79    On Windows:
  80
  81    ```console
  82    $ where black
  83    %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
  84    ```
  85
  86    Note that if you are using a virtual environment detected by PyCharm, this is an
  87    unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
  88
  89 1. Open External tools in PyCharm/IntelliJ IDEA
  90
  91    On macOS:
  92
  93    `PyCharm -> Preferences -> Tools -> External Tools`
  94
  95    On Windows / Linux / BSD:
  96
  97    `File -> Settings -> Tools -> External Tools`
  98
  99 1. Click the + icon to add a new external tool with the following values:
 100
 101    - Name: Black
 102    - Description: Black is the uncompromising Python code formatter.
 103    - Program: \<install_location_from_step_2>
 104    - Arguments: `"$FilePath$"`
 105
 106 1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
 107
 108    - Alternatively, you can set a keyboard shortcut by navigating to
 109      `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
 110
 111 ### As file watcher
 112
 113 1. Install `black`.
 114
 115    ```console
 116    $ pip install black
 117    ```
 118
 119 1. Locate your `black` installation folder.
 120
 121    On macOS / Linux / BSD:
 122
 123    ```console
 124    $ which black
 125    /usr/local/bin/black  # possible location
 126    ```
 127
 128    On Windows:
 129
 130    ```console
 131    $ where black
 132    %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
 133    ```
 134
 135    Note that if you are using a virtual environment detected by PyCharm, this is an
 136    unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
 137
 138 1. Make sure you have the
 139    [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
 140    installed.
 141 1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a new
 142    watcher:
 143    - Name: Black
 144    - File type: Python
 145    - Scope: Project Files
 146    - Program: \<install_location_from_step_2>
 147    - Arguments: `$FilePath$`
 148    - Output paths to refresh: `$FilePath$`
 149    - Working directory: `$ProjectFileDir$`
 150
 151 - In Advanced Options
 152   - Uncheck "Auto-save edited files to trigger the watcher"
 153   - Uncheck "Trigger the watcher on external changes"
 154
 155 ## Wing IDE
 156
 157 Wing IDE supports `black` via **Preference Settings** for system wide settings and
 158 **Project Properties** for per-project or workspace specific settings, as explained in
 159 the Wing documentation on
 160 [Auto-Reformatting](https://wingware.com/doc/edit/auto-reformatting). The detailed
 161 procedure is:
 162
 163 ### Prerequistes
 164
 165 - Wing IDE version 8.0+
 166
 167 - Install `black`.
 168
 169   ```console
 170   $ pip install black
 171   ```
 172
 173 - Make sure it runs from the command line, e.g.
 174
 175   ```console
 176   $ black --help
 177   ```
 178
 179 ### Preference Settings
 180
 181 If you want Wing IDE to always reformat with `black` for every project, follow these
 182 steps:
 183
 184 1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
 185
 186 1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
 187    `Whole files before save`.
 188
 189 1. Set **Reformatter** from `PEP8` (default) to `Black`.
 190
 191 ### Project Properties
 192
 193 If you want to just reformat for a specific project and not intervene with Wing IDE
 194 global setting, follow these steps:
 195
 196 1. In menubar navigate to `Project -> Project Properties -> Options`.
 197
 198 1. Set **Auto-Reformat** from `Use Preferences setting` (default) to `Line after edit`
 199    or `Whole files before save`.
 200
 201 1. Set **Reformatter** from `Use Preferences setting` (default) to `Black`.
 202
 203 ## Vim
 204
 205 ### Official plugin
 206
 207 Commands and shortcuts:
 208
 209 - `:Black` to format the entire file (ranges not supported);
 210   - you can optionally pass `target_version=<version>` with the same values as in the
 211     command line.
 212 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
 213 - `:BlackVersion` to get the current version of _Black_ in use.
 214
 215 Configuration:
 216
 217 - `g:black_fast` (defaults to `0`)
 218 - `g:black_linelength` (defaults to `88`)
 219 - `g:black_skip_string_normalization` (defaults to `0`)
 220 - `g:black_skip_magic_trailing_comma` (defaults to `0`)
 221 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 222 - `g:black_use_virtualenv` (defaults to `1`)
 223 - `g:black_target_version` (defaults to `""`)
 224 - `g:black_quiet` (defaults to `0`)
 225 - `g:black_preview` (defaults to `0`)
 226
 227 #### Installation
 228
 229 This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to
 230 be able to run _Black_ inside the Vim process which is much faster than calling an
 231 external command.
 232
 233 ##### `vim-plug`
 234
 235 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 236
 237 _Black_'s `stable` branch tracks official version updates, and can be used to simply
 238 follow the most recent stable version.
 239
 240 ```
 241 Plug 'psf/black', { 'branch': 'stable' }
 242 ```
 243
 244 Another option which is a bit more explicit and offers more control is to use
 245 `vim-plug`'s `tag` option with a shell wildcard. This will resolve to the latest tag
 246 which matches the given pattern.
 247
 248 The following matches all stable versions (see the
 249 [Release Process](../contributing/release_process.md) section for documentation of
 250 version scheme used by Black):
 251
 252 ```
 253 Plug 'psf/black', { 'tag': '*.*.*' }
 254 ```
 255
 256 and the following demonstrates pinning to a specific year's stable style (2022 in this
 257 case):
 258
 259 ```
 260 Plug 'psf/black', { 'tag': '22.*.*' }
 261 ```
 262
 263 ##### Vundle
 264
 265 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 266
 267 ```
 268 Plugin 'psf/black'
 269 ```
 270
 271 and execute the following in a terminal:
 272
 273 ```console
 274 $ cd ~/.vim/bundle/black
 275 $ git checkout origin/stable -b stable
 276 ```
 277
 278 ##### Arch Linux
 279
 280 On Arch Linux, the plugin is shipped with the
 281 [`python-black`](https://archlinux.org/packages/community/any/python-black/) package, so
 282 you can start using it in Vim after install with no additional setup.
 283
 284 ##### Vim 8 Native Plugin Management
 285
 286 or you can copy the plugin files from
 287 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and
 288 [autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim).
 289
 290 ```
 291 mkdir -p ~/.vim/pack/python/start/black/plugin
 292 mkdir -p ~/.vim/pack/python/start/black/autoload
 293 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
 294 curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim
 295 ```
 296
 297 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 298 Pathogen, and so on.
 299
 300 #### Usage
 301
 302 On first run, the plugin creates its own virtualenv using the right Python version and
 303 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
 304 restarting Vim.
 305
 306 If you need to do anything special to make your virtualenv work and install _Black_ (for
 307 example you want to run a version from main), create a virtualenv manually and point
 308 `g:black_virtualenv` to it. The plugin will use it.
 309
 310 If you would prefer to use the system installation of _Black_ rather than a virtualenv,
 311 then add this to your vimrc:
 312
 313 ```
 314 let g:black_use_virtualenv = 0
 315 ```
 316
 317 Note that the `:BlackUpgrade` command is only usable and useful with a virtualenv, so
 318 when the virtualenv is not in use, `:BlackUpgrade` is disabled. If you need to upgrade
 319 the system installation of _Black_, then use your system package manager or pip--
 320 whatever tool you used to install _Black_ originally.
 321
 322 To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
 323
 324 ```
 325 augroup black_on_save
 326   autocmd!
 327   autocmd BufWritePre *.py Black
 328 augroup end
 329 ```
 330
 331 To run _Black_ on a key press (e.g. F9 below), add this:
 332
 333 ```
 334 nnoremap <F9> :Black<CR>
 335 ```
 336
 337 ### With ALE
 338
 339 1. Install [`ale`](https://github.com/dense-analysis/ale)
 340
 341 1. Install `black`
 342
 343 1. Add this to your vimrc:
 344
 345    ```vim
 346    let g:ale_fixers = {}
 347    let g:ale_fixers.python = ['black']
 348    ```
 349
 350 ## Gedit
 351
 352 gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
 353 as
 354
 355 ```console
 356 $ gedit <file_name>
 357 ```
 358
 359 1. `Go to edit > preferences > plugins`
 360 1. Search for `external tools` and activate it.
 361 1. In `Tools menu -> Manage external tools`
 362 1. Add a new tool using `+` button.
 363 1. Copy the below content to the code window.
 364
 365 ```console
 366 #!/bin/bash
 367 Name=$GEDIT_CURRENT_DOCUMENT_NAME
 368 black $Name
 369 ```
 370
 371 - Set a keyboard shortcut if you like, Ex. `ctrl-B`
 372 - Save: `Nothing`
 373 - Input: `Nothing`
 374 - Output: `Display in bottom pane` if you like.
 375 - Change the name of the tool if you like.
 376
 377 Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
 378 close and reopen your File, _Black_ will be done with its job.
 379
 380 ## Visual Studio Code
 381
 382 - Use the
 383   [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
 384   ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
 385
 386 - Alternatively the pre-release
 387   [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)
 388   extension can be used which runs a [Language Server Protocol](https://langserver.org/)
 389   server for Black. Formatting is much more responsive using this extension, **but the
 390   minimum supported version of Black is 22.3.0**.
 391
 392 ## SublimeText 3
 393
 394 Use [sublack plugin](https://github.com/jgirardet/sublack).
 395
 396 ## Python LSP Server
 397
 398 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 399 Sublime Text, Visual Studio Code and many more), you can use the
 400 [Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
 401 [python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
 402
 403 ## Atom/Nuclide
 404
 405 Use [python-black](https://atom.io/packages/python-black) or
 406 [formatters-python](https://atom.io/packages/formatters-python).
 407
 408 ## Gradle (the build tool)
 409
 410 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
 411
 412 ## Kakoune
 413
 414 Add the following hook to your kakrc, then run _Black_ with `:format`.
 415
 416 ```
 417 hook global WinSetOption filetype=python %{
 418     set-option window formatcmd 'black -q  -'
 419 }
 420 ```
 421
 422 ## Thonny
 423
 424 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).