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.