sponsor Vim development Vim logo Vim Book Ad

VPE - Vim Python Extensions : Extension for Vim scripting using Python 3

 script karma  Rating 4/1, Downloaded by 589  Comments, bugs, improvements  Vim wiki

created by
Paul Ollis
script type
  The official documentation is now at https://vim-vpe.readthedocs.io/en/stable.
  This documentation is working towards a comprehensive user guide, including
  API documentation. The help file included with VPE is mainly only the API.  

  A lot has been added since version 0.4, most significantly in areas that
  make writing and maintaining non-trivial plug-ins easier.


  VPE requires a minimum of Vim 8.0.0700 and Python 3.6.

  VPE is tested on Linux and Windows 10. On Windows, testing is done using Vim
  8.2.1970 and Python 3.8.6. On Linux testing is done using
  Vim-8.0.0700/Python-3.6.0 and very recent versions of both vim and Python.

    Although it has not yet reached a version 1.0 release, I believe that VPE
    is quite stable. I make heavy, daily use of VPE within my (Linux) Vim
    environment without problems.

    While the API should be considered unstable, it has actually proven fairly
    stable, with only a few, minor incompatible changes since version 0.1.


  VPE adds to Vim’s built-in support for Python scripting. 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, user
    defined commands and events.

    New in 0.5 is support for using Python decorators to set up these mappings.

  - Pythonic support for using popup-windows. (Requires Vim 8.2.)

  - Pythonic support for using timers; when a timer fires a Python function is

  - Pythonic support for channels.

  - Syntax class and supporting context managers to define highlighting.

  - Logging to a buffer. Useful when developing and debugging plug-ins.
    When active in a window, the window automatically scrolls to show new

  - A plug-in support mechanism. I find this more convenient for non-trivial
    Python based plug-ins.

  - Other relatively high level support for non-trivial plug-ins. This includes
    management of configuration values, scratch (display only) buffers,
    user-interface like components (panels and fields).

  The above just scratches the surface, see :help vpe.txt for detailed
  documentation or the more readable form at https://vim-vpe.readthedocs.io/.

Source code

  The source code is maintained at https://github.com/paul-ollis/vim-vpe.git.
  You can raise bugs or feature requests there.

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 Vim class and is intended to be a drop
  in replacement for Vim’s standard python-vim module, but with a number of

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

  - 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 so existing
    code that catches vim.error still works.


  Please treat the examples as demo, minimally tested code.

  The examples provided with VPE are:

    vpe_filenav - start with, ':runtime examples/vpe_filenav.vim'

      A very simple file explorer that can be used to open files.

    vpe_bufnav - start with, ':runtime examples/vpe_bufnav.vim'

      An explorer for buffers. This is heavily inspired by Jeff
      Lanzarotta's excellent vimscript #42, but it does not attempt to be
      a clone.
install details
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.

    $ 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.

The source code is at https://github.com/paul-ollis/vim-vpe.git. You can clone
this into ~/.vim/pack, but that will, currently, not include the Vim help file.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vim-vpe-0.6.zip 0.6 2021-09-14 8.0 Paul Ollis Version 0.6

- The main activity has been writing more of a user guide. The built-in Vim
  style help is now mainly reference. The full help is in HTML form - currently
  available at https://vim-vpe.readthedocs.io/en/userguide/.

- General

  - Fixed issue where VPE could fail to load its plugins.

  - Prevent some errors when getting application window information.

  - Reduce the likelyhood of callback failures passing silently.

  - The define_command function now allows the range argument to be True, which
    is equivalent to the Vim '-range' option without arguments.

  - The call_soon mechanism now logs a traceback upon failure.

- Refactoring

  - Cleaned up how single-shot timers are handled.

  - Moved a lot of code into vpe.common.

- AutoCmdGroup

  - Additional keyword arguments may now be passed to the function handling an

- Channel

  - The on_connect method is now invoked via call_soon.

  - The closed property was fixed to prevent an exception.

  - The on_message method is now invoked via call_soon.

  - Added a read method to allow explicit channel reading.

  - Prevent Vim error when closing an already closed channel.

- Popup windows

  - Better detection of mouse events, by adding hard coded sequences.

  - Made the textprop, textpropif and textpropwin properties read/write.

  - Tidied up handling of keys with modifiers.

  - The buffer property is now None where it would previously raise an

  - Added setoptions and move methods.

- Buffer

  - Added an add_listener method. Provides a hook into Vim's listener_add
    mechanism. Treat this feature as quite experimental.

- ScratchBuffer

  - The init_options method now does nothing, it exists only to be
    over-ridden by subclasses.
vim-vpe-0.5.2.zip 0.5.2 2021-03-20 8.0 Paul Ollis Version 0.5.2

- Big change to colors.py. Should not affect the existing API.

- Better window size behaviour when displaying ScratchBuffers.

