]> 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:

Draft for Black 2023 stable style (#3418)
[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 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 #### Troubleshooting
338
339 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
340 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
341 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
342 this.
343
344 **I get an import error when using _Black_ from a virtual environment**: If you get an
345 error message like this:
346
347 ```text
348 Traceback (most recent call last):
349   File "<string>", line 63, in <module>
350   File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
351     from typed_ast import ast3, ast27
352   File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
353     from typed_ast import _ast3
354 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
355 ```
356
357 Then you need to install `typed_ast` directly from the source code. The error happens
358 because `pip` will download [Python wheels](https://pythonwheels.com/) if they are
359 available. Python wheels are a new standard of distributing Python packages and packages
360 that have Cython and extensions written in C are already compiled, so the installation
361 is much more faster. The problem here is that somehow the Python environment inside Vim
362 does not match with those already compiled C extensions and these kind of errors are the
363 result. Luckily there is an easy fix: installing the packages from the source code.
364
365 The package that causes problems is:
366
367 - [typed-ast](https://pypi.org/project/typed-ast/)
368
369 Now remove those two packages:
370
371 ```console
372 $ pip uninstall typed-ast -y
373 ```
374
375 And now you can install them with:
376
377 ```console
378 $ pip install --no-binary :all: typed-ast
379 ```
380
381 The C extensions will be compiled and now Vim's Python environment will match. Note that
382 you need to have the GCC compiler and the Python development files installed (on
383 Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
384
385 If you later want to update _Black_, you should do it like this:
386
387 ```console
388 $ pip install -U black --no-binary typed-ast
389 ```
390
391 ### With ALE
392
393 1. Install [`ale`](https://github.com/dense-analysis/ale)
394
395 1. Install `black`
396
397 1. Add this to your vimrc:
398
399    ```vim
400    let g:ale_fixers = {}
401    let g:ale_fixers.python = ['black']
402    ```
403
404 ## Gedit
405
406 gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
407 as
408
409 ```console
410 $ gedit <file_name>
411 ```
412
413 1. `Go to edit > preferences > plugins`
414 1. Search for `external tools` and activate it.
415 1. In `Tools menu -> Manage external tools`
416 1. Add a new tool using `+` button.
417 1. Copy the below content to the code window.
418
419 ```console
420 #!/bin/bash
421 Name=$GEDIT_CURRENT_DOCUMENT_NAME
422 black $Name
423 ```
424
425 - Set a keyboard shortcut if you like, Ex. `ctrl-B`
426 - Save: `Nothing`
427 - Input: `Nothing`
428 - Output: `Display in bottom pane` if you like.
429 - Change the name of the tool if you like.
430
431 Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
432 close and reopen your File, _Black_ will be done with its job.
433
434 ## Visual Studio Code
435
436 - Use the
437   [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
438   ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
439
440 - Alternatively the pre-release
441   [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)
442   extension can be used which runs a [Language Server Protocol](https://langserver.org/)
443   server for Black. Formatting is much more responsive using this extension, **but the
444   minimum supported version of Black is 22.3.0**.
445
446 ## SublimeText 3
447
448 Use [sublack plugin](https://github.com/jgirardet/sublack).
449
450 ## Python LSP Server
451
452 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
453 Sublime Text, Visual Studio Code and many more), you can use the
454 [Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
455 [python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
456
457 ## Atom/Nuclide
458
459 Use [python-black](https://atom.io/packages/python-black) or
460 [formatters-python](https://atom.io/packages/formatters-python).
461
462 ## Gradle (the build tool)
463
464 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
465
466 ## Kakoune
467
468 Add the following hook to your kakrc, then run _Black_ with `:format`.
469
470 ```
471 hook global WinSetOption filetype=python %{
472     set-option window formatcmd 'black -q  -'
473 }
474 ```
475
476 ## Thonny
477
478 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).