]> git.madduck.net Git - etc/vim.git/blob - docs/editor_integration.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:

aa3a1eeedec32d2dcce31bbcf89313834e78c048
[etc/vim.git] / docs / editor_integration.md
1 # Editor integration
2
3 ## Emacs
4
5 Options include the following:
6
7 - [purcell/reformatter.el](https://github.com/purcell/reformatter.el)
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`.
14
15 ```console
16 $ pip install black
17 ```
18
19 2. Locate your `black` installation folder.
20
21 On macOS / Linux / BSD:
22
23 ```console
24 $ which black
25 /usr/local/bin/black  # possible location
26 ```
27
28 On Windows:
29
30 ```console
31 $ where black
32 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
33 ```
34
35 Note that if you are using a virtual environment detected by PyCharm, this is an
36 unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
37
38 3. Open External tools in PyCharm/IntelliJ IDEA
39
40 On macOS:
41
42 `PyCharm -> Preferences -> Tools -> External Tools`
43
44 On Windows / Linux / BSD:
45
46 `File -> Settings -> Tools -> External Tools`
47
48 4. Click the + icon to add a new external tool with the following values:
49
50    - Name: Black
51    - Description: Black is the uncompromising Python code formatter.
52    - Program: <install_location_from_step_2>
53    - Arguments: `"$FilePath$"`
54
55 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
56
57    - Alternatively, you can set a keyboard shortcut by navigating to
58      `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
59
60 6. Optionally, run _Black_ on every file save:
61
62    1. Make sure you have the
63       [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
64       installed.
65    2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
66       new watcher:
67       - Name: Black
68       - File type: Python
69       - Scope: Project Files
70       - Program: <install_location_from_step_2>
71       - Arguments: `$FilePath$`
72       - Output paths to refresh: `$FilePath$`
73       - Working directory: `$ProjectFileDir$`
74
75    - In Advanced Options
76      - Uncheck "Auto-save edited files to trigger the watcher"
77      - Uncheck "Trigger the watcher on external changes"
78
79 ## Wing IDE
80
81 Wing supports black via the OS Commands tool, as explained in the Wing documentation on
82 [pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
83
84 1. Install `black`.
85
86 ```console
87 $ pip install black
88 ```
89
90 2. Make sure it runs from the command line, e.g.
91
92 ```console
93 $ black --help
94 ```
95
96 3. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
97    execute black on the currently selected file:
98
99 - Use the Tools -> OS Commands menu selection
100 - click on **+** in **OS Commands** -> New: Command line..
101   - Title: black
102   - Command Line: black %s
103   - I/O Encoding: Use Default
104   - Key Binding: F1
105   - [x] Raise OS Commands when executed
106   - [x] Auto-save files before execution
107   - [x] Line mode
108
109 4. Select a file in the editor and press **F1** , or whatever key binding you selected
110    in step 3, to reformat the file.
111
112 ## Vim
113
114 Commands and shortcuts:
115
116 - `:Black` to format the entire file (ranges not supported);
117 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
118 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
119
120 Configuration:
121
122 - `g:black_fast` (defaults to `0`)
123 - `g:black_linelength` (defaults to `88`)
124 - `g:black_skip_string_normalization` (defaults to `0`)
125 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
126 - `g:black_quiet` (defaults to `0`)
127
128 To install with [vim-plug](https://github.com/junegunn/vim-plug):
129
130 ```
131 Plug 'psf/black', { 'branch': 'stable' }
132 ```
133
134 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
135
136 ```
137 Plugin 'psf/black'
138 ```
139
140 and execute the following in a terminal:
141
142 ```console
143 $ cd ~/.vim/bundle/black
144 $ git checkout origin/stable -b stable
145 ```
146
147 or you can copy the plugin from
148 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
149
150 ```
151 mkdir -p ~/.vim/pack/python/start/black/plugin
152 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
153 ```
154
155 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
156 Pathogen, and so on.
157
158 This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
159 be able to run _Black_ inside the Vim process which is much faster than calling an
160 external command.
161
162 On first run, the plugin creates its own virtualenv using the right Python version and
163 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
164 restarting Vim.
165
166 If you need to do anything special to make your virtualenv work and install _Black_ (for
167 example you want to run a version from master), create a virtualenv manually and point
168 `g:black_virtualenv` to it. The plugin will use it.
169
170 To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
171
172 ```
173 autocmd BufWritePre *.py execute ':Black'
174 ```
175
176 To run _Black_ on a key press (e.g. F9 below), add this:
177
178 ```
179 nnoremap <F9> :Black<CR>
180 ```
181
182 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
183 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
184 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
185 this.
186
187 **I get an import error when using _Black_ from a virtual environment**: If you get an
188 error message like this:
189
190 ```text
191 Traceback (most recent call last):
192   File "<string>", line 63, in <module>
193   File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
194     from typed_ast import ast3, ast27
195   File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
196     from typed_ast import _ast3
197 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
198 ```
199
200 Then you need to install `typed_ast` and `regex` directly from the source code. The
201 error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if
202 they are available. Python wheels are a new standard of distributing Python packages and
203 packages that have Cython and extensions written in C are already compiled, so the
204 installation is much more faster. The problem here is that somehow the Python
205 environment inside Vim does not match with those already compiled C extensions and these
206 kind of errors are the result. Luckily there is an easy fix: installing the packages
207 from the source code.
208
209 The two packages that cause the problem are:
210
211 - [regex](https://pypi.org/project/regex/)
212 - [typed-ast](https://pypi.org/project/typed-ast/)
213
214 Now remove those two packages:
215
216 ```console
217 $ pip uninstall regex typed-ast -y
218 ```
219
220 And now you can install them with:
221
222 ```console
223 $ pip install --no-binary :all: regex typed-ast
224 ```
225
226 The C extensions will be compiled and now Vim's Python environment will match. Note that
227 you need to have the GCC compiler and the Python development files installed (on
228 Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
229
230 If you later want to update _Black_, you should do it like this:
231
232 ```console
233 $ pip install -U black --no-binary regex,typed-ast
234 ```
235
236 ## Gedit
237
238 gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
239 as
240
241 ```console
242 $ gedit <file_name>
243 ```
244
245 1. `Go to edit > preferences > plugins`
246 2. Search for `external tools` and activate it.
247 3. In `Tools menu -> Manage external tools`
248 4. Add a new tool using `+` button.
249 5. Copy the below content to the code window.
250
251 ```console
252 #!/bin/bash
253 Name=$GEDIT_CURRENT_DOCUMENT_NAME
254 black $Name
255 ```
256
257 - Set a keyboard shortcut if you like, Ex. `ctrl-B`
258 - Save: `Nothing`
259 - Input: `Nothing`
260 - Output: `Display in bottom pane` if you like.
261 - Change the name of the tool if you like.
262
263 Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
264 close and reopen your File, _Black_ will be done with its job.
265
266 ## Visual Studio Code
267
268 Use the
269 [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
270 ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
271
272 ## SublimeText 3
273
274 Use [sublack plugin](https://github.com/jgirardet/sublack).
275
276 ## Jupyter Notebook Magic
277
278 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
279
280 ## Python Language Server
281
282 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
283 Sublime Text, Visual Studio Code and many more), you can use the
284 [Python Language Server](https://github.com/palantir/python-language-server) with the
285 [pyls-black](https://github.com/rupert/pyls-black) plugin.
286
287 ## Atom/Nuclide
288
289 Use [python-black](https://atom.io/packages/python-black).
290
291 ## Gradle (the build tool)
292
293 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
294
295 ## Kakoune
296
297 Add the following hook to your kakrc, then run _Black_ with `:format`.
298
299 ```
300 hook global WinSetOption filetype=python %{
301     set-option window formatcmd 'black -q  -'
302 }
303 ```
304
305 ## Thonny
306
307 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).
308
309 ## Other integrations
310
311 Other editors and tools will require external contributions.
312
313 Patches welcome! ✨ 🍰 ✨
314
315 Any tool that can pipe code through _Black_ using its stdio mode (just
316 [use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
317 The formatted code will be returned on stdout (unless `--check` was passed). _Black_
318 will still emit messages on stderr but that shouldn't affect your use case.
319
320 This can be used for example with PyCharm's or IntelliJ's
321 [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).