VPE plug-in mechanism¶
Vim’s default plug-in mechanism¶
Using Vim’s standard mechanism for VPE based plug-ins is a bit fiddly because:
You need a vim script file that then imports and initialises the actual Python code. Note that is it not a good idea to simply put all the code within ‘python3 <<EOF … EOF’ because that will pollute Vim’s global Python namespace.
Such plug-ins depend on the VPE plug-in being loaded first.
So the Vim Python Extensions (VPE) provides a framework that simplifies writing plug-ins in Python.
Plug-in structure¶
A plug-in is basically Python module or package. In order to be recognised as a VPE plug-in that should automatically be loaded, the module or package’s __init__.py must have docstring that starts with ‘VPE-plugin: ‘ (note the space after the colon). For example:
"""VPE-plugin: Spam file support from within Vim."""
Triple, double quotes must be used and the docstring must start on line 1. If a plug-in does not start like this then it is simply a library for other plug-in code.
All VPE plug-ins are installed in:
$HOME/.vim/pack/vpe_plugins Unix
$HOME/vimfiles/pack/vpe_plugins Windows
Plug-in loading and initialisation¶
Loading¶
VPE plug-ins are loaded after other Vim startup (by using the VimEnter auto command). VPE scans the vpe_plugins directory for auto-loadable plug-in modules and packages during normal Vim start up.
Each one it finds is loaded by simply importing it as a sub-module or sub-pakage of the vpe_plugins package. For example if your plugin file is my_plugin.py then VPE will import it as:
import vpe_plugins.my_plugin
Initialisation¶
Since a plug-in is imported, its top level code performs any necessary initialisation. This will, of course, only be executed the first time it is imported
Dependencies¶
A plug-in can use code from other plug-in by simply importing its code. For example my_plugin.py can use their_plugin.py by doing:
from vpe_plugins import their_plugin