diff --git a/README.md b/README.md index 7e3605ab..0f81f14b 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,24 @@ For details about testing and troubleshooting, see the [development](http://pynvim.readthedocs.io/en/latest/development.html) documentation. -#### Usage through the python REPL +#### Autoconnect in Python/IPython REPL + +You can explore and use pynvim through Python/IPython REPL. For easy connection use the +startup script in scripts/nvim_startup.py like so: +```bash +$ ipython -i scripts/nvim_startup.py +# or if you prefer the Python REPL instead of IPython +$ python -i scripts/nvim_startup.py +``` + +This will leave you with an Python/IPython Session that has a variable named "nvim" which +represents a connection to your current NVim instance. +If you have more than one instance running, the script will ask at startup to which +instance it shall connect to. Afterwards see [the next section](README.md#manual-usage-through-the-python-repl) +for examples on how to use the API. + + +#### Manual usage through the python REPL A number of different transports are supported, but the simplest way to get started is with the python REPL. First, start Nvim with a known address (or use diff --git a/scripts/nvim_startup.py b/scripts/nvim_startup.py new file mode 100755 index 00000000..1e85bd18 --- /dev/null +++ b/scripts/nvim_startup.py @@ -0,0 +1,62 @@ +""" Startup script for IPython an Python REPL that will connect to a running +NeoVim instance automatically or ask the user which NeoVim instance to connect +to. After connection there is a variable called "nvim" that gives acccess to +the endpoint. +""" +import atexit +from glob import glob +import pynvim + + +class NvimAutoAttachException(Exception): + '''Exception class that will be raised by this script''' + + +def __let_user_choose_instance(nvim_instances): + for idx, inst in enumerate(nvim_instances): + with pynvim.attach('socket', path=inst) as nvim_endpoint: + nvim_endpoint.command( + 'echon "I am Instance Nr {}: " $NVIM_LISTEN_ADDRESS'.format( + idx + ) + ) + + for idx, inst in enumerate(nvim_instances): + print('Instance Nr {}: {}'.format(idx, inst)) + + while True: + try: + print( + 'Which Nvim instance should I connect to? ' + '(Look at the bottom of the vim instance you want to connect ' + 'to)' + ) + inst_nr = int(input('Connect to Instance Nr: ')) + chosen_inst = nvim_instances[inst_nr] + break + except (ValueError, IndexError): + continue + + return chosen_inst + + +def autoattach_to_nvim(glob_expr='/tmp/nvim*/0'): + '''Returns a nvim endpoint if there is only one instance. + If there are more instances, asks the user which one to pick. + Raises NvimAutoAttachException if there are no NVim instances. + ''' + nvim_instances = glob(glob_expr) + if not nvim_instances: + raise NvimAutoAttachException( + 'Could not find any running NVim instances.' + ) + if len(nvim_instances) > 1: + chosen_inst = __let_user_choose_instance(nvim_instances) + else: + chosen_inst = nvim_instances[0] + return pynvim.attach('socket', path=chosen_inst) + + +nvim = autoattach_to_nvim() +nvim.command('echo "Connected to Python REPL."') +atexit.register(lambda: nvim.command('echo "Python REPL disconnected."'))