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

blackd: fix mishandling of single character input (#3558)
[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 ### 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).