Merge pull request #58 from elmart/session-creation-facade

Improve python API.

Author: tarruda

.travis.yml

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

README.md

@@ -27,11 +27,9 @@ similar to the one exposed by the [python-vim
 bridge](http://vimdoc.sourceforge.net/htmldoc/if_pyth.html#python-vim))
 
 ```python
->>> from neovim import socket_session, Nvim
-# Create a msgpack-rpc session to the unix domain socket created by Nvim:
->>> session = socket_session('/tmp/nvim')
-# Create a Nvim instance from the session(don't call Nvim constructor!):
->>> nvim = Nvim.from_session(session)
+>>> from neovim import attach
+# Create a python API session attached to unix domain socket created above:
+>>> nvim = attach('socket', path='/tmp/nvim')
 # Now do some work. 
 >>> buffer = nvim.buffers[0] # Get the first buffer
 >>> buffer[0] = 'replace first line'

neovim/__init__.py

@@ -7,16 +7,16 @@
 import sys
 
 from .api import DecodeHook, Nvim, SessionHook
-from .msgpack_rpc import (socket_session, spawn_session, stdio_session,
+from .msgpack_rpc import (child_session, socket_session, stdio_session,
                           tcp_session)
 from .plugin import (Host, autocmd, command, encoding, function, plugin,
                      rpc_export, shutdown_hook)
 
 
-__all__ = ('tcp_session', 'socket_session', 'stdio_session', 'spawn_session',
+__all__ = ('tcp_session', 'socket_session', 'stdio_session', 'child_session',
            'start_host', 'autocmd', 'command', 'encoding', 'function',
            'plugin', 'rpc_export', 'Host', 'DecodeHook', 'Nvim',
-           'SessionHook', 'shutdown_hook')
+           'SessionHook', 'shutdown_hook', 'attach')
 
 
 def start_host(session=None):
@@ -65,6 +65,35 @@ def start_host(session=None):
     host.start(plugins)
 
 
+def attach(session_type, address=None, port=None, path=None, argv=None):
+    """Provide a nicer interface to create python api sessions.
+
+    Previous machinery to create python api sessions is still there. This only
+    creates a facade function to make things easier for the most usual cases.
+    Thus, instead of:
+        from neovim import socket_session, Nvim
+        session = tcp_session(address=<address>, port=<port>)
+        nvim = Nvim.from_session(session)
+    You can now do:
+        from neovim import attach
+        nvim = attach('tcp', address=<address>, port=<port>)
+    And also:
+        nvim = attach('socket', path=<path>)
+        nvim = attach('child', argv=<argv>)
+        nvim = attach('stdio')
+    """
+    session = (tcp_session(address, port) if session_type == 'tcp' else
+               socket_session(path) if session_type == 'socket' else
+               stdio_session() if session_type == 'stdio' else
+               child_session(argv) if session_type == 'child'else
+               None)
+
+    if not session:
+        raise Exception('Unknown session type "%s"' % session_type)
+
+    return Nvim.from_session(session)
+
+
 # Required for python 2.6
 class NullHandler(logging.Handler):
     def emit(self, record):

neovim/msgpack_rpc/__init__.py

@@ -10,7 +10,7 @@
 from .session import Session
 
 
-__all__ = ('tcp_session', 'socket_session', 'stdio_session', 'spawn_session')
+__all__ = ('tcp_session', 'socket_session', 'stdio_session', 'child_session')
 
 
 def session(transport_type='stdio', *args, **kwargs):
@@ -36,6 +36,6 @@ def stdio_session():
     return session('stdio')
 
 
-def spawn_session(argv):
+def child_session(argv):
     """Create a msgpack-rpc session from a new Nvim instance."""
-    return session('spawn', argv)
+    return session('child', argv)

neovim/msgpack_rpc/event_loop/asyncio.py

@@ -89,7 +89,7 @@ def _connect_stdio(self):
         coroutine = self._loop.connect_write_pipe(self._fact, sys.stdout)
         self._loop.run_until_complete(coroutine)
 
-    def _connect_spawn(self, argv):
+    def _connect_child(self, argv):
         coroutine = self._loop.subprocess_exec(self._fact, *argv)
         self._loop.run_until_complete(coroutine)
 

neovim/msgpack_rpc/event_loop/base.py

@@ -30,7 +30,7 @@ class BaseEventLoop(object):
     - `_connect_socket(path)`: Same as tcp, but use a UNIX domain socket or
       or named pipe.
     - `_connect_stdio()`: Use stdin/stdout as the connection to Nvim
-    - `_connect_spawn(argv)`: Use the argument vector `argv` to spawn an
+    - `_connect_child(argv)`: Use the argument vector `argv` to spawn an
       embedded Nvim that has it's stdin/stdout connected to the event loop.
     - `_start_reading()`: Called after any of _connect_* methods. Can be used
       to perform any post-connection setup or validation.
@@ -68,7 +68,7 @@ def __init__(self, transport_type, *args):
         Traceback (most recent call last):
             ...
         AttributeError: 'BaseEventLoop' object has no attribute '_init'
-        >>> BaseEventLoop('spawn', ['nvim', '--embed', '-u', 'NONE'])
+        >>> BaseEventLoop('child', ['nvim', '--embed', '-u', 'NONE'])
         Traceback (most recent call last):
             ...
         AttributeError: 'BaseEventLoop' object has no attribute '_init'
@@ -101,10 +101,10 @@ def connect_stdio(self):
         info('Preparing stdin/stdout for streaming data')
         self._connect_stdio()
 
-    def connect_spawn(self, argv):
-        """Connect a new Nvim instance. Delegated to `_connect_spawn`."""
+    def connect_child(self, argv):
+        """Connect a new Nvim instance. Delegated to `_connect_child`."""
         info('Spawning a new nvim instance')
-        self._connect_spawn(argv)
+        self._connect_child(argv)
 
     def send(self, data):
         """Queue `data` for sending to Nvim."""

neovim/msgpack_rpc/event_loop/uv.py

@@ -63,7 +63,7 @@ def _connect_stdio(self):
         self._write_stream = pyuv.Pipe(self._loop)
         self._write_stream.open(sys.stdout.fileno())
 
-    def _connect_spawn(self, argv):
+    def _connect_child(self, argv):
         self._write_stream = pyuv.Pipe(self._loop)
         self._read_stream = pyuv.Pipe(self._loop)
         self._error_stream = pyuv.Pipe(self._loop)
@@ -108,7 +108,10 @@ def _on_async(self, handle):
 
     def _setup_signals(self, signals):
         self._signal_handles = []
-        handler = lambda h, signum: self._on_signal(signum)
+
+        def handler(h, signum):
+            self._on_signal(signum)
+
         for signum in signals:
             handle = pyuv.Signal(self._loop)
             handle.start(handler, signum)

test/common.py

@@ -7,15 +7,10 @@
 from nose.tools import eq_ as eq
 
 
-session = None
-vim = None
-if 'NVIM_SPAWN_ARGV' in os.environ:
-    argv = json.loads(os.environ['NVIM_SPAWN_ARGV'])
-    session = neovim.spawn_session(argv)
+if 'NVIM_CHILD_ARGV' in os.environ:
+    vim = neovim.attach('child', argv=json.loads(os.environ['NVIM_CHILD_ARGV']))
 else:
-    session = neovim.socket_session(os.environ['NVIM_LISTEN_ADDRESS'])
-
-vim = neovim.Nvim.from_session(session)
+    vim = neovim.attach('socket', path=os.environ['NVIM_LISTEN_ADDRESS'])
 
 if sys.version_info >= (3, 0):
     # For Python3 we decode binary strings as Unicode for compatibility
@@ -63,6 +58,7 @@
 
 vim.input(cleanup_func)
 
+
 def cleanup():
     # cleanup nvim
     vim.command('call BeforeEachTest()')