The Vim Python Extensions (VPE)¶
Introduction¶
VPE adds to Vim’s built-in support for Python scripting with the following aims.
Ability to write more Pythonic code.
Provide a toolkit of additional classes and functions to support complex plug-ins.
Be extremely compatible with existing Vim Python scripts.
Requirements¶
VPE requires a minimum of Vim 8.0.0700 and Python 3.6.
VPE has not been tested on Windows.
Installation¶
The VPE directory tree is structured as a package with a single plugin. Assuming your Vim files are in the “~/.vim” directory, add a “pack” sub-directory and install VPE into the “~/.vim/pack” directory. One way to do this is by simply cloning the VPE repository.
$ cd ~/.vim/pack
$ git clone https://github.com/paul-ollis/vim-vpe.git
or just unzip vim-vpe.zip.
$ cd ~/.vim/pack
$ unzip vim-vpe.zip
The package includes a “vim-vpe/start/vpe/plugin/vpe.vim” startup script that updates the Python path so that the vpe package can be imported.
Quick start¶
The quickest way to start using VPE is to import the vim
object:
from vpe import vim
The vim
object is an instance of the vpe.Vim
class and is intended to
be a drop in replacement for Vim’s standard python-vim module, but with
a number of enhancements.
Most of Vim’s functions appear as members, for example:
vim.cursor(4, 10) # Position cursor at row 4, column 10. m = vim.execute('messages') # Get all the recent Vim messagse.
The attributes buffers, current, options, tabpages, vars, vvars and windows provide enhanced access to the corresponding Vim objects. For example vim.current.buffer provides a
Buffer
instance in place of Vim’s standard python-buffer.The Vim registers are available using the
registers
attribute.When errors occur a
VimError
is raised, which provides a better breakdown of the error. This is a subclass of vim.error (python-error) so existing code that catches vim.error still works.
Features¶
This is a brief list of VPE’s features.
A
Vim
class that provides an enhanced, drop-in replacement for the standard python-vim module.Classes
Window
,Buffer
,TabPage
are enhanced wrappers around the standard vim versions.Support for cleanly invoking Python functions for keyboard mappings.
Pythonic support for using popup-windows. (Requires Vim 8.2.)
Pythonic support for using timers.
Pythonic support for autocommands that invoke Python functions.
Python support for channels.
Logging to a buffer. Useful when developing and debugging plug-ins.