Refactor to conform with Nvim external plugin infrastructure

- Move some code from plugin_host.py to script_host.py
- Remove script_host.py and tests, it now belongs in Neovim repository
- Rename "plugins" to "plugin"
- Add plugin/decorators.py module. Now plugins are defined with these
  decorators.
- Rename plugins/plugin_host.py to plugin/host.py
- Fix flake8 errors in plugin/host.py

Author: tarruda

.travis.yml

@@ -38,7 +38,7 @@ script:
       ./scripts/run-api-tests.exp "nosetests" "nvim -u NONE";
       NVIM_SPAWN_ARGV='["nvim", "-u", "NONE", "--embed"]' nosetests;
     else
-      flake8 --exclude ./neovim/plugins neovim;
+      flake8 neovim;
     fi
 after_script:
   - if [ $CI_TARGET = tests ]; then

neovim/__init__.py

@@ -4,15 +4,19 @@
 """
 import logging
 import os
+import sys
 
 from .api import DecodeHook, Nvim, SessionHook
 from .msgpack_rpc import (socket_session, spawn_session, stdio_session,
                           tcp_session)
-from .plugins import PluginHost, ScriptHost
+from .plugin import (Host, autocmd, command, encoding, function, plugin,
+                     rpc_export, shutdown_hook)
 
 
 __all__ = ('tcp_session', 'socket_session', 'stdio_session', 'spawn_session',
-           'start_host', 'DecodeHook', 'Nvim', 'SessionHook')
+           'start_host', 'autocmd', 'command', 'encoding', 'function',
+           'plugin', 'rpc_export', 'Host', 'DecodeHook', 'Nvim',
+           'SessionHook', 'shutdown_hook')
 
 
 def start_host(session=None):
@@ -30,6 +34,15 @@ def start_host(session=None):
     defined as a separate executable. It is exposed as a library function for
     testing purposes only.
     """
+    plugins = []
+    for arg in sys.argv:
+        _, ext = os.path.splitext(arg)
+        if ext == '.py':
+            plugins.append(arg)
+
+    if not plugins:
+        sys.exit('must specify at least one plugin as argument')
+
     logger = logging.getLogger(__name__)
     if 'NVIM_PYTHON_LOG_FILE' in os.environ:
         logfile = os.environ['NVIM_PYTHON_LOG_FILE'].strip()
@@ -48,9 +61,8 @@ def start_host(session=None):
         logger.setLevel(level)
     if not session:
         session = stdio_session()
-    nvim = Nvim.from_session(session)
-    with PluginHost(nvim, preloaded=[ScriptHost]) as host:
-        host.run()
+    host = Host(Nvim.from_session(session))
+    host.start(plugins)
 
 
 # Required for python 2.6

neovim/plugin/__init__.py

@@ -0,0 +1,9 @@
+"""Nvim plugin/host subpackage."""
+
+from .decorators import (autocmd, command, encoding, function, plugin,
+                         rpc_export, shutdown_hook)
+from .host import Host
+
+
+__all__ = ('Host', 'plugin', 'rpc_export', 'command', 'autocmd',
+           'function', 'encoding', 'shutdown_hook')

neovim/plugin/decorators.py

