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