patch 8.0.0251: not easy to select Python 2 or 3
Problem: It is not so easy to write a script that works with both Python 2
and Python 3, even when the Python code works with both.
Solution: Add 'pyxversion', :pyx, etc. (Marc Weber, Ken Takata)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index ec4030e..687c605 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2239,6 +2239,7 @@
pumvisible() Number whether popup menu is visible
pyeval({expr}) any evaluate |Python| expression
py3eval({expr}) any evaluate |python3| expression
+pyxeval({expr}) any evaluate |python_x| expression
range({expr} [, {max} [, {stride}]])
List items from {expr} to {max}
readfile({fname} [, {binary} [, {max}]])
@@ -6163,6 +6164,14 @@
non-string keys result in error.
{only available when compiled with the |+python| feature}
+pyxeval({expr}) *pyxeval()*
+ Evaluate Python expression {expr} and return its result
+ converted to Vim data structures.
+ Uses Python 2 or 3, see |python_x| and 'pyxversion'.
+ See also: |pyeval()|, |py3eval()|
+ {only available when compiled with the |+python| or the
+ |+python3| feature}
+
*E726* *E727*
range({expr} [, {max} [, {stride}]]) *range()*
Returns a |List| with Numbers:
@@ -8402,6 +8411,7 @@
profile Compiled with |:profile| support.
python Compiled with Python 2.x interface. |has-python|
python3 Compiled with Python 3.x interface. |has-python|
+pythonx Compiled with |python_x| interface. |has-pythonx|
qnx QNX version of Vim.
quickfix Compiled with |quickfix| support.
reltime Compiled with |reltime()| support.
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index 5929bcf..9378807 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -16,6 +16,7 @@
8. pyeval(), py3eval() Vim functions |python-pyeval|
9. Dynamic loading |python-dynamic|
10. Python 3 |python3|
+11. Python X |python_x|
{Vi does not have any of these commands}
@@ -711,6 +712,7 @@
To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()|
functions to evaluate Python expressions and pass their values to VimL.
+|pyxeval()| is also available.
==============================================================================
9. Dynamic loading *python-dynamic*
@@ -812,4 +814,68 @@
the other one from being available.
==============================================================================
+11. Python X *python_x* *pythonx*
+
+Because most python code can be written so that it works with python 2.6+ and
+python 3 the pyx* functions and commands have been writen. They work exactly
+the same as the Python 2 and 3 variants, but select the Python version using
+the 'pyxversion' setting.
+
+You should set 'pyxversion' in your |.vimrc| to prefer Python 2 or Python 3
+for Python commands. If you change this setting at runtime you may risk that
+state of plugins (such as initialization) may be lost.
+
+If you want to use a module, you can put it in the {rtp}/pythonx directory.
+See |pythonx-directory|.
+
+ *:pyx* *:pythonx*
+The `:pyx` and `:pythonx` commands work similar to `:python`. A simple check
+if the `:pyx` command is working: >
+ :pyx print("Hello")
+
+To see what version of Python is being used: >
+ :pyx import sys
+ :pyx print(sys.version)
+<
+ *:pyxfile* *python_x-special-comments*
+The `:pyxfile` command works similar to `:pyfile`. However you can add one of
+these comments to force Vim using `:pyfile` or `:py3file`: >
+ #!/any string/python2 " Shebang. Must be the first line of the file.
+ #!/any string/python3 " Shebang. Must be the first line of the file.
+ # requires python 2.x " Maximum lines depend on 'modelines'.
+ # requires python 3.x " Maximum lines depend on 'modelines'.
+Unlike normal modelines, the bottom of the file is not checked.
+If none of them are found, the 'pyxversion' setting is used.
+ *W20* *W21*
+If Vim does not support the selected Python version a silent message will be
+printed. Use `:messages` to read them.
+
+ *:pyxdo*
+The `:pyxdo` command works similar to `:pydo`.
+
+ *has-pythonx*
+You can test if pyx* commands are available with: >
+ if has('pythonx')
+ echo 'pyx* commands are available. (Python ' . &pyx . ')'
+ endif
+
+When compiled with only one of |+python| or |+python3|, the has() returns 1.
+When compiled with both |+python| and |+python3|, the test depends on the
+'pyxversion' setting. If 'pyxversion' is 0, it tests Python 3 first, and if
+it is not available then Python 2. If 'pyxversion' is 2 or 3, it tests only
+Python 2 or 3 respectively.
+
+Note that for has('pythonx') to work it may try to dynamically load Python 3
+or 2. This may have side effects, especially when Vim can only load one of
+the two.
+
+If a user prefers Python 2 and want to fallback to Python 3, he needs to set
+'pyxversion' explicitly in his |.vimrc|. E.g.: >
+ if has('python')
+ set pyx=2
+ elseif has('python3')
+ set pyx=3
+ endif
+
+==============================================================================
vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 4ebf999..81b2eb6 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1440,6 +1440,10 @@
|:python| :py[thon] execute Python command
|:pydo| :pyd[o] execute Python command for each line
|:pyfile| :pyf[ile] execute Python script file
+|:pyx| :pyx execute |python_x| command
+|:pythonx| :pythonx same as :pyx
+|:pyxdo| :pyxd[o] execute |python_x| command for each line
+|:pyxfile| :pyxf[ile] execute |python_x| script file
|:quit| :q[uit] quit current window (when one window quit Vim)
|:quitall| :quita[ll] quit Vim
|:qall| :qa[ll] quit Vim
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index a9a0cc4..4e94902 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -5789,6 +5789,34 @@
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
+ *'pyxversion'* *'pyx'*
+'pyxversion' 'pyx' number (default depends on the build)
+ global
+ {not in Vi}
+ {only available when compiled with the |+python| or
+ the |+python3| feature}
+ Specifies the python version used for pyx* functions and commands
+ |python_x|. The default value is as follows:
+
+ Compiled with Default ~
+ |+python| and |+python3| 0
+ only |+python| 2
+ only |+python3| 3
+
+ Available values are 0, 2 and 3.
+ If 'pyxversion' is 0, it is set to 2 or 3 after the first execution of
+ any python2/3 commands or functions. E.g. `:py` sets to 2, and `:py3`
+ sets to 3. `:pyx` sets it to 3 if Python 3 is available, otherwise sets
+ to 2 if Python 2 is available.
+ See also: |has-pythonx|
+
+ If Vim is compiled with only |+python| or |+python3| setting
+ 'pyxversion' has no effect. The pyx* functions and commands are
+ always the same as the compiled version.
+
+ This option cannot be set from a |modeline| or in the |sandbox|, for
+ security reasons.
+
*'quoteescape'* *'qe'*
'quoteescape' 'qe' string (default "\")
local to buffer
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index e0252f7..b55fce1 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -835,6 +835,7 @@
'pumheight' 'ph' maximum height of the popup menu
'pythondll' name of the Python 2 dynamic library
'pythonthreedll' name of the Python 3 dynamic library
+'pyxversion' 'pyx' Python version used for pyx* commands
'quoteescape' 'qe' escape characters used in a string
'readonly' 'ro' disallow writing the buffer
'redrawtime' 'rdt' timeout for 'hlsearch' and |:match| highlighting