@@ -0,0 +1,144 @@
+"""Decorators used by python host plugin system."""
+import inspect
+
+
+import logging
+logger = logging.getLogger(__name__)
+debug, info, warn = (logger.debug, logger.info, logger.warn,)
+__all__ = ('plugin', 'rpc_export', 'command', 'autocmd', 'function',
+           'encoding', 'shutdown_hook')
+
+
+def plugin(cls):
+    """Tag a class as a plugin.
+
+    This decorator is required to make the a class methods discoverable by the
+    plugin_load method of the host.
+    """
+    cls._nvim_plugin = True
+    # the _nvim_bind attribute is set to True by default, meaning that
+    # decorated functions have a bound Nvim instance as first argument.
+    # For methods in a plugin-decorated class this is not required, because
+    # the class initializer will already receive the nvim object.
+    for _, fn in inspect.getmembers(cls, inspect.ismethod):
+        if hasattr(fn, '_nvim_bind'):
+            fn.im_func._nvim_bind = False
+    return cls
+
+
+def rpc_export(rpc_method_name, sync=False):
+    """Export a function or plugin method as a msgpack-rpc request handler."""
+    def dec(f):
+        f._nvim_rpc_method_name = rpc_method_name
+        f._nvim_rpc_sync = sync
+        f._nvim_bind = True
+        f._nvim_prefix_plugin_path = False
+        return f
+    return dec
+
+
+def command(name, nargs=0, complete=None, range=None, count=None, bang=False,
+            register=False, sync=False, eval=None):
+    """Tag a function or plugin method as a Nvim command handler."""
+    def dec(f):
+        f._nvim_rpc_method_name = 'command:{0}'.format(name)
+        f._nvim_rpc_sync = sync
+        f._nvim_bind = True
+        f._nvim_prefix_plugin_path = True
+
+        opts = {}
+
+        if range:
+            opts['range'] = '' if range is True else str(range)
+        elif count:
+            opts['count'] = count
+
+        if bang:
+            opts['bang'] = True
+
+        if register:
+            opts['register'] = True
+
+        if nargs:
+            opts['nargs'] = nargs
+
+        if complete:
+            opts['complete'] = complete
+
+        if eval:
+            opts['eval'] = eval
+
+        f.nvim_rpc_spec = {
+            'type': 'command',
+            'name': name,
+            'sync': sync,
+            'opts': opts
+        }
+        return f
+    return dec
+
+
+def autocmd(name, pattern=None, sync=False, eval=None):
+    """Tag a function or plugin method as a Nvim autocommand handler."""
+    def dec(f):
+        f._nvim_rpc_method_name = 'autocmd:{0}:{1}'.format(name, pattern)
+        f._nvim_rpc_sync = sync
+        f._nvim_bind = True
+        f._nvim_prefix_plugin_path = True
+
+        opts = {
+            'pattern': pattern or '*'
+        }
+
+        if eval:
+            opts['eval'] = eval
+
+        f.nvim_rpc_spec = {
+            'type': 'autocmd',
+            'name': name,
+            'sync': sync,
+            'opts': opts
+        }
+        return f
+    return dec
+
+
+def function(name, range=False, sync=False, eval=None):
+    """Tag a function or plugin method as a Nvim function handler."""
+    def dec(f):
+        f._nvim_rpc_method_name = 'function:{0}'.format(name)
+        f._nvim_rpc_sync = sync
+        f._nvim_bind = True
+        f._nvim_prefix_plugin_path = True
+
+        opts = {}
+
+        if range:
+            opts['range'] = '' if range is True else str(range)
+
+        if eval:
+            opts['eval'] = eval
+
+        f.nvim_rpc_spec = {
+            'type': 'function',
+            'name': name,
+            'sync': sync,
+            'opts': opts
+        }
+        return f
+    return dec
+
+
+def shutdown_hook(f):
+    """Tag a function or method as a shutdown hook."""
+    f._nvim_shutdown_hook = True
+    f._nvim_bind = True
+    return f
+
+
+def encoding(encoding=True):
+    """Configure automatic encoding/decoding of strings."""
+    def dec(f):
+        f._nvim_encoding = encoding
+        return f
+    return dec

neovim/plugin/host.py