- Fix invalid characters in generated autogrp names.

- Add support for VPE plugin help files.

- Better preserve types for option access.
vim-vpe-0.5.1.zip 0.5.1 2021-03-12 8.0 Paul Ollis Version 0.5.1

- Added a load of missing API documentation that I foolishly forgot about.

- The temp_active_buffer context manager now also preserves the window's
vim-vpe-0.5.zip 0.5 2021-03-09 8.0 Paul Ollis Version 0.5

- Try to prevent VPE's help obscuring help for standard Vim commands and

- Added plugin system; I find this easier to use for Python based plug-ins.

- Key mappings, user commands and auto commands now show the Python function

- Allow key mappings and user commands that do not pass an info object.

- Support creating key mappings that simply expand as strings; for when a Python
  fucnction is overkill.

- All commands available via vpe.commands now get prefixed with 'keepalt' by
  default. This is a backwardly incompatible change, but should have minimal
  impact on existing code.

- New modules.

  - vpe.windows. Provides a wrapping around the output of winlayout().

  - vpe.app_ui_support. Provides a way to query information about Vim's
    application window when runninf on an X-desktop.

  - vpe.config. Provides a mechanism defined configuration values which can
    stored on disk.

  - vpe.panels. Provides an extension to ScratchBuffer that horizontally
    divides the buffer into one or more independent panels.

  - vpe.ui. Adds user interaction support, building on vpe.panels. Currently
    it is focussed on supporting interactive modification of values managed by

- New and modified functions.

  - Added 'soon' argument to error_msg.

  - Added echo_msg and warning_msg (to match error_msg).

  - Added temp_active_window context manager.

  - Added saved_current_window and temp_active_buffer context managers.

- New classes

  - CommandHandler, EventHandler, BufEventHandler and KeyHandler. These support
    using Python decorators as a clean way to map user commands, event and key
    sequences to Python methods.

- Buffer class

  - Enhanced the show method to allow vertical splits and provide more
    flexibility in how line/columns are allocated to each half of the split.

  - Added a split_and_show method.

  - Added is_active method. Return True if the buffer is showing in the current

  - Methods find_active_windows and goto_active_window now only search the
    current tab page by default. This is backwardly incompatible. Also added

- TemporaryOptions class

  - Added a save method.

- Syntax class

  - Can be used without clearing previous syntax items.

- Window class

  - Added a close method.

- Vim class

  - Added iter_all_windows method.

- Syntax class

  - It is not possible to prevent automatic deletion of old syntax.

- ScratchBuffer class

  - New method on_first_showing is invoked when the buffer is first shown. This
    is intended to be over-ridden or extended.

  - Added auto_grp_name and syntax_prefix properties. These are useful to avoid
    name clashes when adding syntax and auto commands.

- Added support for vertical, aboveleft, belowright, topleft, botright and
  keepalt modifiers for vpe.commands.

- Provide mechanism to reset a Vim option to its default value.

- Work around an issue where Vim can consume large amounts of memory due to
  code executed by timer. This could only occur when a Vim session was left
  without focus.
vim-vpe-0.4.1.zip 0.4.1 2020-11-23 8.0 Paul Ollis - Log class.
  - Changed the way the buffer contents are trimmed. Prevents (or at least
    reduces) annoying window redraws/corruption.
vim-vpe-0.4.zip 0.4 2020-11-21 8.0 Paul Ollis - Works on Windows (10).
- General
  - Added dot_vim_dir function.
  - List style options are now always converted
    from bytes to str.
- Buffer class
  - Added find_active_windows method.
  - The ScratchBuffer can now be usefully sub-classed.
  - Added set_ext_name method.
- Windows class.
  - Added visible_line_range property.
- Timers
  - Fixed bug for single shot timers.
vim-vpe-0.3.zip 0.3 2020-11-06 8.0 Paul Ollis - Fixed issue with examples running 'out-of-the-box'.
- Added a version() function to the vpe module.
- Added define_command function.
  - User commands that call Python.
- Timers
  - Added fire_count attribute.
  - Added dead attribute.
  - Fixed timer clean up.
- Fix to error_msg to restore message colour.
- Add Syntax.include method.
vim-vpe-0.2.zip 0.2 2020-10-27 8.0 Paul Ollis Documentation improvements (still needs work).
Some internal code refactoring.
Improved logging of run-time errors (to log buffer).
Syntax class:
  - Added link_to argument to group method.
  - Prevent annoying warning message.
Buffer class:
  - Added new properties: type, location, long_display_name,
    short_display_name, short_description, bufnr, changed, changedtick,
    lastused, lnum, linecount, loaded, variables, windows and popups.
  - Added goto_active_window method.
Started adding some examples as a supplement to the documentation.
The HTML help is now available on readthdocs.
vim-vpe.zip 0.1 2020-10-02 8.0 Paul Ollis Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.