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).