@@ -0,0 +1,152 @@
+"""Implements a Nvim host for python plugins."""
+import functools
+import imp
+import inspect
+import logging
+import os
+import os.path
+
+from ..api import DecodeHook
+from ..compat import IS_PYTHON3, find_module
+
+
+__all__ = ('Host')
+
+logger = logging.getLogger(__name__)
+debug, info, warn = (logger.debug, logger.info, logger.warn,)
+
+
+class Host(object):
+
+    """Nvim host for python plugins.
+
+    Takes care of loading/unloading plugins and routing msgpack-rpc
+    requests/notifications to the appropriate handlers.
+    """
+
+    def __init__(self, nvim):
+        """Set handlers for plugin_load/plugin_unload."""
+        self.nvim = nvim
+        self._specs = {}
+        self._loaded = {}
+        self._notification_handlers = {}
+        self._request_handlers = {
+            'poll': lambda: 'ok',
+            'specs': lambda path: self._specs[path],
+            'shutdown': self.shutdown
+        }
+        self._nvim_encoding = nvim.options['encoding']
+
+    def start(self, plugins):
+        """Start listening for msgpack-rpc requests and notifications."""
+        self.nvim.session.run(self._on_request,
+                              self._on_notification,
+                              lambda: self._load(plugins))
+
+    def shutdown(self):
+        """Shutdown the host."""
+        self._unload()
+        self.nvim.session.stop()
+
+    def _on_request(self, name, args):
+        """Handle a msgpack-rpc request."""
+        handler = self._request_handlers.get(name, None)
+        if not handler:
+            msg = 'no request handler registered for "%s"' % name
+            warn(msg)
+            raise Exception(msg)
+
+        debug('calling request handler for "%s", args: "%s"', name, args)
+        rv = handler(*args)
+        debug("request handler for '%s %s' returns: %s", name, args, rv)
+        return rv
+
+    def _on_notification(self, name, args):
+        """Handle a msgpack-rpc notification."""
+        handler = self._notification_handlers.get(name, None)
+        if not handler:
+            warn('no notification handler registered for "%s"', name)
+            return
+
+        debug('calling notification handler for "%s", args: "%s"', name, args)
+        handler(*args)
+
+    def _load(self, plugins):
+        for path in plugins:
+            if path in self._loaded:
+                raise Exception('{0} is already loaded'.format(path))
+            directory, name = os.path.split(os.path.splitext(path)[0])
+            file, pathname, description = find_module(name, [directory])
+            module = imp.load_module(name, file, pathname, description)
+            handlers = []
+            self._discover_classes(module, handlers, path)
+            self._discover_functions(module, handlers, path)
+            if not handlers:
+                raise Exception('{0} exports no handlers'.format(path))
+            self._loaded[path] = {'handlers': handlers, 'module': module}
+
+    def _unload(self):
+        for path, plugin in self._loaded.items():
+            handlers = plugin['handlers']
+            for handler in handlers:
+                method_name = handler._nvim_rpc_method_name
+                if hasattr(handler, '_nvim_shutdown_hook'):
+                    handler()
+                elif handler._nvim_rpc_sync:
+                    del self._request_handlers[method_name]
+                else:
+                    del self._notification_handlers[method_name]
+        self._specs = {}
+        self._loaded = {}
+
+    def _discover_classes(self, module, handlers, plugin_path):
+        for _, cls in inspect.getmembers(module, inspect.isclass):
+            if getattr(cls, '_nvim_plugin', False):
+                # create an instance of the plugin and pass the nvim object
+                plugin = cls(self._configure_nvim_for(cls))
+                # discover handlers in the plugin instance
+                self._discover_functions(plugin, handlers, plugin_path)
+
+    def _discover_functions(self, obj, handlers, plugin_path):
+        predicate = lambda o: hasattr(o, '_nvim_rpc_method_name')
+        specs = []
+        for _, fn in inspect.getmembers(obj, predicate):
+            if fn._nvim_bind:
+                # bind a nvim instance to the handler
+                fn2 = functools.partial(fn, self._configure_nvim_for(fn))
+                # copy _nvim_* attributes from the original function
+                for attr in dir(fn):
+                    if attr.startswith('_nvim_'):
+                        setattr(fn2, attr, getattr(fn, attr))
+                fn = fn2
+            # register in the rpc handler dict
+            method = fn._nvim_rpc_method_name
+            if fn._nvim_prefix_plugin_path:
+                method = '{0}:{1}'.format(plugin_path, method)
+            if fn._nvim_rpc_sync:
+                if method in self._request_handlers:
+                    raise Exception('Request handler for "{0}" is ' +
+                                    'already registered'.format(method))
+                self._request_handlers[method] = fn
+            else:
+                if method in self._notification_handlers:
+                    raise Exception('Notification handler for "{0}" is ' +
+                                    'already registered'.format(method))
+                self._notification_handlers[method] = fn
+            if hasattr(fn, 'nvim_rpc_spec'):
+                specs.append(fn.nvim_rpc_spec)
+            handlers.append(fn)
+        if specs:
+            self._specs[plugin_path] = specs
+
+    def _configure_nvim_for(self, obj):
+        # Configure a nvim instance for obj(checks encoding configuration)
+        nvim = self.nvim
+        encoding = getattr(obj, '_nvim_encoding', None)
+        if IS_PYTHON3 and encoding is None:
+            encoding = True
+        if encoding is True:
+            encoding = self._nvim_encoding
+        if encoding:
+            nvim = nvim.with_hook(DecodeHook(encoding))
+        return nvim