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

Include mode information for unstable formattings
[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    - Uncheck "Auto-save edited files to trigger the watcher" in Advanced Options
76
77 ## Wing IDE
78
79 Wing supports black via the OS Commands tool, as explained in the Wing documentation on
80 [pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
81
82 1. Install `black`.
83
84 ```console
85 $ pip install black
86 ```
87
88 2. Make sure it runs from the command line, e.g.
89
90 ```console
91 $ black --help
92 ```
93
94 3. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
95    execute black on the currently selected file:
96
97 - Use the Tools -> OS Commands menu selection
98 - click on **+** in **OS Commands** -> New: Command line..
99   - Title: black
100   - Command Line: black %s
101   - I/O Encoding: Use Default
102   - Key Binding: F1
103   - [x] Raise OS Commands when executed
104   - [x] Auto-save files before execution
105   - [x] Line mode
106
107 4. Select a file in the editor and press **F1** , or whatever key binding you selected
108    in step 3, to reformat the file.
109
110 ## Vim
111
112 Commands and shortcuts:
113
114 - `:Black` to format the entire file (ranges not supported);
115 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
116 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
117
118 Configuration:
119
120 - `g:black_fast` (defaults to `0`)
121 - `g:black_linelength` (defaults to `88`)
122 - `g:black_skip_string_normalization` (defaults to `0`)
123 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
124
125 To install with [vim-plug](https://github.com/junegunn/vim-plug):
126
127 ```
128 Plug 'psf/black', { 'branch': 'stable' }
129 ```
130
131 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
132
133 ```
134 Plugin 'psf/black'
135 ```
136
137 and execute the following in a terminal:
138
139 ```console
140 $ cd ~/.vim/bundle/black
141 $ git checkout origin/stable -b stable
142 ```
143
144 or you can copy the plugin from
145 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
146
147 ```
148 mkdir -p ~/.vim/pack/python/start/black/plugin
149 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
150 ```
151
152 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
153 Pathogen, and so on.
154
155 This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
156 be able to run _Black_ inside the Vim process which is much faster than calling an
157 external command.
158
159 On first run, the plugin creates its own virtualenv using the right Python version and
160 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
161 restarting Vim.
162
163 If you need to do anything special to make your virtualenv work and install _Black_ (for
164 example you want to run a version from master), create a virtualenv manually and point
165 `g:black_virtualenv` to it. The plugin will use it.
166
167 To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
168
169 ```
170 autocmd BufWritePre *.py execute ':Black'
171 ```
172
173 To run _Black_ on a key press (e.g. F9 below), add this:
174
175 ```
176 nnoremap <F9> :Black<CR>
177 ```
178
179 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
180 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
181 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
182 this.
183
184 **I get an import error when using _Black_ from a virtual environment**: If you get an
185 error message like this:
186
187 ```text
188 Traceback (most recent call last):
189   File "<string>", line 63, in <module>
190   File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
191     from typed_ast import ast3, ast27
192   File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
193     from typed_ast import _ast3
194 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
195 ```
196
197 Then you need to install `typed_ast` and `regex` directly from the source code. The
198 error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if
199 they are available. Python wheels are a new standard of distributing Python packages and
200 packages that have Cython and extensions written in C are already compiled, so the
201 installation is much more faster. The problem here is that somehow the Python
202 environment inside Vim does not match with those already compiled C extensions and these
203 kind of errors are the result. Luckily there is an easy fix: installing the packages
204 from the source code.
205
206 The two packages that cause the problem are:
207
208 - [regex](https://pypi.org/project/regex/)
209 - [typed-ast](https://pypi.org/project/typed-ast/)
210
211 Now remove those two packages:
212
213 ```console
214 $ pip uninstall regex typed-ast -y
215 ```
216
217 And now you can install them with:
218
219 ```console
220 $ pip install --no-binary :all: regex typed-ast
221 ```
222
223 The C extensions will be compiled and now Vim's Python environment will match. Note that
224 you need to have the GCC compiler and the Python development files installed (on
225 Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
226
227 If you later want to update _Black_, you should do it like this:
228
229 ```console
230 $ pip install -U black --no-binary regex,typed-ast
231 ```
232
233 ## Visual Studio Code
234
235 Use the
236 [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
237 ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
238
239 ## SublimeText 3
240
241 Use [sublack plugin](https://github.com/jgirardet/sublack).
242
243 ## Jupyter Notebook Magic
244
245 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
246
247 ## Python Language Server
248
249 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
250 Sublime Text, Visual Studio Code and many more), you can use the
251 [Python Language Server](https://github.com/palantir/python-language-server) with the
252 [pyls-black](https://github.com/rupert/pyls-black) plugin.
253
254 ## Atom/Nuclide
255
256 Use [python-black](https://atom.io/packages/python-black).
257
258 ## Gradle (the build tool)
259
260 Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugin.
261
262 ## Kakoune
263
264 Add the following hook to your kakrc, then run _Black_ with `:format`.
265
266 ```
267 hook global WinSetOption filetype=python %{
268     set-option window formatcmd 'black -q  -'
269 }
270 ```
271
272 ## Thonny
273
274 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).
275
276 ## Other integrations
277
278 Other editors and tools will require external contributions.
279
280 Patches welcome! ✨ 🍰 ✨
281
282 Any tool that can pipe code through _Black_ using its stdio mode (just
283 [use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
284 The formatted code will be returned on stdout (unless `--check` was passed). _Black_
285 will still emit messages on stderr but that shouldn't affect your use case.
286
287 This can be used for example with PyCharm's or IntelliJ's
288 [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).