VPE - Vim Python Extensions : Extension for Vim scripting using Python 3
| script karma
Downloaded by 510
Comments, bugs, improvements
script versions (upload new version)
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
- Classes Window, Buffer, TabPage are enhanced wrappers around the standard
- 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/.
The source code is maintained at https://github.com/paul-ollis/vim-vpe.git.
You can raise bugs or feature requests there.
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
- 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
|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.
Click on the package to download.
ip used for rating: 22.214.171.124
- 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/.
- 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.
- Cleaned up how single-shot timers are handled.
- Moved a lot of code into vpe.common.
- Additional keyword arguments may now be passed to the function handling an
- 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.
- Added an add_listener method. Provides a hook into Vim's listener_add
mechanism. Treat this feature as quite experimental.
- The init_options method now does nothing, it exists only to be
over-ridden by subclasses.
- 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.
- Added a load of missing API documentation that I foolishly forgot about.
- The temp_active_buffer context manager now also preserves the window's
- 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
||- Log class.
- Changed the way the buffer contents are trimmed. Prevents (or at least
reduces) annoying window redraws/corruption.
||- Works on Windows (10).
- 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.
- Fixed bug for single shot timers.
||- 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.
- Added fire_count attribute.
- Added dead attribute.
- Fixed timer clean up.
- Fix to error_msg to restore message colour.
- Add Syntax.include method.
||Documentation improvements (still needs work).
Some internal code refactoring.
Improved logging of run-time errors (to log buffer).
- Added link_to argument to group method.
- Prevent annoying warning message.
- 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.