Adding documentation to the README for import errors in vim (#1317)

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index def311ff2fbaab29eea816d99767ca2124536d0c..8ff893c9904e2e0ce485809164d5ead367003f29 100644 (file)
--- a/README.md
+++ b/README.md
@@ -61,30 +61,41 @@ black {source_file_or_directory}
 _Black_ doesn't provide many options. You can list them by running `black --help`:
 
 ```text
 _Black_ doesn't provide many options. You can list them by running `black --help`:
 
 ```text

-black [OPTIONS] [SRC]...
+Usage: black [OPTIONS] [SRC]...
+
+  The uncompromising code formatter.

 
 Options:
   -c, --code TEXT                 Format the code passed in as a string.
   -l, --line-length INTEGER       How many characters per line to allow.
                                   [default: 88]
 
 Options:
   -c, --code TEXT                 Format the code passed in as a string.
   -l, --line-length INTEGER       How many characters per line to allow.
                                   [default: 88]

+

   -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]
   -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]

+

   --pyi                           Format all input files like typing stubs
                                   regardless of file extension (useful when
                                   piping source on standard input).
   --pyi                           Format all input files like typing stubs
                                   regardless of file extension (useful when
                                   piping source on standard input).

+

   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files
   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files

-                                  would be reformatted.  Return code 123 means
+                                  would be reformatted. Return code 123 means

                                   there was an internal error.
                                   there was an internal error.

+

   --diff                          Don't write the files back, just output a
                                   diff for each file on stdout.
   --diff                          Don't write the files back, just output a
                                   diff for each file on stdout.

+
+  --color / --no-color            Show colored diff. Only applies when
+                                  `--diff` is given.
+

   --fast / --safe                 If --fast given, skip temporary sanity
                                   checks. [default: --safe]
   --fast / --safe                 If --fast given, skip temporary sanity
                                   checks. [default: --safe]

+

   --include TEXT                  A regular expression that matches files and
                                   directories that should be included on
                                   recursive searches.  An empty value means
   --include TEXT                  A regular expression that matches files and
                                   directories that should be included on
                                   recursive searches.  An empty value means


@@ -93,6 +104,7 @@ Options:
                                   on all platforms (Windows, too).  Exclusions
                                   are calculated first, inclusions later.
                                   [default: \.pyi?$]
                                   on all platforms (Windows, too).  Exclusions
                                   are calculated first, inclusions later.
                                   [default: \.pyi?$]

+

   --exclude TEXT                  A regular expression that matches files and
                                   directories that should be excluded on
                                   recursive searches.  An empty value means no
   --exclude TEXT                  A regular expression that matches files and
                                   directories that should be excluded on
                                   recursive searches.  An empty value means no


@@ -100,16 +112,23 @@ Options:
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
                                   later.  [default: /(\.eggs|\.git|\.hg|\.mypy
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
                                   later.  [default: /(\.eggs|\.git|\.hg|\.mypy

-                                  _cache|\.nox|\.tox|\.venv|_build|buck-
+                                  _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-

                                   out|build|dist)/]
                                   out|build|dist)/]

+
+  --force-exclude TEXT            Like --exclude, but files and directories
+                                  matching this regex will be excluded even
+                                  when they are passed explicitly as arguments
+

   -q, --quiet                     Don't emit non-error messages to stderr.
   -q, --quiet                     Don't emit non-error messages to stderr.

-                                  Errors are still emitted, silence those with
+                                  Errors are still emitted; silence those with

                                   2>/dev/null.
                                   2>/dev/null.

+

   -v, --verbose                   Also emit messages to stderr about files
                                   that were not changed or were ignored due to
                                   --exclude=.
   -v, --verbose                   Also emit messages to stderr about files
                                   that were not changed or were ignored due to
                                   --exclude=.

+

   --version                       Show the version and exit.
   --version                       Show the version and exit.

-  --config PATH                   Read configuration from PATH.
+  --config FILE                   Read configuration from PATH.

   -h, --help                      Show this message and exit.
 ```
 
   -h, --help                      Show this message and exit.
 ```
 


@@ -625,8 +644,11 @@ file hierarchy.
 
 ### Emacs
 
 
 ### Emacs
 

-Use [proofit404/blacken](https://github.com/proofit404/blacken) or
-[Elpy](https://github.com/jorgenschaefer/elpy).
+Options include the following:
+
+- [purcell/reformatter.el](https://github.com/purcell/reformatter.el)
+- [proofit404/blacken](https://github.com/proofit404/blacken)
+- [Elpy](https://github.com/jorgenschaefer/elpy).

 
 ### PyCharm/IntelliJ IDEA
 
 
 ### PyCharm/IntelliJ IDEA
 


@@ -801,6 +823,55 @@ default. On macOS with Homebrew run: `brew install vim`. When building Vim from
 use: `./configure --enable-python3interp=yes`. There's many guides online how to do
 this.
 
 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 "<string>", line 63, in <module>
+  File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
+    from typed_ast import ast3, ast27
+  File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
+    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
+```
+
+And now you can install them with:
+
+```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
+```
+

 ### Visual Studio Code
 
 Use the
 ### Visual Studio Code
 
 Use the