X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/59f03d1b9d3c77f214087948b4d5e3dbb024d0b3..a062d5c9854205c4ae3f4cbe8859ed59bcd6259c:/docs/integrations/editors.md?ds=sidebyside diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md index a8b7978..ff56306 100644 --- a/docs/integrations/editors.md +++ b/docs/integrations/editors.md @@ -10,6 +10,19 @@ 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 @@ -46,6 +59,99 @@ Options include the following: - In `Trigger Settings` section of plugin configuration check `Trigger when saving changed files`. +### As external tool + +1. Install `black`. + + ```console + $ pip install black + ``` + +1. Locate your `black` installation folder. + + On macOS / Linux / BSD: + + ```console + $ which black + /usr/local/bin/black # possible location + ``` + + 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. Open External tools in PyCharm/IntelliJ IDEA + + On macOS: + + `PyCharm -> Preferences -> Tools -> External Tools` + + On Windows / Linux / BSD: + + `File -> Settings -> Tools -> External Tools` + +1. Click the + icon to add a new external tool with the following values: + + - Name: Black + - Description: Black is the uncompromising Python code formatter. + - Program: \ + - Arguments: `"$FilePath$"` + +1. Format the currently opened file by selecting `Tools -> External Tools -> black`. + + - Alternatively, you can set a keyboard shortcut by navigating to + `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`. + +### As file watcher + +1. Install `black`. + + ```console + $ pip install black + ``` + +1. Locate your `black` installation folder. + + On macOS / Linux / BSD: + + ```console + $ which black + /usr/local/bin/black # possible location + ``` + + 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 @@ -228,60 +334,6 @@ To run _Black_ on a key press (e.g. F9 below), add this: nnoremap :Black ``` -#### Troubleshooting - -**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` 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 package that causes problems is: - -- [typed-ast](https://pypi.org/project/typed-ast/) - -Now remove those two packages: - -```console -$ pip uninstall typed-ast -y -``` - -And now you can install them with: - -```console -$ pip install --no-binary :all: 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 typed-ast -``` - ### With ALE 1. Install [`ale`](https://github.com/dense-analysis/ale)