README.md
1Pynvim: Python client to [Neovim](https://github.com/neovim/neovim)
2===================================================================
3
4[](https://travis-ci.org/neovim/pynvim)
5[](http://pynvim.readthedocs.io/en/latest/?badge=latest)
6[](https://codecov.io/gh/neovim/pynvim)
7
8Pynvim implements support for python plugins in Nvim. It also works as a library for
9connecting to and scripting Nvim processes through its msgpack-rpc API.
10
11Install
12-------
13
14Supports python 2.7, and 3.4 or later.
15
16```sh
17pip2 install pynvim
18pip3 install pynvim
19```
20
21If you only use one of python2 or python3, it is enough to install that
22version. You can install the package without being root by adding the `--user`
23flag.
24
25Anytime you upgrade Neovim, make sure to upgrade pynvim as well:
26```sh
27pip2 install --upgrade pynvim
28pip3 install --upgrade pynvim
29```
30
31Alternatively, the master version could be installed by executing the following
32in the root of this repository:
33```sh
34pip2 install .
35pip3 install .
36```
37
38Python Plugin API
39-----------------
40
41Pynvim supports python _remote plugins_ (via the language-agnostic Nvim rplugin
42interface), as well as _Vim plugins_ (via the `:python[3]` interface). Thus when
43pynvim is installed Neovim will report support for the `+python[3]` Vim feature.
44
45The rplugin interface allows plugins to handle vimL function calls as well as
46defining commands and autocommands, and such plugins can operate asynchronously
47without blocking nvim. For details on the new rplugin interface,
48see the [Remote Plugin](http://pynvim.readthedocs.io/en/latest/usage/remote-plugins.html) documentation.
49
50Pynvim defines some extensions over the vim python API:
51
52* Builtin and plugin vimL functions are available as `nvim.funcs`
53* API functions are available as `vim.api` and for objects such as `buffer.api`
54* Lua functions can be defined using `vim.exec_lua` and called with `vim.lua`
55* Support for thread-safety and async requests.
56
57See the [Python Plugin API](http://pynvim.readthedocs.io/en/latest/usage/python-plugin-api.html) documentation for usage of this new functionality.
58
59Development
60-----------
61
62Use (and activate) a local virtualenv.
63
64 python3 -m venv env36
65 source env36/bin/activate
66
67If you change the code, you must reinstall for the changes to take effect:
68
69 pip install .
70
71Use `pytest` to run the tests. Invoking with `python -m` prepends the current
72directory to `sys.path` (otherwise `pytest` might find other versions!):
73
74 python -m pytest
75
76For details about testing and troubleshooting, see the
77[development](http://pynvim.readthedocs.io/en/latest/development.html)
78documentation.
79
80### Usage from the Python REPL
81
82A number of different transports are supported, but the simplest way to get
83started is with the python REPL. First, start Nvim with a known address (or use
84the `$NVIM_LISTEN_ADDRESS` of a running instance):
85
86```sh
87$ NVIM_LISTEN_ADDRESS=/tmp/nvim nvim
88```
89
90In another terminal, connect a python REPL to Nvim (note that the API is similar
91to the one exposed by the [python-vim
92bridge](http://vimdoc.sourceforge.net/htmldoc/if_pyth.html#python-vim)):
93
94```python
95>>> from pynvim import attach
96# Create a python API session attached to unix domain socket created above:
97>>> nvim = attach('socket', path='/tmp/nvim')
98# Now do some work.
99>>> buffer = nvim.current.buffer # Get the current buffer
100>>> buffer[0] = 'replace first line'
101>>> buffer[:] = ['replace whole buffer']
102>>> nvim.command('vsplit')
103>>> nvim.windows[1].width = 10
104>>> nvim.vars['global_var'] = [1, 2, 3]
105>>> nvim.eval('g:global_var')
106[1, 2, 3]
107```
108
109You can embed Neovim into your python application instead of connecting to
110a running Neovim instance.
111
112```python
113>>> from pynvim import attach
114>>> nvim = attach('child', argv=["/bin/env", "nvim", "--embed", "--headless"])
115```
116
117- The ` --headless` argument tells `nvim` not to wait for a UI to connect.
118- Alternatively, use `--embed` _without_ `--headless` if your client is a UI
119 and you want `nvim` to wait for your client to `nvim_ui_attach` before
120 continuing startup.
121
122See the tests for more examples.
123
124Release
125-------
126
1271. Create a release commit with title `Pynvim x.y.z`
128 - list significant changes in the commit message
129 - bump the version in `pynvim/util.py` and `setup.py` (3 places in total)
1302. Make a release on GitHub with the same commit/version tag and copy the message.
1313. Run `scripts/disable_log_statements.sh`
1324. Run `python setup.py sdist`
133 - diff the release tarball `dist/pynvim-x.y.z.tar.gz` against the previous one.
1345. Run `twine upload -r pypi dist/pynvim-x.y.z.tar.gz`
135 - Assumes you have a pypi account with permissions.
1366. Run `scripts/enable_log_statements.sh` or `git reset --hard` to restore the working dir.
137
){kind=link}
){kind=link}