X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/06ccb88bf2bd35a4dc5d591bb296b5b299d07323..0e26ada66d16d2aea97bda5f907bb0b20b0985e7:/docs/integrations/editors.md?ds=sidebyside diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md index 88176e1..ff56306 100644 --- a/docs/integrations/editors.md +++ b/docs/integrations/editors.md @@ -10,6 +10,57 @@ Options include the following: ## PyCharm/IntelliJ IDEA +There are three different ways you can use _Black_ from PyCharm: + +1. As local server using the BlackConnect plugin +1. As external tool +1. As file watcher + +The first option is the simplest to set up and formats the fastest (by spinning up +{doc}`Black's HTTP server `, avoiding the +startup cost on subsequent formats), but if you would prefer to not install a +third-party plugin or blackd's extra dependencies, the other two are also great options. + +### As local server + +1. Install _Black_ with the `d` extra. + + ```console + $ pip install 'black[d]' + ``` + +1. Install + [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect). + +1. Open plugin configuration in PyCharm/IntelliJ IDEA + + On macOS: + + `PyCharm -> Preferences -> Tools -> BlackConnect` + + On Windows / Linux / BSD: + + `File -> Settings -> Tools -> BlackConnect` + +1. In `Local Instance (shared between projects)` section: + + 1. Check `Start local blackd instance when plugin loads`. + 1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd` + executable. + +1. In `Trigger Settings` section check `Trigger on code reformat` to enable code + reformatting with _Black_. + +1. Format the currently opened file by selecting `Code -> Reformat Code` or using a + shortcut. + +1. Optionally, to run _Black_ on every file save: + + - In `Trigger Settings` section of plugin configuration check + `Trigger when saving changed files`. + +### As external tool + 1. Install `black`. ```console @@ -57,29 +108,7 @@ Options include the following: - Alternatively, you can set a keyboard shortcut by navigating to `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`. -1. Optionally, run _Black_ on every file save: - - 1. Make sure you have the - [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin - installed. - 1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a - new watcher: - - Name: Black - - File type: Python - - Scope: Project Files - - Program: \ - - Arguments: `$FilePath$` - - Output paths to refresh: `$FilePath$` - - Working directory: `$ProjectFileDir$` - - - In Advanced Options - - Uncheck "Auto-save edited files to trigger the watcher" - - Uncheck "Trigger the watcher on external changes" - -## Wing IDE - -Wing supports black via the OS Commands tool, as explained in the Wing documentation on -[pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is: +### As file watcher 1. Install `black`. @@ -87,27 +116,89 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta $ pip install black ``` -1. Make sure it runs from the command line, e.g. +1. Locate your `black` installation folder. + + On macOS / Linux / BSD: ```console - $ black --help + $ which black + /usr/local/bin/black # possible location ``` -1. In Wing IDE, activate the **OS Commands** panel and define the command **black** to - execute black on the currently selected file: + On Windows: + + ```console + $ where black + %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location + ``` + + Note that if you are using a virtual environment detected by PyCharm, this is an + unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`. + +1. Make sure you have the + [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin + installed. +1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a new + watcher: + - Name: Black + - File type: Python + - Scope: Project Files + - Program: \ + - Arguments: `$FilePath$` + - Output paths to refresh: `$FilePath$` + - Working directory: `$ProjectFileDir$` + +- In Advanced Options + - Uncheck "Auto-save edited files to trigger the watcher" + - Uncheck "Trigger the watcher on external changes" + +## Wing IDE + +Wing IDE supports `black` via **Preference Settings** for system wide settings and +**Project Properties** for per-project or workspace specific settings, as explained in +the Wing documentation on +[Auto-Reformatting](https://wingware.com/doc/edit/auto-reformatting). The detailed +procedure is: + +### Prerequistes + +- Wing IDE version 8.0+ + +- Install `black`. + + ```console + $ pip install black + ``` - - Use the Tools -> OS Commands menu selection - - click on **+** in **OS Commands** -> New: Command line.. - - Title: black - - Command Line: black %s - - I/O Encoding: Use Default - - Key Binding: F1 - - [x] Raise OS Commands when executed - - [x] Auto-save files before execution - - [x] Line mode +- Make sure it runs from the command line, e.g. -1. Select a file in the editor and press **F1** , or whatever key binding you selected - in step 3, to reformat the file. + ```console + $ black --help + ``` + +### Preference Settings + +If you want Wing IDE to always reformat with `black` for every project, follow these +steps: + +1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`. + +1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or + `Whole files before save`. + +1. Set **Reformatter** from `PEP8` (default) to `Black`. + +### Project Properties + +If you want to just reformat for a specific project and not intervene with Wing IDE +global setting, follow these steps: + +1. In menubar navigate to `Project -> Project Properties -> Options`. + +1. Set **Auto-Reformat** from `Use Preferences setting` (default) to `Line after edit` + or `Whole files before save`. + +1. Set **Reformatter** from `Use Preferences setting` (default) to `Black`. ## Vim @@ -116,23 +207,61 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta Commands and shortcuts: - `:Black` to format the entire file (ranges not supported); + - you can optionally pass `target_version=` with the same values as in the + command line. - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv; -- `:BlackVersion` to get the current version of _Black_ inside the virtualenv. +- `:BlackVersion` to get the current version of _Black_ in use. Configuration: - `g:black_fast` (defaults to `0`) - `g:black_linelength` (defaults to `88`) - `g:black_skip_string_normalization` (defaults to `0`) +- `g:black_skip_magic_trailing_comma` (defaults to `0`) - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`) +- `g:black_use_virtualenv` (defaults to `1`) +- `g:black_target_version` (defaults to `""`) - `g:black_quiet` (defaults to `0`) +- `g:black_preview` (defaults to `0`) + +#### Installation + +This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to +be able to run _Black_ inside the Vim process which is much faster than calling an +external command. + +##### `vim-plug` To install with [vim-plug](https://github.com/junegunn/vim-plug): +_Black_'s `stable` branch tracks official version updates, and can be used to simply +follow the most recent stable version. + ``` Plug 'psf/black', { 'branch': 'stable' } ``` +Another option which is a bit more explicit and offers more control is to use +`vim-plug`'s `tag` option with a shell wildcard. This will resolve to the latest tag +which matches the given pattern. + +The following matches all stable versions (see the +[Release Process](../contributing/release_process.md) section for documentation of +version scheme used by Black): + +``` +Plug 'psf/black', { 'tag': '*.*.*' } +``` + +and the following demonstrates pinning to a specific year's stable style (2022 in this +case): + +``` +Plug 'psf/black', { 'tag': '22.*.*' } +``` + +##### Vundle + or with [Vundle](https://github.com/VundleVim/Vundle.vim): ``` @@ -146,20 +275,29 @@ $ cd ~/.vim/bundle/black $ git checkout origin/stable -b stable ``` -or you can copy the plugin from -[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim). +##### Arch Linux + +On Arch Linux, the plugin is shipped with the +[`python-black`](https://archlinux.org/packages/community/any/python-black/) package, so +you can start using it in Vim after install with no additional setup. + +##### Vim 8 Native Plugin Management + +or you can copy the plugin files from +[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and +[autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim). ``` mkdir -p ~/.vim/pack/python/start/black/plugin +mkdir -p ~/.vim/pack/python/start/black/autoload curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim +curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim ``` Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or Pathogen, and so on. -This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to -be able to run _Black_ inside the Vim process which is much faster than calling an -external command. +#### Usage On first run, the plugin creates its own virtualenv using the right Python version and automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and @@ -169,70 +307,31 @@ If you need to do anything special to make your virtualenv work and install _Bla example you want to run a version from main), create a virtualenv manually and point `g:black_virtualenv` to it. The plugin will use it. -To run _Black_ on save, add the following line to `.vimrc` or `init.vim`: +If you would prefer to use the system installation of _Black_ rather than a virtualenv, +then add this to your vimrc: ``` -autocmd BufWritePre *.py execute ':Black' +let g:black_use_virtualenv = 0 ``` -To run _Black_ on a key press (e.g. F9 below), add this: +Note that the `:BlackUpgrade` command is only usable and useful with a virtualenv, so +when the virtualenv is not in use, `:BlackUpgrade` is disabled. If you need to upgrade +the system installation of _Black_, then use your system package manager or pip-- +whatever tool you used to install _Black_ originally. -``` -nnoremap :Black -``` +To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`: -**How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by -default. On macOS with Homebrew run: `brew install vim`. When building Vim from source, -use: `./configure --enable-python3interp=yes`. There's many guides online how to do -this. - -**I get an import error when using _Black_ from a virtual environment**: If you get an -error message like this: - -```text -Traceback (most recent call last): - File "", line 63, in - File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in - from typed_ast import ast3, ast27 - File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in - from typed_ast import _ast3 -ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt ``` - -Then you need to install `typed_ast` and `regex` directly from the source code. The -error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if -they are available. Python wheels are a new standard of distributing Python packages and -packages that have Cython and extensions written in C are already compiled, so the -installation is much more faster. The problem here is that somehow the Python -environment inside Vim does not match with those already compiled C extensions and these -kind of errors are the result. Luckily there is an easy fix: installing the packages -from the source code. - -The two packages that cause the problem are: - -- [regex](https://pypi.org/project/regex/) -- [typed-ast](https://pypi.org/project/typed-ast/) - -Now remove those two packages: - -```console -$ pip uninstall regex typed-ast -y +augroup black_on_save + autocmd! + autocmd BufWritePre *.py Black +augroup end ``` -And now you can install them with: +To run _Black_ on a key press (e.g. F9 below), add this: -```console -$ pip install --no-binary :all: regex typed-ast ``` - -The C extensions will be compiled and now Vim's Python environment will match. Note that -you need to have the GCC compiler and the Python development files installed (on -Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`). - -If you later want to update _Black_, you should do it like this: - -```console -$ pip install -U black --no-binary regex,typed-ast +nnoremap :Black ``` ### With ALE @@ -280,24 +379,26 @@ close and reopen your File, _Black_ will be done with its job. ## Visual Studio Code -Use the -[Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) -([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)). +- Use the + [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) + ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)). + +- Alternatively the pre-release + [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) + extension can be used which runs a [Language Server Protocol](https://langserver.org/) + server for Black. Formatting is much more responsive using this extension, **but the + minimum supported version of Black is 22.3.0**. ## SublimeText 3 Use [sublack plugin](https://github.com/jgirardet/sublack). -## Jupyter Notebook Magic - -Use [blackcellmagic](https://github.com/csurfer/blackcellmagic). - -## Python Language Server +## Python LSP Server If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom, Sublime Text, Visual Studio Code and many more), you can use the -[Python Language Server](https://github.com/palantir/python-language-server) with the -[pyls-black](https://github.com/rupert/pyls-black) plugin. +[Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the +[python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin. ## Atom/Nuclide