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

Add option to skip the first line of source code (#3299)
[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_ inside the virtualenv.
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_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
115 - `g:black_quiet` (defaults to `0`)
116 - `g:black_preview` (defaults to `0`)
117
118 To install with [vim-plug](https://github.com/junegunn/vim-plug):
119
120 ```
121 Plug 'psf/black', { 'branch': 'stable' }
122 ```
123
124 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
125
126 ```
127 Plugin 'psf/black'
128 ```
129
130 and execute the following in a terminal:
131
132 ```console
133 $ cd ~/.vim/bundle/black
134 $ git checkout origin/stable -b stable
135 ```
136
137 or you can copy the plugin files from
138 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and
139 [autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim).
140
141 ```
142 mkdir -p ~/.vim/pack/python/start/black/plugin
143 mkdir -p ~/.vim/pack/python/start/black/autoload
144 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
145 curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim
146 ```
147
148 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
149 Pathogen, and so on.
150
151 This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to
152 be able to run _Black_ inside the Vim process which is much faster than calling an
153 external command.
154
155 On first run, the plugin creates its own virtualenv using the right Python version and
156 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
157 restarting Vim.
158
159 If you need to do anything special to make your virtualenv work and install _Black_ (for
160 example you want to run a version from main), create a virtualenv manually and point
161 `g:black_virtualenv` to it. The plugin will use it.
162
163 To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
164
165 ```
166 augroup black_on_save
167   autocmd!
168   autocmd BufWritePre *.py Black
169 augroup end
170 ```
171
172 To run _Black_ on a key press (e.g. F9 below), add this:
173
174 ```
175 nnoremap <F9> :Black<CR>
176 ```
177
178 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
179 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
180 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
181 this.
182
183 **I get an import error when using _Black_ from a virtual environment**: If you get an
184 error message like this:
185
186 ```text
187 Traceback (most recent call last):
188   File "<string>", line 63, in <module>
189   File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
190     from typed_ast import ast3, ast27
191   File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
192     from typed_ast import _ast3
193 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
194 ```
195
196 Then you need to install `typed_ast` directly from the source code. The error happens
197 because `pip` will download [Python wheels](https://pythonwheels.com/) if they are
198 available. Python wheels are a new standard of distributing Python packages and packages
199 that have Cython and extensions written in C are already compiled, so the installation
200 is much more faster. The problem here is that somehow the Python environment inside Vim
201 does not match with those already compiled C extensions and these kind of errors are the
202 result. Luckily there is an easy fix: installing the packages from the source code.
203
204 The package that causes problems is:
205
206 - [typed-ast](https://pypi.org/project/typed-ast/)
207
208 Now remove those two packages:
209
210 ```console
211 $ pip uninstall typed-ast -y
212 ```
213
214 And now you can install them with:
215
216 ```console
217 $ pip install --no-binary :all: typed-ast
218 ```
219
220 The C extensions will be compiled and now Vim's Python environment will match. Note that
221 you need to have the GCC compiler and the Python development files installed (on
222 Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
223
224 If you later want to update _Black_, you should do it like this:
225
226 ```console
227 $ pip install -U black --no-binary typed-ast
228 ```
229
230 ### With ALE
231
232 1. Install [`ale`](https://github.com/dense-analysis/ale)
233
234 1. Install `black`
235
236 1. Add this to your vimrc:
237
238    ```vim
239    let g:ale_fixers = {}
240    let g:ale_fixers.python = ['black']
241    ```
242
243 ## Gedit
244
245 gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
246 as
247
248 ```console
249 $ gedit <file_name>
250 ```
251
252 1. `Go to edit > preferences > plugins`
253 1. Search for `external tools` and activate it.
254 1. In `Tools menu -> Manage external tools`
255 1. Add a new tool using `+` button.
256 1. Copy the below content to the code window.
257
258 ```console
259 #!/bin/bash
260 Name=$GEDIT_CURRENT_DOCUMENT_NAME
261 black $Name
262 ```
263
264 - Set a keyboard shortcut if you like, Ex. `ctrl-B`
265 - Save: `Nothing`
266 - Input: `Nothing`
267 - Output: `Display in bottom pane` if you like.
268 - Change the name of the tool if you like.
269
270 Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
271 close and reopen your File, _Black_ will be done with its job.
272
273 ## Visual Studio Code
274
275 - Use the
276   [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
277   ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
278
279 - Alternatively the pre-release
280   [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)
281   extension can be used which runs a [Language Server Protocol](https://langserver.org/)
282   server for Black. Formatting is much more responsive using this extension, **but the
283   minimum supported version of Black is 22.3.0**.
284
285 ## SublimeText 3
286
287 Use [sublack plugin](https://github.com/jgirardet/sublack).
288
289 ## Python LSP Server
290
291 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
292 Sublime Text, Visual Studio Code and many more), you can use the
293 [Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
294 [python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
295
296 ## Atom/Nuclide
297
298 Use [python-black](https://atom.io/packages/python-black) or
299 [formatters-python](https://atom.io/packages/formatters-python).
300
301 ## Gradle (the build tool)
302
303 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
304
305 ## Kakoune
306
307 Add the following hook to your kakrc, then run _Black_ with `:format`.
308
309 ```
310 hook global WinSetOption filetype=python %{
311     set-option window formatcmd 'black -q  -'
312 }
313 ```
314
315 ## Thonny
316
317 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).