]> git.madduck.net Git - etc/vim.git/blob - docs/integrations/editors.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

83904144c4887c0fc39282c25303183d24884524
[etc/vim.git] / 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/editing#_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).