Add pants_runtime_python_version global option (pantsbuild#7363)

### Problem
As discussed in pantsbuild/setup#30, we decided to add support for using Python 3 to every day user's setup script `./pants` by having them pin the interpreter version they want to use in `pants.ini`, and then grepping that value to choose the relevant interpreter. However, this currently results in this error:

```
ERROR] Invalid option 'pants_runtime_python_version' under [GLOBAL] in /Users/eric/DocsLocal/code/projects/setup/pants.ini
Exception caught: (<class 'pants.option.config.ConfigValidationError'>)

Exception message: Invalid config entries detected. See log for details on which entries to update or remove.
(Specify --no-verify-config to disable this check.)
```

### Solution
Exactly how we handle `--pants-version`, introduce a new global option `--pants-runtime-python-version` that allows users to set `pants_runtime_python_version` in their `pants.ini`.

Even though Pants code cannot dynamically change the interpreter it runs with—as it is too late to change the interpreter once the process is already running—we can check that Pants is running with the intended interpreter and print a helpful message if it is not.

You can leave off the option, and you'll get no runtime check. Setup scripts are free to implement Python interpreter resolution in another way if they prefer.

### Result
* Including `pants_runtime_python_version` in `pants.ini` no longer results in an error.
* Running `./pants --pants-runtime-python-version=2.6` will error out. Running `./pants2 --pants-runtime-python-version=2.7` will work normally.

src/python/pants/init/options_initializer.py

@@ -6,7 +6,7 @@
 
 import logging
 import sys
-from builtins import object
+from builtins import map, object
 
 import pkg_resources
 
@@ -108,6 +108,21 @@ def create(cls, options_bootstrapper, build_configuration, init_subsystems=True)
         .format(global_bootstrap_options.pants_version, pants_version())
       )
 
+    pants_runtime_python_version = global_bootstrap_options.pants_runtime_python_version
+    current_python_version = '.'.join(map(str, sys.version_info[0:2]))
+    if pants_runtime_python_version and pants_runtime_python_version != current_python_version:
+      raise BuildConfigurationError(
+        'Running Pants with a different Python interpreter version than requested. '
+        'You requested {}, but are running with {}.\n\n'
+        'Note that Pants cannot use the value you give for `--pants-engine-python-version` to '
+        'dynamically change the interpreter it uses, as it is too late for it to change once the program '
+        'is already running. Instead, your setup script (e.g. `./pants`) must configure which Python '
+        'interpreter and virtualenv to use. For example, the setup script we distribute '
+        'at https://www.pantsbuild.org/install.html#recommended-installation will read the '
+        '`pants_runtime_python_version` defined in your pants.ini to determine which Python '
+        'version to run with.'.format(pants_runtime_python_version, current_python_version)
+      )
+
     # Parse and register options.
     options = cls._construct_options(options_bootstrapper, build_configuration)
 

src/python/pants/option/global_options.py

@@ -115,12 +115,29 @@ def register_bootstrap_options(cls, register):
     register('--colors', type=bool, default=sys.stdout.isatty(), recursive=True, daemon=False,
              help='Set whether log messages are displayed in color.')
 
-    # Pants code uses this only to verify that we are of the requested version. However
-    # setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
-    # and use it to select the right version.
-    # Note that to print the version of the pants instance you're running, use -v, -V or --version.
     register('--pants-version', advanced=True, default=pants_version(),
-             help='Use this pants version.')
+             help='Use this pants version. Note Pants code only uses this to verify that you are '
+                  'using the requested version, as Pants cannot dynamically change the version it '
+                  'is using once the program is already running. This option is useful to set in '
+                  'your pants.ini, however, and then you can grep the value to select which '
+                  'version to use for setup scripts (e.g. `./pants`), runner scripts, IDE plugins, '
+                  'etc. For example, the setup script we distribute at https://www.pantsbuild.org/install.html#recommended-installation '
+                  'uses this value to determine which Python version to run with. You may find the '
+                  'version of the pants instance you are running using -v, -V, or --version.')
+
+    register('--pants-runtime-python-version', advanced=True,
+             help='Use this Python version to run Pants. The option expects the major and minor '
+                  'version, e.g. 2.7 or 3.6. Note Pants code only uses this to verify that you are '
+                  'using the requested interpreter, as Pants cannot dynamically change the '
+                  'interpreter it is using once the program is already running. This option is '
+                  'useful to set in your pants.ini, however, and then you can grep the value to '
+                  'select which interpreter to use for setup scripts (e.g. `./pants`), runner '
+                  'scripts, IDE plugins, etc. For example, the setup script we distribute at '
+                  'https://www.pantsbuild.org/install.html#recommended-installation uses this '
+                  'value to determine which Python version to run with. Also note this does not mean '
+                  'your own code must use this Python version. See '
+                  'https://www.pantsbuild.org/python_readme.html#configure-the-python-version '
+                  'for how to configure your code\'s compatibility.')
 
     register('--plugins', advanced=True, type=list, help='Load these plugins.')
     register('--plugin-cache-dir', advanced=True,