Vim plugin: allow using system black rather than virtualenv (psf#3309)

Provide a configuration parameter to the Vim plugin which will allow the
plugin to skip setting up a virtualenv. This is useful when there is a
system installation of black (e.g. from a Linux distribution) which the
user prefers to use.

Using a virtualenv remains the default.

- Fixes psf#3308

Author: bugfood

CHANGES.md

@@ -50,6 +50,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Vim plugin: Optionally allow using the system installation of Black via
+  `let g:black_use_virtualenv = 0`(#3309)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes

autoload/black.vim

@@ -56,6 +56,16 @@ def _get_virtualenv_site_packages(venv_path, pyver):
   return venv_path / 'lib' / f'python{pyver[0]}.{pyver[1]}' / 'site-packages'
 
 def _initialize_black_env(upgrade=False):
+  if vim.eval("g:black_use_virtualenv ? 'true' : 'false'") == "false":
+    if upgrade:
+      print("Upgrade disabled due to g:black_use_virtualenv being disabled.")
+      print("Either use your system package manager (or pip) to upgrade black separately,")
+      print("or modify your vimrc to have 'let g:black_use_virtualenv = 1'.")
+      return False
+    else:
+      # Nothing needed to be done.
+      return True
+
   pyver = sys.version_info[:3]
   if pyver < (3, 7):
     print("Sorry, Black requires Python 3.7+ to run.")

docs/integrations/editors.md

@@ -104,7 +104,7 @@ Commands and shortcuts:
   - you can optionally pass `target_version=<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:
 
@@ -160,6 +160,18 @@ 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.
 
+If you would prefer to use the system installation of _Black_ rather than a virtualenv,
+then add this to your vimrc:
+
+```
+let g:black_use_virtualenv = 0
+```
+
+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.
+
 To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
 
 ```

plugin/black.vim

@@ -63,6 +63,9 @@ endif
 if !exists("g:black_target_version")
   let g:black_target_version = ""
 endif
+if !exists("g:black_use_virtualenv")
+  let g:black_use_virtualenv = 1
+endif
 if !exists("g:black_preview")
   let g:black_preview = 0
 endif