if_pyth.txt For Vim version 9.1. Last change: 2024 Nov 09
VIM REFERENCE MANUAL by Paul Moore
The Python Interface to Vim python Python
1. Commands python-commands
2. The vim module python-vim
3. Buffer objects python-buffer
4. Range objects python-range
5. Window objects python-window
6. Tab page objects python-tabpage
7. vim.bindeval objects python-bindeval-objects
8. pyeval(), py3eval() Vim functions python-pyeval
9. Dynamic loading python-dynamic
10. Python 3 python3
11. Python X python_x
12. Building with Python support python-building
The Python 2.x interface is available only when Vim was compiled with the
+python feature.
The Python 3 interface is available only when Vim was compiled with the
+python3 feature.
Both can be available at the same time, but read python-2-and-3.
NOTE: Python 2 is old and no longer being developed. Using Python 3 is highly
recommended. Python 2 support will be dropped when it does not work properly
anymore.
==============================================================================
1. Commands python-commands
:python :py E263 E264 E887
:[range]py[thon] {stmt}
Execute Python statement {stmt}. A simple check if
the :python command is working:
:[range]py[thon] << [trim] [{endmarker}]
{script}
{endmarker}
Execute Python script {script}.
Note: This command doesn't work when the Python
feature wasn't compiled in. To avoid errors, see
script-here.
If [endmarker] is omitted from after the "<<", a dot '.' must be used after
{script}, like for the :append and :insert commands. Refer to
:let-heredoc for more information.
This form of the :python command is mainly useful for including python code
in Vim scripts.
Example:
To see what version of Python you have:
There is no need to import sys, it's done by default.
python-environment
Environment variables set in Vim are not always available in Python. This
depends on how Vim and Python were built. Also see
https://docs.python.org/3/library/os.html#os.environ
Note: Python is very sensitive to the indenting. Make sure the "class" line
and "EOF" do not have any indent.
:pydo
:[range]pydo {body} Execute Python function "def _vim_pydo(line, linenr):
{body}" for each line in the [range], with the
function arguments being set to the text of each line
in turn, without a trailing <EOL>, and the current
line number. The function should return a string or
None. If a string is returned, it becomes the text of
the line in the current turn. The default for [range]
is the whole file: "1,$".
Examples:
One can use :pydo in possible conjunction with :py to filter a range using
python. For example:
:pyfile :pyf
:[range]pyf[ile] {file}
Execute the Python script in {file}. The whole
argument is used as a single file name.
Both of these commands do essentially the same thing - they execute a piece of
Python code, with the "current range" python-range set to the given line
range.
In the case of :python, the code to execute is in the command-line.
In the case of :pyfile, the code to execute is the contents of the given file.
Python commands cannot be used in the sandbox.
To pass arguments you need to set sys.argv[] explicitly. Example:
Here are some examples python-examples
(Note that changes - like the imports - persist from one command to the next,
just like in the Python interpreter.)
==============================================================================
2. The vim module python-vim
Python code gets all of its access to vim (with one exception - see
python-output below) via the "vim" module. The vim module implements two
methods, three constants, and one error object. You need to import the vim
module before using it:
Overview
Methods of the "vim" module
vim.command(str) python-command
Executes the vim (ex-mode) command str. Returns None.
Examples:
The ":python" command cannot be used recursively with Python 2.2 and
older. This only works with Python 2.3 and later:
vim.eval(str) python-eval
Evaluates the expression str using the vim internal expression
evaluator (see expression). Returns the expression result as:
- a string if the Vim expression evaluates to a string or number
- a list if the Vim expression evaluates to a Vim list
- a dictionary if the Vim expression evaluates to a Vim dictionary
Dictionaries and lists are recursively expanded.
Examples:
[{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name':
'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}]
NOTE: In Vim9 script, local variables in def functions are not visible
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
or Dictionary) or call (Funcref) vim objects.
vim.strwidth(str) python-strwidth
Like strwidth(): returns number of display cells str occupies, tab
is counted as one cell.
vim.foreach_rtp(callable) python-foreach_rtp
Call the given callable for each path in 'runtimepath' until either
callable returns something but None, the exception is raised or there
are no longer paths. If stopped in case callable returned non-None,
vim.foreach_rtp function returns the value returned by callable.
vim.chdir(*args, **kwargs) python-chdir
vim.fchdir(*args, **kwargs) python-fchdir
Run os.chdir or os.fchdir, then all appropriate vim stuff.
Note: you should not use these functions directly, use os.chdir and
os.fchdir instead. Behavior of vim.fchdir is undefined in case
os.fchdir does not exist.
Error object of the "vim" module
vim.error python-error
Upon encountering a Vim error, Python raises an exception of type
vim.error.
Example:
Constants of the "vim" module
Note that these are not actually constants - you could reassign them.
But this is silly, as you would then lose access to the vim objects
to which the variables referred.
vim.buffers python-buffers
A mapping object providing access to the list of vim buffers. The
object supports the following operations:
vim.windows python-windows
A sequence object providing access to the list of vim windows. The
object supports the following operations:
python-tabpage.windows objects are bound to parent python-tabpage
object and always use windows from that tab page (or throw vim.error
in case tab page was deleted). You can keep a reference to both
without keeping a reference to vim module object or python-tabpage,
they will not lose their properties in this case.
vim.tabpages python-tabpages
A sequence object providing access to the list of vim tab pages. The
object supports the following operations:
vim.current python-current
An object providing access (via specific attributes) to various
"current" objects available in vim:
vim.current.line The current line (RW) String
vim.current.buffer The current buffer (RW) Buffer
vim.current.window The current window (RW) Window
vim.current.tabpage The current tab page (RW) TabPage
vim.current.range The current line range (RO) Range
The last case deserves a little explanation. When the :python or
:pyfile command specifies a range, this range of lines becomes the
"current range". A range is a bit like a buffer, but with all access
restricted to a subset of lines. See python-range for more details.
Note: When assigning to vim.current.{buffer,window,tabpage} it expects
valid python-buffer, python-window or python-tabpage objects
respectively. Assigning triggers normal (with autocommands)
switching to given buffer, window or tab page. It is the only way to
switch UI objects in python: you can't assign to
python-tabpage.window attribute. To switch without triggering
autocommands use
vim.vars python-vars
vim.vvars python-vvars
Dictionary-like objects holding dictionaries with global (g:) and
vim (v:) variables respectively. Identical to vim.bindeval("g:"),
but faster.
vim.options python-options
Object partly supporting mapping protocol (supports setting and
getting items) providing a read-write access to global options.
Note: unlike :set this provides access only to global options. You
cannot use this object to obtain or set local options' values or
access local-only options in any fashion. Raises KeyError if no global
option with such name exists (i.e. does not raise KeyError for
global-local options and global only options, but does for window-
and buffer-local ones). Use python-buffer objects to access to
buffer-local options and python-window objects to access to
window-local options.
Type of this object is available via "Options" attribute of vim
module.
Output from Python python-output
Vim displays all Python code output in the Vim message area. Normal
output appears as information messages, and error output appears as
error messages.
In implementation terms, this means that all output to sys.stdout
(including the output from print statements) appears as information
messages, and all output to sys.stderr (including error tracebacks)
appears as error messages.
python-input
Input (via sys.stdin, including input() and raw_input()) is not
supported, and may cause the program to crash. This should probably be
fixed.
python2-directory python3-directory pythonx-directory
Python 'runtimepath' handling python-special-path
In python vim.VIM_SPECIAL_PATH special directory is used as a replacement for
the list of paths found in 'runtimepath': with this directory in sys.path and
vim.path_hooks in sys.path_hooks python will try to load module from
{rtp}/python2 (or python3) and {rtp}/pythonx (for both python versions) for
each {rtp} found in 'runtimepath' (Note: find_module() has been removed from
imp module around Python 3.12.0a7).
Implementation is similar to the following, but written in C:
vim.VIM_SPECIAL_PATH python-VIM_SPECIAL_PATH
String constant used in conjunction with vim path hook. If path hook
installed by vim is requested to handle anything but path equal to
vim.VIM_SPECIAL_PATH constant it raises ImportError. In the only other
case it uses special loader.
Note: you must not use value of this constant directly, always use
vim.VIM_SPECIAL_PATH object.
vim.find_module(...) python-find_module
vim.path_hook(path) python-path_hook
vim.find_spec(...) python-find_spec
Methods or objects used to implement path loading as described above.
You should not be using any of these directly except for vim.path_hook
in case you need to do something with sys.meta_path, vim.find_spec()
is available starting with Python 3.7.
It is not guaranteed that any of the objects will exist in future vim
versions.
vim._get_paths python-_get_paths
Methods returning a list of paths which will be searched for by path
hook. You should not rely on this method being present in future
versions, but can use it for debugging.
It returns a list of {rtp}/python2 (or {rtp}/python3) and
{rtp}/pythonx directories for each {rtp} in 'runtimepath'.
==============================================================================
3. Buffer objects python-buffer
Buffer objects represent vim buffers. You can obtain them in a number of ways:
- via vim.current.buffer (python-current)
- from indexing vim.buffers (python-buffers)
- from the "buffer" attribute of a window (python-window)
Buffer objects have two read-only attributes - name - the full file name for
the buffer, and number - the buffer number. They also have three methods
(append, mark, and range; see below).
You can also treat buffer objects as sequence objects. In this context, they
act as if they were lists (yes, they are mutable) of strings, with each
element being a line of the buffer. All of the usual sequence operations,
including indexing, index assignment, slicing and slice assignment, work as
you would expect. Note that the result of indexing (slicing) a buffer is a
string (list of strings). This has one unusual consequence - b[:] is different
from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas
"b = None" merely updates the variable b, with no effect on the buffer.
Buffer indexes start at zero, as is normal in Python. This differs from vim
line numbers, which start from 1. This is particularly relevant when dealing
with marks (see below) which use vim line numbers.
The buffer object attributes are:
b.vars Dictionary-like object used to access
buffer-variables.
b.options Mapping object (supports item getting, setting and
deleting) that provides access to buffer-local options
and buffer-local values of global-local options. Use
python-window.options if option is window-local,
this object will raise KeyError. If option is
global-local and local value is missing getting it
will return None.
b.name String, RW. Contains buffer name (full path).
Note: when assigning to b.name BufFilePre and
BufFilePost autocommands are launched.
b.number Buffer number. Can be used as python-buffers key.
Read-only.
b.valid True or False. Buffer object becomes invalid when
corresponding buffer is wiped out.
The buffer object methods are:
b.append(str) Append a line to the buffer
b.append(str, nr) Idem, below line "nr"
b.append(list) Append a list of lines to the buffer
Note that the option of supplying a list of strings to
the append method differs from the equivalent method
for Python's built-in list objects.
b.append(list, nr) Idem, below line "nr"
b.mark(name) Return a tuple (row,col) representing the position
of the named mark (can also get the []"<> marks)
b.range(s,e) Return a range object (see python-range) which
represents the part of the given buffer between line
numbers s and e inclusive.
Note that when adding a line it must not contain a line break character '\n'.
A trailing '\n' is allowed and ignored, so that you can do:
Buffer object type is available using "Buffer" attribute of vim module.
Examples (assume b is the current buffer)
==============================================================================
4. Range objects python-range
Range objects represent a part of a vim buffer. You can obtain them in a
number of ways:
- via vim.current.range (python-current)
- from a buffer's range() method (python-buffer)
A range object is almost identical in operation to a buffer object. However,
all operations are restricted to the lines within the range (this line range
can, of course, change as a result of slice assignments, line deletions, or
the range.append() method).
The range object attributes are:
r.start Index of first line into the buffer
r.end Index of last line into the buffer
The range object methods are:
r.append(str) Append a line to the range
r.append(str, nr) Idem, after line "nr"
r.append(list) Append a list of lines to the range
Note that the option of supplying a list of strings to
the append method differs from the equivalent method
for Python's built-in list objects.
r.append(list, nr) Idem, after line "nr"
Range object type is available using "Range" attribute of vim module.
Example (assume r is the current range):
==============================================================================
5. Window objects python-window
Window objects represent vim windows. You can obtain them in a number of ways:
- via vim.current.window (python-current)
- from indexing vim.windows (python-windows)
- from indexing "windows" attribute of a tab page (python-tabpage)
- from the "window" attribute of a tab page (python-tabpage)
You can manipulate window objects only through their attributes. They have no
methods, and no sequence or other interface.
Window attributes are:
buffer (read-only) The buffer displayed in this window
cursor (read-write) The current cursor position in the window
This is a tuple, (row,col).
height (read-write) The window height, in rows
width (read-write) The window width, in columns
vars (read-only) The window w: variables. Attribute is
unassignable, but you can change window
variables this way
options (read-only) The window-local options. Attribute is
unassignable, but you can change window
options this way. Provides access only to
window-local options, for buffer-local use
python-buffer and for global ones use
python-options. If option is global-local
and local value is missing getting it will
return None.
number (read-only) Window number. The first window has number 1.
This is zero in case it cannot be determined
(e.g. when the window object belongs to other
tab page).
row, col (read-only) On-screen window position in display cells.
First position is zero.
tabpage (read-only) Window tab page.
valid (read-write) True or False. Window object becomes invalid
when corresponding window is closed.
The height attribute is writable only if the screen is split horizontally.
The width attribute is writable only if the screen is split vertically.
Window object type is available using "Window" attribute of vim module.
==============================================================================
6. Tab page objects python-tabpage
Tab page objects represent vim tab pages. You can obtain them in a number of
ways:
- via vim.current.tabpage (python-current)
- from indexing vim.tabpages (python-tabpages)
You can use this object to access tab page windows. They have no methods and
no sequence or other interfaces.
Tab page attributes are:
number The tab page number like the one returned by
tabpagenr().
windows Like python-windows, but for current tab page.
vars The tab page t: variables.
window Current tabpage window.
valid True or False. Tab page object becomes invalid when
corresponding tab page is closed.
TabPage object type is available using "TabPage" attribute of vim module.
==============================================================================
7. vim.bindeval objects python-bindeval-objects
vim.Dictionary object python-Dictionary
Dictionary-like object providing access to vim Dictionary type.
Attributes:
Attribute Description
locked One of python-.locked
Value Description
zero Variable is not locked
vim.VAR_LOCKED Variable is locked, but can be unlocked
vim.VAR_FIXED Variable is locked and can't be unlocked
Read-write. You can unlock locked variable by assigning
True or False to this attribute. No recursive locking
is supported.
scope One of
Value Description
zero Dictionary is not a scope one
vim.VAR_DEF_SCOPE g: or l: dictionary
vim.VAR_SCOPE Other scope dictionary,
see internal-variables
Methods (note: methods do not support keyword arguments):
Method Description
keys() Returns a list with dictionary keys.
values() Returns a list with dictionary values.
items() Returns a list of 2-tuples with dictionary contents.
update(iterable), update(dictionary), update(**kwargs)
Adds keys to dictionary.
get(key[, default=None])
Obtain key from dictionary, returning the default if it is
not present.
pop(key[, default])
Remove specified key from dictionary and return
corresponding value. If key is not found and default is
given returns the default, otherwise raises KeyError.
popitem()
Remove random key from dictionary and return (key, value)
pair.
has_key(key)
Check whether dictionary contains specified key, similar
to `key in dict`.
__new__(), __new__(iterable), __new__(dictionary), __new__(update)
You can use vim.Dictionary() to create new vim
dictionaries. d=vim.Dictionary(arg) is the same as
d=vim.bindeval('{}');d.update(arg). Without arguments
constructs empty dictionary.
Examples:
Note: when iterating over keys you should not modify dictionary.
vim.List object python-List
Sequence-like object providing access to vim List type.
Supports .locked attribute, see python-.locked. Also supports the
following methods:
Method Description
extend(item) Add items to the list.
__new__(), __new__(iterable)
You can use vim.List() to create new vim lists.
l=vim.List(iterable) is the same as
l=vim.bindeval('[]');l.extend(iterable). Without
arguments constructs empty list.
Examples:
vim.Function object python-Function
Function-like object, acting like vim Funcref object. Accepts special
keyword argument self, see Dictionary-function. You can also use
vim.Function(name) constructor, it is the same as
vim.bindeval('function(%s)'%json.dumps(name)).
Attributes (read-only):
Attribute Description
name Function name.
args None or a python-List object with arguments. Note
that this is a copy of the arguments list, constructed
each time you request this attribute. Modifications made
to the list will be ignored (but not to the containers
inside argument list: this is like copy() and not
deepcopy()).
self None or a python-Dictionary object with self
dictionary. Note that explicit self keyword used when
calling resulting object overrides this attribute.
auto_rebind Boolean. True if partial created from this Python object
and stored in the Vim script dictionary should be
automatically rebound to the dictionary it is stored in
when this dictionary is indexed. Exposes Vim internal
difference between dict.func (auto_rebind=True) and
function(dict.func,dict) (auto_rebind=False). This
attribute makes no sense if self attribute is None.
Constructor additionally accepts args, self and auto_rebind
keywords. If args and/or self argument is given then it constructs
a partial, see function(). auto_rebind is only used when self
argument is given, otherwise it is assumed to be True regardless of
whether it was given or not. If self is given then it defaults to
False.
Examples:
==============================================================================
8. pyeval() and py3eval() Vim functions python-pyeval
To facilitate bi-directional interface, you can use pyeval() and py3eval()
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.
==============================================================================
9. Dynamic loading python-dynamic
On MS-Windows and Unix the Python library can be loaded dynamically. The
:version output then includes +python/dyn or +python3/dyn.
This means that Vim will search for the Python DLL or shared library file only
when needed. When you don't use the Python interface you don't need it, thus
you can use Vim without this file.
MS-Windows
To use the Python interface the Python DLL must be in your search path. In a
console window type "path" to see what directories are used. If the DLL is
not found in your search path, Vim will check the registry to find the path
where Python is installed. The 'pythondll' or 'pythonthreedll' option can be
also used to specify the Python DLL.
The name of the DLL should match the Python version Vim was compiled with.
Currently the name for Python 2 is "python27.dll", that is for Python 2.7.
That is the default value for 'pythondll'. For Python 3 it is python36.dll
(Python 3.6). To know for sure edit "gvim.exe" and search for
"python\d*.dll\c".
Unix
The 'pythondll' or 'pythonthreedll' option can be used to specify the Python
shared library file instead of DYNAMIC_PYTHON_DLL or DYNAMIC_PYTHON3_DLL file
what were specified at compile time. The version of the shared library must
match the Python 2.x or Python 3 version (v:python3_version) Vim was
compiled with unless using python3-stable-abi.
Stable ABI and mixing Python versions
python-stable python-stable-abi python3-stable-abi
If Vim was not compiled with Stable ABI (only available for Python 3), the
version of the Python shared library must match the version that Vim was
compiled with. Otherwise, mixing versions could result in unexpected crashes
and failures. With Stable ABI, this restriction is relaxed, and any Python 3
library with version of at least v:python3_version will work. See
has-python for how to check if Stable ABI is supported, or see if version
output includes +python3/dyn-stable.
On MS-Windows, 'pythonthreedll' will be set to "python3.dll". When searching
the DLL from the registry, Vim will search the latest version of Python.
==============================================================================
10. Python 3 python3
:py3 :python3
:[range]py3 {stmt}
:[range]py3 << [trim] [{endmarker}]
{script}
{endmarker}
:[range]python3 {stmt}
:[range]python3 << [trim] [{endmarker}]
{script}
{endmarker}
The :py3 and :python3 commands work similar to :python. A
simple check if the :py3 command is working:
To see what version of Python you have:
:[range]py3f[ile] {file}
The :py3file command works similar to :pyfile.
:py3do
:[range]py3do {body}
The :py3do command works similar to :pydo.
Vim can be built in four ways (:version output):
1. No Python support (-python, -python3)
2. Python 2 support only (+python or +python/dyn, -python3)
3. Python 3 support only (-python, +python3 or +python3/dyn)
4. Python 2 and 3 support (+python/dyn, +python3/dyn)
Some more details on the special case 4: python-2-and-3
When Python 2 and Python 3 are both supported they must be loaded dynamically.
When doing this on Linux/Unix systems and importing global symbols, this leads
to a crash when the second Python version is used. So either global symbols
are loaded but only one Python version is activated, or no global symbols are
loaded. The latter makes Python's "import" fail on libraries that expect the
symbols to be provided by Vim.
E836 E837
Vim's configuration script makes a guess for all libraries based on one
standard Python library (termios). If importing this library succeeds for
both Python versions, then both will be made available in Vim at the same
time. If not, only the version first used in a session will be enabled.
When trying to use the other one you will get the E836 or E837 error message.
Here Vim's behavior depends on the system in which it was configured. In a
system where both versions of Python were configured with --enable-shared,
both versions of Python will be activated at the same time. There will still
be problems with other third party libraries that were not linked to
libPython.
To work around such problems there are these options:
1. The problematic library is recompiled to link to the according
libpython.so.
2. Vim is recompiled for only one Python version.
3. You undefine PY_NO_RTLD_GLOBAL in auto/config.h after configuration. This
may crash Vim though.
E880
Raising SystemExit exception in python isn't endorsed way to quit vim, use:
E1266
This error can occur when Python 3 cannot load the required modules. This
means that your Python 3 is not correctly installed or there are some mistakes
in your settings. Please check the following items:
1. Make sure that Python 3 is correctly installed. Also check the version of
python.
2. Check the 'pythonthreedll' option.
3. Check the 'pythonthreehome' option.
4. Check the PATH environment variable if you don't set 'pythonthreedll'.
On MS-Windows, you can use where.exe to check which dll will be loaded.
E.g.
has-python
You can test what Python version is available with:
Note however, that when Python 2 and 3 are both available and loaded
dynamically, these has() calls will try to load them. If only one can be
loaded at a time, just checking if Python 2 or 3 are available will prevent
the other one from being available.
To avoid loading the dynamic library, only check if Vim was compiled with
python support:
When loading the library dynamically, Vim can be compiled to support Python 3
Stable ABI (python3-stable-abi) which allows you to load a different version
of Python 3 library than the one Vim was compiled with. To check it:
This also tells you whether Python is dynamically loaded, which will fail if
the runtime library cannot be found.
==============================================================================
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 written. 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:
To see what version of Python is being used:
: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:
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:
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.:
==============================================================================
12. Building with Python support python-building
A few hints for building with Python 2 or 3 support.
UNIX
See src/Makefile for how to enable including the Python interface.
On Ubuntu you will want to install these packages for Python 2:
python
python-dev
For Python 3:
python3
python3-dev
For Python 3.6:
python3.6
python3.6-dev
If you have more than one version of Python 3, you need to link python3 to the
one you prefer, before running configure.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:
VIM REFERENCE MANUAL by Paul Moore
The Python Interface to Vim python Python
1. Commands python-commands
2. The vim module python-vim
3. Buffer objects python-buffer
4. Range objects python-range
5. Window objects python-window
6. Tab page objects python-tabpage
7. vim.bindeval objects python-bindeval-objects
8. pyeval(), py3eval() Vim functions python-pyeval
9. Dynamic loading python-dynamic
10. Python 3 python3
11. Python X python_x
12. Building with Python support python-building
The Python 2.x interface is available only when Vim was compiled with the
+python feature.
The Python 3 interface is available only when Vim was compiled with the
+python3 feature.
Both can be available at the same time, but read python-2-and-3.
NOTE: Python 2 is old and no longer being developed. Using Python 3 is highly
recommended. Python 2 support will be dropped when it does not work properly
anymore.
==============================================================================
1. Commands python-commands
:python :py E263 E264 E887
:[range]py[thon] {stmt}
Execute Python statement {stmt}. A simple check if
the :python command is working:
:python print "Hello"
:[range]py[thon] << [trim] [{endmarker}]
{script}
{endmarker}
Execute Python script {script}.
Note: This command doesn't work when the Python
feature wasn't compiled in. To avoid errors, see
script-here.
If [endmarker] is omitted from after the "<<", a dot '.' must be used after
{script}, like for the :append and :insert commands. Refer to
:let-heredoc for more information.
This form of the :python command is mainly useful for including python code
in Vim scripts.
Example:
function! IcecreamInitialize()
python << EOF
class StrawberryIcecream:
def __call__(self):
print 'EAT ME'
EOF
endfunction
python << EOF
class StrawberryIcecream:
def __call__(self):
print 'EAT ME'
EOF
endfunction
To see what version of Python you have:
:python print(sys.version)
There is no need to import sys, it's done by default.
python-environment
Environment variables set in Vim are not always available in Python. This
depends on how Vim and Python were built. Also see
https://docs.python.org/3/library/os.html#os.environ
Note: Python is very sensitive to the indenting. Make sure the "class" line
and "EOF" do not have any indent.
:pydo
:[range]pydo {body} Execute Python function "def _vim_pydo(line, linenr):
{body}" for each line in the [range], with the
function arguments being set to the text of each line
in turn, without a trailing <EOL>, and the current
line number. The function should return a string or
None. If a string is returned, it becomes the text of
the line in the current turn. The default for [range]
is the whole file: "1,$".
Examples:
:pydo return "%s\t%d" % (line[::-1], len(line))
:pydo if line: return "%4d: %s" % (linenr, line)
:pydo if line: return "%4d: %s" % (linenr, line)
One can use :pydo in possible conjunction with :py to filter a range using
python. For example:
:py3 << EOF
needle = vim.eval('@a')
replacement = vim.eval('@b')
needle = vim.eval('@a')
replacement = vim.eval('@b')
def py_vim_string_replace(str):
return str.replace(needle, replacement)
EOF
:'<,'>py3do return py_vim_string_replace(line)
return str.replace(needle, replacement)
EOF
:'<,'>py3do return py_vim_string_replace(line)
:pyfile :pyf
:[range]pyf[ile] {file}
Execute the Python script in {file}. The whole
argument is used as a single file name.
Both of these commands do essentially the same thing - they execute a piece of
Python code, with the "current range" python-range set to the given line
range.
In the case of :python, the code to execute is in the command-line.
In the case of :pyfile, the code to execute is the contents of the given file.
Python commands cannot be used in the sandbox.
To pass arguments you need to set sys.argv[] explicitly. Example:
:python sys.argv = ["foo", "bar"]
:pyfile myscript.py
:pyfile myscript.py
Here are some examples python-examples
:python from vim import *
:python from string import upper
:python current.line = upper(current.line)
:python print "Hello"
:python str = current.buffer[42]
:python from string import upper
:python current.line = upper(current.line)
:python print "Hello"
:python str = current.buffer[42]
(Note that changes - like the imports - persist from one command to the next,
just like in the Python interpreter.)
==============================================================================
2. The vim module python-vim
Python code gets all of its access to vim (with one exception - see
python-output below) via the "vim" module. The vim module implements two
methods, three constants, and one error object. You need to import the vim
module before using it:
:python import vim
Overview
:py print "Hello" # displays a message
:py vim.command(cmd) # execute an Ex command
:py w = vim.windows[n] # gets window "n"
:py cw = vim.current.window # gets the current window
:py b = vim.buffers[n] # gets buffer "n"
:py cb = vim.current.buffer # gets the current buffer
:py w.height = lines # sets the window height
:py w.cursor = (row, col) # sets the window cursor position
:py pos = w.cursor # gets a tuple (row, col)
:py name = b.name # gets the buffer file name
:py line = b[n] # gets a line from the buffer
:py lines = b[n:m] # gets a list of lines
:py num = len(b) # gets the number of lines
:py b[n] = str # sets a line in the buffer
:py b[n:m] = [str1, str2, str3] # sets a number of lines at once
:py del b[n] # deletes a line
:py del b[n:m] # deletes a number of lines
:py vim.command(cmd) # execute an Ex command
:py w = vim.windows[n] # gets window "n"
:py cw = vim.current.window # gets the current window
:py b = vim.buffers[n] # gets buffer "n"
:py cb = vim.current.buffer # gets the current buffer
:py w.height = lines # sets the window height
:py w.cursor = (row, col) # sets the window cursor position
:py pos = w.cursor # gets a tuple (row, col)
:py name = b.name # gets the buffer file name
:py line = b[n] # gets a line from the buffer
:py lines = b[n:m] # gets a list of lines
:py num = len(b) # gets the number of lines
:py b[n] = str # sets a line in the buffer
:py b[n:m] = [str1, str2, str3] # sets a number of lines at once
:py del b[n] # deletes a line
:py del b[n:m] # deletes a number of lines
Methods of the "vim" module
vim.command(str) python-command
Executes the vim (ex-mode) command str. Returns None.
Examples:
:py vim.command("set tw=72")
:py vim.command("%s/aaa/bbb/g")
The following definition executes Normal mode commands::py vim.command("%s/aaa/bbb/g")
def normal(str):
vim.command("normal "+str)
# Note the use of single quotes to delimit a string containing
# double quotes
normal('"a2dd"aP')
E659vim.command("normal "+str)
# Note the use of single quotes to delimit a string containing
# double quotes
normal('"a2dd"aP')
The ":python" command cannot be used recursively with Python 2.2 and
older. This only works with Python 2.3 and later:
:py vim.command("python print 'Hello again Python'")
vim.eval(str) python-eval
Evaluates the expression str using the vim internal expression
evaluator (see expression). Returns the expression result as:
- a string if the Vim expression evaluates to a string or number
- a list if the Vim expression evaluates to a Vim list
- a dictionary if the Vim expression evaluates to a Vim dictionary
Dictionaries and lists are recursively expanded.
Examples:
:" value of the 'textwidth' option
:py text_width = vim.eval("&tw")
:
:" contents of the 'a' register
:py a_reg = vim.eval("@a")
:
:" Result is a string! Use string.atoi() to convert to a number.
:py str = vim.eval("12+12")
:
:py tagList = vim.eval('taglist("eval_expr")')
The latter will return a python list of python dicts, for instance::py text_width = vim.eval("&tw")
:
:" contents of the 'a' register
:py a_reg = vim.eval("@a")
:
:" Result is a string! Use string.atoi() to convert to a number.
:py str = vim.eval("12+12")
:
:py tagList = vim.eval('taglist("eval_expr")')
[{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name':
'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}]
NOTE: In Vim9 script, local variables in def functions are not visible
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
or Dictionary) or call (Funcref) vim objects.
vim.strwidth(str) python-strwidth
Like strwidth(): returns number of display cells str occupies, tab
is counted as one cell.
vim.foreach_rtp(callable) python-foreach_rtp
Call the given callable for each path in 'runtimepath' until either
callable returns something but None, the exception is raised or there
are no longer paths. If stopped in case callable returned non-None,
vim.foreach_rtp function returns the value returned by callable.
vim.chdir(*args, **kwargs) python-chdir
vim.fchdir(*args, **kwargs) python-fchdir
Run os.chdir or os.fchdir, then all appropriate vim stuff.
Note: you should not use these functions directly, use os.chdir and
os.fchdir instead. Behavior of vim.fchdir is undefined in case
os.fchdir does not exist.
Error object of the "vim" module
vim.error python-error
Upon encountering a Vim error, Python raises an exception of type
vim.error.
Example:
try:
vim.command("put a")
except vim.error:
# nothing in register a
vim.command("put a")
except vim.error:
# nothing in register a
Constants of the "vim" module
Note that these are not actually constants - you could reassign them.
But this is silly, as you would then lose access to the vim objects
to which the variables referred.
vim.buffers python-buffers
A mapping object providing access to the list of vim buffers. The
object supports the following operations:
:py b = vim.buffers[i] # Indexing (read-only)
:py b in vim.buffers # Membership test
:py n = len(vim.buffers) # Number of elements
:py for b in vim.buffers: # Iterating over buffer list
:py b in vim.buffers # Membership test
:py n = len(vim.buffers) # Number of elements
:py for b in vim.buffers: # Iterating over buffer list
vim.windows python-windows
A sequence object providing access to the list of vim windows. The
object supports the following operations:
:py w = vim.windows[i] # Indexing (read-only)
:py w in vim.windows # Membership test
:py n = len(vim.windows) # Number of elements
:py for w in vim.windows: # Sequential access
Note: vim.windows object always accesses current tab page.:py w in vim.windows # Membership test
:py n = len(vim.windows) # Number of elements
:py for w in vim.windows: # Sequential access
python-tabpage.windows objects are bound to parent python-tabpage
object and always use windows from that tab page (or throw vim.error
in case tab page was deleted). You can keep a reference to both
without keeping a reference to vim module object or python-tabpage,
they will not lose their properties in this case.
vim.tabpages python-tabpages
A sequence object providing access to the list of vim tab pages. The
object supports the following operations:
:py t = vim.tabpages[i] # Indexing (read-only)
:py t in vim.tabpages # Membership test
:py n = len(vim.tabpages) # Number of elements
:py for t in vim.tabpages: # Sequential access
:py t in vim.tabpages # Membership test
:py n = len(vim.tabpages) # Number of elements
:py for t in vim.tabpages: # Sequential access
vim.current python-current
An object providing access (via specific attributes) to various
"current" objects available in vim:
vim.current.line The current line (RW) String
vim.current.buffer The current buffer (RW) Buffer
vim.current.window The current window (RW) Window
vim.current.tabpage The current tab page (RW) TabPage
vim.current.range The current line range (RO) Range
The last case deserves a little explanation. When the :python or
:pyfile command specifies a range, this range of lines becomes the
"current range". A range is a bit like a buffer, but with all access
restricted to a subset of lines. See python-range for more details.
Note: When assigning to vim.current.{buffer,window,tabpage} it expects
valid python-buffer, python-window or python-tabpage objects
respectively. Assigning triggers normal (with autocommands)
switching to given buffer, window or tab page. It is the only way to
switch UI objects in python: you can't assign to
python-tabpage.window attribute. To switch without triggering
autocommands use
py << EOF
saved_eventignore = vim.options['eventignore']
vim.options['eventignore'] = 'all'
try:
vim.current.buffer = vim.buffers[2] # Switch to buffer 2
finally:
vim.options['eventignore'] = saved_eventignore
EOF
saved_eventignore = vim.options['eventignore']
vim.options['eventignore'] = 'all'
try:
vim.current.buffer = vim.buffers[2] # Switch to buffer 2
finally:
vim.options['eventignore'] = saved_eventignore
EOF
vim.vars python-vars
vim.vvars python-vvars
Dictionary-like objects holding dictionaries with global (g:) and
vim (v:) variables respectively. Identical to vim.bindeval("g:"),
but faster.
vim.options python-options
Object partly supporting mapping protocol (supports setting and
getting items) providing a read-write access to global options.
Note: unlike :set this provides access only to global options. You
cannot use this object to obtain or set local options' values or
access local-only options in any fashion. Raises KeyError if no global
option with such name exists (i.e. does not raise KeyError for
global-local options and global only options, but does for window-
and buffer-local ones). Use python-buffer objects to access to
buffer-local options and python-window objects to access to
window-local options.
Type of this object is available via "Options" attribute of vim
module.
Output from Python python-output
Vim displays all Python code output in the Vim message area. Normal
output appears as information messages, and error output appears as
error messages.
In implementation terms, this means that all output to sys.stdout
(including the output from print statements) appears as information
messages, and all output to sys.stderr (including error tracebacks)
appears as error messages.
python-input
Input (via sys.stdin, including input() and raw_input()) is not
supported, and may cause the program to crash. This should probably be
fixed.
python2-directory python3-directory pythonx-directory
Python 'runtimepath' handling python-special-path
In python vim.VIM_SPECIAL_PATH special directory is used as a replacement for
the list of paths found in 'runtimepath': with this directory in sys.path and
vim.path_hooks in sys.path_hooks python will try to load module from
{rtp}/python2 (or python3) and {rtp}/pythonx (for both python versions) for
each {rtp} found in 'runtimepath' (Note: find_module() has been removed from
imp module around Python 3.12.0a7).
Implementation is similar to the following, but written in C:
from imp import find_module, load_module
import vim
import sys
import vim
import sys
class VimModuleLoader(object):
def __init__(self, module):
self.module = module
def __init__(self, module):
self.module = module
def load_module(self, fullname, path=None):
return self.module
return self.module
def _find_module(fullname, oldtail, path):
idx = oldtail.find('.')
if idx > 0:
name = oldtail[:idx]
tail = oldtail[idx+1:]
fmr = find_module(name, path)
module = load_module(fullname[:-len(oldtail)] + name, *fmr)
return _find_module(fullname, tail, module.__path__)
else:
fmr = find_module(fullname, path)
return load_module(fullname, *fmr)
idx = oldtail.find('.')
if idx > 0:
name = oldtail[:idx]
tail = oldtail[idx+1:]
fmr = find_module(name, path)
module = load_module(fullname[:-len(oldtail)] + name, *fmr)
return _find_module(fullname, tail, module.__path__)
else:
fmr = find_module(fullname, path)
return load_module(fullname, *fmr)
# It uses vim module itself in place of VimPathFinder class: it does not
# matter for python which object has find_module function attached to as
# an attribute.
class VimPathFinder(object):
@classmethod
def find_module(cls, fullname, path=None):
try:
return VimModuleLoader(_find_module(fullname, fullname, path or vim._get_paths()))
except ImportError:
return None
# matter for python which object has find_module function attached to as
# an attribute.
class VimPathFinder(object):
@classmethod
def find_module(cls, fullname, path=None):
try:
return VimModuleLoader(_find_module(fullname, fullname, path or vim._get_paths()))
except ImportError:
return None
@classmethod
def load_module(cls, fullname, path=None):
return _find_module(fullname, fullname, path or vim._get_paths())
def load_module(cls, fullname, path=None):
return _find_module(fullname, fullname, path or vim._get_paths())
def hook(path):
if path == vim.VIM_SPECIAL_PATH:
return VimPathFinder
else:
raise ImportError
if path == vim.VIM_SPECIAL_PATH:
return VimPathFinder
else:
raise ImportError
sys.path_hooks.append(hook)
vim.VIM_SPECIAL_PATH python-VIM_SPECIAL_PATH
String constant used in conjunction with vim path hook. If path hook
installed by vim is requested to handle anything but path equal to
vim.VIM_SPECIAL_PATH constant it raises ImportError. In the only other
case it uses special loader.
Note: you must not use value of this constant directly, always use
vim.VIM_SPECIAL_PATH object.
vim.find_module(...) python-find_module
vim.path_hook(path) python-path_hook
vim.find_spec(...) python-find_spec
Methods or objects used to implement path loading as described above.
You should not be using any of these directly except for vim.path_hook
in case you need to do something with sys.meta_path, vim.find_spec()
is available starting with Python 3.7.
It is not guaranteed that any of the objects will exist in future vim
versions.
vim._get_paths python-_get_paths
Methods returning a list of paths which will be searched for by path
hook. You should not rely on this method being present in future
versions, but can use it for debugging.
It returns a list of {rtp}/python2 (or {rtp}/python3) and
{rtp}/pythonx directories for each {rtp} in 'runtimepath'.
==============================================================================
3. Buffer objects python-buffer
Buffer objects represent vim buffers. You can obtain them in a number of ways:
- via vim.current.buffer (python-current)
- from indexing vim.buffers (python-buffers)
- from the "buffer" attribute of a window (python-window)
Buffer objects have two read-only attributes - name - the full file name for
the buffer, and number - the buffer number. They also have three methods
(append, mark, and range; see below).
You can also treat buffer objects as sequence objects. In this context, they
act as if they were lists (yes, they are mutable) of strings, with each
element being a line of the buffer. All of the usual sequence operations,
including indexing, index assignment, slicing and slice assignment, work as
you would expect. Note that the result of indexing (slicing) a buffer is a
string (list of strings). This has one unusual consequence - b[:] is different
from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas
"b = None" merely updates the variable b, with no effect on the buffer.
Buffer indexes start at zero, as is normal in Python. This differs from vim
line numbers, which start from 1. This is particularly relevant when dealing
with marks (see below) which use vim line numbers.
The buffer object attributes are:
b.vars Dictionary-like object used to access
buffer-variables.
b.options Mapping object (supports item getting, setting and
deleting) that provides access to buffer-local options
and buffer-local values of global-local options. Use
python-window.options if option is window-local,
this object will raise KeyError. If option is
global-local and local value is missing getting it
will return None.
b.name String, RW. Contains buffer name (full path).
Note: when assigning to b.name BufFilePre and
BufFilePost autocommands are launched.
b.number Buffer number. Can be used as python-buffers key.
Read-only.
b.valid True or False. Buffer object becomes invalid when
corresponding buffer is wiped out.
The buffer object methods are:
b.append(str) Append a line to the buffer
b.append(str, nr) Idem, below line "nr"
b.append(list) Append a list of lines to the buffer
Note that the option of supplying a list of strings to
the append method differs from the equivalent method
for Python's built-in list objects.
b.append(list, nr) Idem, below line "nr"
b.mark(name) Return a tuple (row,col) representing the position
of the named mark (can also get the []"<> marks)
b.range(s,e) Return a range object (see python-range) which
represents the part of the given buffer between line
numbers s and e inclusive.
Note that when adding a line it must not contain a line break character '\n'.
A trailing '\n' is allowed and ignored, so that you can do:
:py b.append(f.readlines())
Buffer object type is available using "Buffer" attribute of vim module.
Examples (assume b is the current buffer)
:py print b.name # write the buffer file name
:py b[0] = "hello!!!" # replace the top line
:py b[:] = None # delete the whole buffer
:py del b[:] # delete the whole buffer
:py b[0:0] = [ "a line" ] # add a line at the top
:py del b[2] # delete a line (the third)
:py b.append("bottom") # add a line at the bottom
:py n = len(b) # number of lines
:py (row,col) = b.mark('a') # named mark
:py r = b.range(1,5) # a sub-range of the buffer
:py b.vars["foo"] = "bar" # assign b:foo variable
:py b.options["ff"] = "dos" # set fileformat
:py del b.options["ar"] # same as :set autoread<
:py b[0] = "hello!!!" # replace the top line
:py b[:] = None # delete the whole buffer
:py del b[:] # delete the whole buffer
:py b[0:0] = [ "a line" ] # add a line at the top
:py del b[2] # delete a line (the third)
:py b.append("bottom") # add a line at the bottom
:py n = len(b) # number of lines
:py (row,col) = b.mark('a') # named mark
:py r = b.range(1,5) # a sub-range of the buffer
:py b.vars["foo"] = "bar" # assign b:foo variable
:py b.options["ff"] = "dos" # set fileformat
:py del b.options["ar"] # same as :set autoread<
==============================================================================
4. Range objects python-range
Range objects represent a part of a vim buffer. You can obtain them in a
number of ways:
- via vim.current.range (python-current)
- from a buffer's range() method (python-buffer)
A range object is almost identical in operation to a buffer object. However,
all operations are restricted to the lines within the range (this line range
can, of course, change as a result of slice assignments, line deletions, or
the range.append() method).
The range object attributes are:
r.start Index of first line into the buffer
r.end Index of last line into the buffer
The range object methods are:
r.append(str) Append a line to the range
r.append(str, nr) Idem, after line "nr"
r.append(list) Append a list of lines to the range
Note that the option of supplying a list of strings to
the append method differs from the equivalent method
for Python's built-in list objects.
r.append(list, nr) Idem, after line "nr"
Range object type is available using "Range" attribute of vim module.
Example (assume r is the current range):
# Send all lines in a range to the default printer
vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))
vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))
==============================================================================
5. Window objects python-window
Window objects represent vim windows. You can obtain them in a number of ways:
- via vim.current.window (python-current)
- from indexing vim.windows (python-windows)
- from indexing "windows" attribute of a tab page (python-tabpage)
- from the "window" attribute of a tab page (python-tabpage)
You can manipulate window objects only through their attributes. They have no
methods, and no sequence or other interface.
Window attributes are:
buffer (read-only) The buffer displayed in this window
cursor (read-write) The current cursor position in the window
This is a tuple, (row,col).
height (read-write) The window height, in rows
width (read-write) The window width, in columns
vars (read-only) The window w: variables. Attribute is
unassignable, but you can change window
variables this way
options (read-only) The window-local options. Attribute is
unassignable, but you can change window
options this way. Provides access only to
window-local options, for buffer-local use
python-buffer and for global ones use
python-options. If option is global-local
and local value is missing getting it will
return None.
number (read-only) Window number. The first window has number 1.
This is zero in case it cannot be determined
(e.g. when the window object belongs to other
tab page).
row, col (read-only) On-screen window position in display cells.
First position is zero.
tabpage (read-only) Window tab page.
valid (read-write) True or False. Window object becomes invalid
when corresponding window is closed.
The height attribute is writable only if the screen is split horizontally.
The width attribute is writable only if the screen is split vertically.
Window object type is available using "Window" attribute of vim module.
==============================================================================
6. Tab page objects python-tabpage
Tab page objects represent vim tab pages. You can obtain them in a number of
ways:
- via vim.current.tabpage (python-current)
- from indexing vim.tabpages (python-tabpages)
You can use this object to access tab page windows. They have no methods and
no sequence or other interfaces.
Tab page attributes are:
number The tab page number like the one returned by
tabpagenr().
windows Like python-windows, but for current tab page.
vars The tab page t: variables.
window Current tabpage window.
valid True or False. Tab page object becomes invalid when
corresponding tab page is closed.
TabPage object type is available using "TabPage" attribute of vim module.
==============================================================================
7. vim.bindeval objects python-bindeval-objects
vim.Dictionary object python-Dictionary
Dictionary-like object providing access to vim Dictionary type.
Attributes:
Attribute Description
locked One of python-.locked
Value Description
zero Variable is not locked
vim.VAR_LOCKED Variable is locked, but can be unlocked
vim.VAR_FIXED Variable is locked and can't be unlocked
Read-write. You can unlock locked variable by assigning
True or False to this attribute. No recursive locking
is supported.
scope One of
Value Description
zero Dictionary is not a scope one
vim.VAR_DEF_SCOPE g: or l: dictionary
vim.VAR_SCOPE Other scope dictionary,
see internal-variables
Methods (note: methods do not support keyword arguments):
Method Description
keys() Returns a list with dictionary keys.
values() Returns a list with dictionary values.
items() Returns a list of 2-tuples with dictionary contents.
update(iterable), update(dictionary), update(**kwargs)
Adds keys to dictionary.
get(key[, default=None])
Obtain key from dictionary, returning the default if it is
not present.
pop(key[, default])
Remove specified key from dictionary and return
corresponding value. If key is not found and default is
given returns the default, otherwise raises KeyError.
popitem()
Remove random key from dictionary and return (key, value)
pair.
has_key(key)
Check whether dictionary contains specified key, similar
to `key in dict`.
__new__(), __new__(iterable), __new__(dictionary), __new__(update)
You can use vim.Dictionary() to create new vim
dictionaries. d=vim.Dictionary(arg) is the same as
d=vim.bindeval('{}');d.update(arg). Without arguments
constructs empty dictionary.
Examples:
d = vim.Dictionary(food="bar") # Constructor
d['a'] = 'b' # Item assignment
print d['a'] # getting item
d.update({'c': 'd'}) # .update(dictionary)
d.update(e='f') # .update(**kwargs)
d.update((('g', 'h'), ('i', 'j'))) # .update(iterable)
for key in d.keys(): # .keys()
for val in d.values(): # .values()
for key, val in d.items(): # .items()
print isinstance(d, vim.Dictionary) # True
for key in d: # Iteration over keys
class Dict(vim.Dictionary): # Subclassing
d['a'] = 'b' # Item assignment
print d['a'] # getting item
d.update({'c': 'd'}) # .update(dictionary)
d.update(e='f') # .update(**kwargs)
d.update((('g', 'h'), ('i', 'j'))) # .update(iterable)
for key in d.keys(): # .keys()
for val in d.values(): # .values()
for key, val in d.items(): # .items()
print isinstance(d, vim.Dictionary) # True
for key in d: # Iteration over keys
class Dict(vim.Dictionary): # Subclassing
Note: when iterating over keys you should not modify dictionary.
vim.List object python-List
Sequence-like object providing access to vim List type.
Supports .locked attribute, see python-.locked. Also supports the
following methods:
Method Description
extend(item) Add items to the list.
__new__(), __new__(iterable)
You can use vim.List() to create new vim lists.
l=vim.List(iterable) is the same as
l=vim.bindeval('[]');l.extend(iterable). Without
arguments constructs empty list.
Examples:
l = vim.List("abc") # Constructor, result: ['a', 'b', 'c']
l.extend(['abc', 'def']) # .extend() method
print l[1:] # slicing
l[:0] = ['ghi', 'jkl'] # slice assignment
print l[0] # getting item
l[0] = 'mno' # assignment
for i in l: # iteration
print isinstance(l, vim.List) # True
class List(vim.List): # Subclassing
l.extend(['abc', 'def']) # .extend() method
print l[1:] # slicing
l[:0] = ['ghi', 'jkl'] # slice assignment
print l[0] # getting item
l[0] = 'mno' # assignment
for i in l: # iteration
print isinstance(l, vim.List) # True
class List(vim.List): # Subclassing
vim.Function object python-Function
Function-like object, acting like vim Funcref object. Accepts special
keyword argument self, see Dictionary-function. You can also use
vim.Function(name) constructor, it is the same as
vim.bindeval('function(%s)'%json.dumps(name)).
Attributes (read-only):
Attribute Description
name Function name.
args None or a python-List object with arguments. Note
that this is a copy of the arguments list, constructed
each time you request this attribute. Modifications made
to the list will be ignored (but not to the containers
inside argument list: this is like copy() and not
deepcopy()).
self None or a python-Dictionary object with self
dictionary. Note that explicit self keyword used when
calling resulting object overrides this attribute.
auto_rebind Boolean. True if partial created from this Python object
and stored in the Vim script dictionary should be
automatically rebound to the dictionary it is stored in
when this dictionary is indexed. Exposes Vim internal
difference between dict.func (auto_rebind=True) and
function(dict.func,dict) (auto_rebind=False). This
attribute makes no sense if self attribute is None.
Constructor additionally accepts args, self and auto_rebind
keywords. If args and/or self argument is given then it constructs
a partial, see function(). auto_rebind is only used when self
argument is given, otherwise it is assumed to be True regardless of
whether it was given or not. If self is given then it defaults to
False.
Examples:
f = vim.Function('tr') # Constructor
print f('abc', 'a', 'b') # Calls tr('abc', 'a', 'b')
vim.command('''
function DictFun() dict
return self
endfunction
''')
f = vim.bindeval('function("DictFun")')
print f(self={}) # Like call('DictFun', [], {})
print isinstance(f, vim.Function) # True
print f('abc', 'a', 'b') # Calls tr('abc', 'a', 'b')
vim.command('''
function DictFun() dict
return self
endfunction
''')
f = vim.bindeval('function("DictFun")')
print f(self={}) # Like call('DictFun', [], {})
print isinstance(f, vim.Function) # True
p = vim.Function('DictFun', self={})
print f()
p = vim.Function('tr', args=['abc', 'a'])
print f('b')
print f()
p = vim.Function('tr', args=['abc', 'a'])
print f('b')
==============================================================================
8. pyeval() and py3eval() Vim functions python-pyeval
To facilitate bi-directional interface, you can use pyeval() and py3eval()
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.
==============================================================================
9. Dynamic loading python-dynamic
On MS-Windows and Unix the Python library can be loaded dynamically. The
:version output then includes +python/dyn or +python3/dyn.
This means that Vim will search for the Python DLL or shared library file only
when needed. When you don't use the Python interface you don't need it, thus
you can use Vim without this file.
MS-Windows
To use the Python interface the Python DLL must be in your search path. In a
console window type "path" to see what directories are used. If the DLL is
not found in your search path, Vim will check the registry to find the path
where Python is installed. The 'pythondll' or 'pythonthreedll' option can be
also used to specify the Python DLL.
The name of the DLL should match the Python version Vim was compiled with.
Currently the name for Python 2 is "python27.dll", that is for Python 2.7.
That is the default value for 'pythondll'. For Python 3 it is python36.dll
(Python 3.6). To know for sure edit "gvim.exe" and search for
"python\d*.dll\c".
Unix
The 'pythondll' or 'pythonthreedll' option can be used to specify the Python
shared library file instead of DYNAMIC_PYTHON_DLL or DYNAMIC_PYTHON3_DLL file
what were specified at compile time. The version of the shared library must
match the Python 2.x or Python 3 version (v:python3_version) Vim was
compiled with unless using python3-stable-abi.
Stable ABI and mixing Python versions
python-stable python-stable-abi python3-stable-abi
If Vim was not compiled with Stable ABI (only available for Python 3), the
version of the Python shared library must match the version that Vim was
compiled with. Otherwise, mixing versions could result in unexpected crashes
and failures. With Stable ABI, this restriction is relaxed, and any Python 3
library with version of at least v:python3_version will work. See
has-python for how to check if Stable ABI is supported, or see if version
output includes +python3/dyn-stable.
On MS-Windows, 'pythonthreedll' will be set to "python3.dll". When searching
the DLL from the registry, Vim will search the latest version of Python.
==============================================================================
10. Python 3 python3
:py3 :python3
:[range]py3 {stmt}
:[range]py3 << [trim] [{endmarker}]
{script}
{endmarker}
:[range]python3 {stmt}
:[range]python3 << [trim] [{endmarker}]
{script}
{endmarker}
The :py3 and :python3 commands work similar to :python. A
simple check if the :py3 command is working:
:py3 print("Hello")
To see what version of Python you have:
:py3 import sys
:py3 print(sys.version)
:py3file:py3 print(sys.version)
:[range]py3f[ile] {file}
The :py3file command works similar to :pyfile.
:py3do
:[range]py3do {body}
The :py3do command works similar to :pydo.
Vim can be built in four ways (:version output):
1. No Python support (-python, -python3)
2. Python 2 support only (+python or +python/dyn, -python3)
3. Python 3 support only (-python, +python3 or +python3/dyn)
4. Python 2 and 3 support (+python/dyn, +python3/dyn)
Some more details on the special case 4: python-2-and-3
When Python 2 and Python 3 are both supported they must be loaded dynamically.
When doing this on Linux/Unix systems and importing global symbols, this leads
to a crash when the second Python version is used. So either global symbols
are loaded but only one Python version is activated, or no global symbols are
loaded. The latter makes Python's "import" fail on libraries that expect the
symbols to be provided by Vim.
E836 E837
Vim's configuration script makes a guess for all libraries based on one
standard Python library (termios). If importing this library succeeds for
both Python versions, then both will be made available in Vim at the same
time. If not, only the version first used in a session will be enabled.
When trying to use the other one you will get the E836 or E837 error message.
Here Vim's behavior depends on the system in which it was configured. In a
system where both versions of Python were configured with --enable-shared,
both versions of Python will be activated at the same time. There will still
be problems with other third party libraries that were not linked to
libPython.
To work around such problems there are these options:
1. The problematic library is recompiled to link to the according
libpython.so.
2. Vim is recompiled for only one Python version.
3. You undefine PY_NO_RTLD_GLOBAL in auto/config.h after configuration. This
may crash Vim though.
E880
Raising SystemExit exception in python isn't endorsed way to quit vim, use:
:py vim.command("qall!")
E1266
This error can occur when Python 3 cannot load the required modules. This
means that your Python 3 is not correctly installed or there are some mistakes
in your settings. Please check the following items:
1. Make sure that Python 3 is correctly installed. Also check the version of
python.
2. Check the 'pythonthreedll' option.
3. Check the 'pythonthreehome' option.
4. Check the PATH environment variable if you don't set 'pythonthreedll'.
On MS-Windows, you can use where.exe to check which dll will be loaded.
E.g.
where.exe python310.dll
5. Check the PYTHONPATH and PYTHONHOME environment variables.has-python
You can test what Python version is available with:
if has('python')
echo 'there is Python 2.x'
endif
if has('python3')
echo 'there is Python 3.x'
endif
echo 'there is Python 2.x'
endif
if has('python3')
echo 'there is Python 3.x'
endif
Note however, that when Python 2 and 3 are both available and loaded
dynamically, these has() calls will try to load them. If only one can be
loaded at a time, just checking if Python 2 or 3 are available will prevent
the other one from being available.
To avoid loading the dynamic library, only check if Vim was compiled with
python support:
if has('python_compiled')
echo 'compiled with Python 2.x support'
if has('python_dynamic')
echo 'Python 2.x dynamically loaded'
endif
endif
if has('python3_compiled')
echo 'compiled with Python 3.x support'
if has('python3_dynamic')
echo 'Python 3.x dynamically loaded'
endif
endif
echo 'compiled with Python 2.x support'
if has('python_dynamic')
echo 'Python 2.x dynamically loaded'
endif
endif
if has('python3_compiled')
echo 'compiled with Python 3.x support'
if has('python3_dynamic')
echo 'Python 3.x dynamically loaded'
endif
endif
When loading the library dynamically, Vim can be compiled to support Python 3
Stable ABI (python3-stable-abi) which allows you to load a different version
of Python 3 library than the one Vim was compiled with. To check it:
if has('python3_dynamic')
if has('python3_stable')
echo 'support Python 3 Stable ABI.'
else
echo 'does not support Python 3 Stable ABI.'
echo 'only use Python 3 version ' .. v:python3_version
endif
endif
if has('python3_stable')
echo 'support Python 3 Stable ABI.'
else
echo 'does not support Python 3 Stable ABI.'
echo 'only use Python 3 version ' .. v:python3_version
endif
endif
This also tells you whether Python is dynamically loaded, which will fail if
the runtime library cannot be found.
==============================================================================
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 written. 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)
: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.#!/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'.
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
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
set pyx=2
elseif has('python3')
set pyx=3
endif
==============================================================================
12. Building with Python support python-building
A few hints for building with Python 2 or 3 support.
UNIX
See src/Makefile for how to enable including the Python interface.
On Ubuntu you will want to install these packages for Python 2:
python
python-dev
For Python 3:
python3
python3-dev
For Python 3.6:
python3.6
python3.6-dev
If you have more than one version of Python 3, you need to link python3 to the
one you prefer, before running configure.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl: