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

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