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

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