Quick Start

Check out the example plugin if you'd like to see an implementation of a plugin using Vimpy. All you have to do is define a python package in your project directory, and Vimpy will automatically import it. It is expected that you follow Python standard conventions for module names when naming your Vimpy projects, so that other projects can import your modules.

For instance, with the VimpyExample plugin Vimpy will automatically attempt the following during initialization:

import vimpy_example
import vimpy_example.commands
import vimpy_example.plugin

Vimpy will catch any ImportError exceptions thrown by these import commands, so it isn't required that your modules define unused Python modules.

Plugins

If your module does happen to have a plugin.py file, then your module is able to handle autocommands. You handle autocommands by defining a "Plugin" object which has event handlers for the different autocommands

All autocommands can be defined inside of your Plugin object methods wit snake-case / Pythonic names. So, for instance - I could bind to VimEnter like so:

import vimpy

class VimplyExamplePlugin(vimpy.Plugin):
    def vim_enter(self, data=None):
        print('Example VimEnter called.')

Vimpy automatically observes your Plugin classes, so all this package needs to do is instantiate a plugin object for it to start receiving autocommand events.

Variables

Vimpy also exposes Vim's variables using a more Pythonic interface. For instance, you could do the following to see the key bound to mapleader if you were inclined to do so:

from vimpy import variables
print(variables.globals['mapleader'])

or you could do this to see the current buffer's syntax setting:

from vimpy import variables
print(variables.buffer['current_syntax'])

Vimpy also makes setting variables just as simple:

from vimpy import variables
variables.globals['example_data'] = 'Okay!'

This allows you to change many Vim options - as well as options for plugins which don't provide a Pythonic interface. Other plugins can access these variables just as you would expect. For instance, you could check the value of the variable that we just set by simply executing :echo g:example_data from Vim's command mode.

What to do next?

Now that you understand the basic organizational structure of a Vimpy plugin, go ahead and refer back to the wiki's home page for more specific pages.