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

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