diff --git a/README.md b/README.md new file mode 100644 index 0000000..e569eba --- /dev/null +++ b/README.md @@ -0,0 +1,109 @@ +# Example Python Plugin for Neovim + +As part of the changes included in Neovim there is a new plugin model where +plugins are separate processes which Neovim communicates to using the +MessagePack protocol. + +Since plugins are distinct from the Neovim process, it is possible to write +plugins in many languages. + +This is a minimal example of a Python plugin. You should be able to (and feel +free to) copy this repository, rename a couple files, include the plugin in +your Vim config and see something happen. + +## Making a New Plugin + +The intention of this repository is to make it quick and easy to start a new +plugin. It is just enough to show how to make the basics work. + +```Bash +git clone --depth 1 https://github.com/jacobsimpson/nvim-example-python-plugin ~/.vim/bundles +rm -Rf ~/.vim/bundles/nvim-example-python-plugin/.git +``` + +## Configuring Vim + +I use NeoBundle so this is an example of how to load this plugin in NeoBundle. + +```VimL +" Required: +call neobundle#begin(expand('~/.vim/bundle/')) + + " Let NeoBundle manage NeoBundle + " Required: + NeoBundleFetch 'Shougo/neobundle.vim' + + " You probably have a number of other plugins listed here. + + " Add this line to make your new plugin load, assuming you haven't renamed it. + NeoBundle 'nvim-example-python-plugin' +call neobundle#end() +``` + +## Confirming the Plugin Loaded + +There is some VimL in the plugin that will print when Neovim is starting up: + + Starting the example Python Plugin + +That will confirm that the VimL portions of the plugin are loading correctly. +That does not guarantee that the Python portions of the plugin are loading. + +It should create a function that can be called. + +```VimL +:exec DoItVimL() +``` + +```VimL +:exec DoItPython() +``` + +It should add some mapped key handlers. + +## Changing the Interface + +Neovim includes a process whereby the interface of the remote plugin are cached +for Neovim. + +```VimL +:UpdateRemotePlugins +``` + +Run this command for *every* change in the plugin interface. Without this, you +may see errors on from Neovim telling you methods are missing from your plugin. +Or the new functionality you are trying to add just won't work. + +## Troubleshooting + +### Python Client Log File + +Define this environment variable to get output logged from your Python client. + +```Bash +export NVIM_PYTHON_LOG_FILE=${HOME}/.nvim-python.log +``` + +The output files will have a number appended, and should be visible with this: + +```Bash +ls ${HOME}/.nvim-python.log* +``` + +### Neovim Log File + +```Bash +ls ~/.nvimlog +``` + +### Neovim Library + +I found that the Python neovim module was not installed on my system. I didn't +see any great errors that lead me to that conclusion, so it is worth checking: + +```Bash +python -c "import neovim" +``` + +Should execute without an error. + diff --git a/doc/nvim-example-python-plugin.txt b/doc/nvim-example-python-plugin.txt new file mode 100644 index 0000000..5d47c52 --- /dev/null +++ b/doc/nvim-example-python-plugin.txt @@ -0,0 +1,19 @@ +*nvim-example-python-plugin.txt* A template of a remote Python plugin. + + Example Remote Python Plugin + +============================================================================== + +CONTENTS *nvim-example-python-plugin-contents* + + 1. Introduction .................... |nvim-example-python-plugin-intro| + + +Original Author: Jacob Simpson +License: The Unlicense + +INTRODUCTION *nvim-example-python-plugin-intro* + +A very simple example of a Python plugin in the new remote plugin style used by +Neovim. + diff --git a/doc/tags b/doc/tags new file mode 100644 index 0000000..6e69701 --- /dev/null +++ b/doc/tags @@ -0,0 +1,3 @@ +nvim-example-python-plugin-contents nvim-example-python-plugin.txt /*nvim-example-python-plugin-contents* +nvim-example-python-plugin-intro nvim-example-python-plugin.txt /*nvim-example-python-plugin-intro* +nvim-example-python-plugin.txt nvim-example-python-plugin.txt /*nvim-example-python-plugin.txt* diff --git a/plugin/nvim-example-python-plugin.vim b/plugin/nvim-example-python-plugin.vim new file mode 100644 index 0000000..b9038c2 --- /dev/null +++ b/plugin/nvim-example-python-plugin.vim @@ -0,0 +1,6 @@ + +echo "Starting the example Python Plugin" + +function DoItVimL() + echo "DoItVimL" +endfunction diff --git a/rplugin/python/nvim-example-python-plugin.py b/rplugin/python/nvim-example-python-plugin.py new file mode 100644 index 0000000..01ca36a --- /dev/null +++ b/rplugin/python/nvim-example-python-plugin.py @@ -0,0 +1 @@ +Autocmd: Called file: nvim-example-python-plugin.py diff --git a/rplugin/python/nvim-example-python-plugin/__init__.py b/rplugin/python/nvim-example-python-plugin/__init__.py new file mode 100644 index 0000000..f0c6ede --- /dev/null +++ b/rplugin/python/nvim-example-python-plugin/__init__.py @@ -0,0 +1,11 @@ +import neovim + +@neovim.plugin +class Limit(object): + def __init__(self, vim): + self.vim = vim + + @neovim.function('DoItPython') + def function_handler(self, args): + self.vim.command('echo "hello"') + diff --git a/rplugin/python/nvim-example-python-plugin/__init__.pyc b/rplugin/python/nvim-example-python-plugin/__init__.pyc new file mode 100644 index 0000000..e15f467 Binary files /dev/null and b/rplugin/python/nvim-example-python-plugin/__init__.pyc differ