patch 9.1.0844: if_python: no way to pass local vars to python
Problem: if_python: no way to pass local vars to python
Solution: Add locals argument to py3eval(), pyeval() and pyxeval()
(Ben Jackson)
fixes: #8573
closes: #10594
Signed-off-by: Ben Jackson <puremourning@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index edc425a..70d6f47 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt* For Vim version 9.1. Last change: 2024 Nov 01
+*builtin.txt* For Vim version 9.1. Last change: 2024 Nov 06
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -467,9 +467,9 @@
prop_type_list([{props}]) List get list of property types
pum_getpos() Dict position and size of pum if visible
pumvisible() Number whether popup menu is visible
-py3eval({expr}) any evaluate |python3| expression
-pyeval({expr}) any evaluate |Python| expression
-pyxeval({expr}) any evaluate |python_x| expression
+py3eval({expr}[, {locals}]) any evaluate |python3| expression
+pyeval({expr}[, {locals}]) any evaluate |Python| expression
+pyxeval({expr}[, {locals}]) any evaluate |python_x| expression
rand([{expr}]) Number get pseudo-random number
range({expr} [, {max} [, {stride}]])
List items from {expr} to {max}
@@ -8127,9 +8127,14 @@
Return type: |Number|
-py3eval({expr}) *py3eval()*
+py3eval({expr}[, {locals}]) *py3eval()*
Evaluate Python expression {expr} and return its result
converted to Vim data structures.
+ If a {locals} |Dictionary| is given, it defines set of local
+ variables available in the expression. The keys are variable
+ names and the values are the variable values. |Dictionary| and
+ |List| values are referenced, and may be updated by the
+ expression (as if |python-bindeval| was used).
Numbers and strings are returned as they are (strings are
copied though, Unicode strings are additionally converted to
'encoding').
@@ -8141,15 +8146,17 @@
Can also be used as a |method|: >
GetExpr()->py3eval()
+ 'b",".join(l)'->py3eval({'l': ['a', 'b', 'c']})
<
Return type: any, depending on {expr}
{only available when compiled with the |+python3| feature}
*E858* *E859*
-pyeval({expr}) *pyeval()*
+pyeval({expr}[, {locals}]) *pyeval()*
Evaluate Python expression {expr} and return its result
converted to Vim data structures.
+ For {locals} see |py3eval()|.
Numbers and strings are returned as they are (strings are
copied though).
Lists are represented as Vim |List| type.
@@ -8165,9 +8172,10 @@
{only available when compiled with the |+python| feature}
-pyxeval({expr}) *pyxeval()*
+pyxeval({expr}[, {locals}]) *pyxeval()*
Evaluate Python expression {expr} and return its result
converted to Vim data structures.
+ For {locals} see |py3eval()|.
Uses Python 2 or 3, see |python_x| and 'pyxversion'.
See also: |pyeval()|, |py3eval()|
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index 6236841..0b6140f 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -1,4 +1,4 @@
-*if_pyth.txt* For Vim version 9.1. Last change: 2024 May 16
+*if_pyth.txt* For Vim version 9.1. Last change: 2024 Nov 06
VIM REFERENCE MANUAL by Paul Moore
@@ -201,6 +201,10 @@
[{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name': ~
'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}] ~
+ NOTE: In vim9script, local variables in def functions are not visible
+ to to python evaluations. To pass local variables to python evaluations,
+ use the {locals} dict when calling |py3eval()| and friends.
+
vim.bindeval(str) *python-bindeval*
Like |python-eval|, but returns special objects described in
|python-bindeval-objects|. These python objects let you modify (|List|
@@ -741,6 +745,10 @@
functions to evaluate Python expressions and pass their values to Vim script.
|pyxeval()| is also available.
+You can inject local variables into the evaluation using the optional {locals}
+dict. This can be particularly useful in vim9script where vim.eval
+|python-eval| will not find locals in a def func.
+
The Python value "None" is converted to v:none.
==============================================================================
diff --git a/runtime/doc/version9.txt b/runtime/doc/version9.txt
index 999a09c..c4022d8 100644
--- a/runtime/doc/version9.txt
+++ b/runtime/doc/version9.txt
@@ -1,4 +1,4 @@
-*version9.txt* For Vim version 9.1. Last change: 2024 Nov 03
+*version9.txt* For Vim version 9.1. Last change: 2024 Nov 06
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -41606,6 +41606,7 @@
- an interactive tutor plugin has been included |vim-tutor-mode|, can be
started via |:Tutor|
- improve the |vimtutor| and add a second chapter for more advanced tips
+- allow to pass local Vim script variables to python interpreter |py3eval()|
*added-9.2*
Added ~