_    ______  ______
| |  / / __ \/ ____/
| | / / /_/ / __/     The Vim Python Extensions
| |/ / ____/ /___
|___/_/   /_____/

Welcome to the Vim Python Extensions (VPE).

status:	This is version 0.7.3. The Version 0.7 line is intended to be the stepping stone for version 1.0. Although it has not yet reached a version 1.0 release, I make heavy, daily use of VPE within my Vim environment without problems. While the API should be considered unstable, it has actually proven largely stable, with only a few, minor incompatible changes since version 0.1.

Introduction

VPE provides a toolkit of modules and classes aimed at making it easier to extend Vim using modern Pythonic code. The headline features are:

• Instead of using the standard vim module you can use the vpe.vim object, which provides a greatly extended superset of the vim module's features.
• Other extensions that, along with vpe.vim, just make it easier to write Pythonic plugin code for Vim.

Installation

Read the installation instructions online.

Using VPE

This is just a brief introduction. For more complete documentation see the online documentation.

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 Vim class, which is designed as a drop in replacement for Vim's standard python-vim module, but with a number of enhancements, including:

• 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 messages.

• 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. This supports things like easier access to buffer variables, more efficient buffer modification and per-buffer metadata storage.

• The Vim registers are available using the registers attribute.

• When errors occur a VimError is raised, which provides a better breakdown of the error (code and command are available as attributes). This is a subclass of vim.error so existing code that catches vim.error still works.

Features

This is a brief list of VPE's features.

• The vpe.vim object - a much enhanced replacement for the standard vim module (python-vim). This is an instance of the Vim class.
• Classes Window, Buffer, TabPage are enhanced wrappers around the standard (vim) versions.
• Key mappings can cleanly be set up to invoke Python functions and methods.
• User commands can cleanly be set up to invoke Python functions and methods. VPE also provides support for subcommands and automatic command line tab-key completion.
• Timers can cleanly be set up to invoke Python functions and methods.
• Autocmd Events can cleanly be set up to invoke Python functions and methods.
• A built in log, which is useful for debugging plugin code.
  • The log can be displayed in a dedicated Vim buffer.
  • Printing can be redirected to the log.
  • You can create your own plugin specific log(s).
• Pythonic support for using popup windows.
• Pythonic support for channels.