



  

Neovim Python Client documentation

 [Neovim Python Client](index.html#document-index) 

 stable

 

Getting started

* [Installation](index.html#document-installation)

	+ [Using pip](index.html#using-pip)

	+ [Install from source](index.html#install-from-source)

Usage

* [Python Plugin API](index.html#document-usage/python-plugin-api)

	+ [Nvim API methods: `vim.api`](index.html#nvim-api-methods-vim-api)

	+ [Vimscript functions: `vim.funcs`](index.html#vimscript-functions-vim-funcs)

	+ [Lua integration](index.html#lua-integration)

	+ [Async calls](index.html#async-calls)

* [Remote (new-style) plugins](index.html#document-usage/remote-plugins)

API documentation

* [Plugin Decorators](index.html#document-plugin-decorators)

	+ [Plugin](index.html#plugin)

	+ [Command](index.html#command)

	+ [Autocmd](index.html#autocmd)

	+ [Function](index.html#function)

* [Nvim Class](index.html#document-api/nvim)

* [Buffer Class](index.html#document-api/buffer)

* [Window Class](index.html#document-api/window)

* [Tabpage Class](index.html#document-api/tabpage)

Development

* [Development](index.html#document-development)

	+ [Troubleshooting](index.html#troubleshooting)

	+ [Usage through the Python REPL](index.html#usage-through-the-python-repl)

[Neovim Python Client](index.html#document-index)

* [Docs](index.html#document-index) »

* Neovim Python Client documentation

* [Edit on GitHub](https://github.com/neovim/python-client/blob/bc85d13b9675c45d93a847cfcb8c43e998000cde/docs/index.rst)

---

Neovim Python Client[¶](#neovim-python-client "Permalink to this headline")

===========================================================================

Implements support for Python plugins in [Neovim](http://neovim.io/).

Also works as a library for connecting to and scripting Neovim processes through its msgpack-rpc API.

Installation[¶](#installation "Permalink to this headline")

-----------------------------------------------------------

The Neovim Python client supports Python 2.7, and 3.4 or later.

### Using pip[¶](#using-pip "Permalink to this headline")

You can install the package without being root by adding the `--user` flag:

```

pip2 install --user pynvim

pip3 install --user pynvim

```

Note

If you only use one of python2 or python3,

it is enough to install that version.

If you follow Neovim HEAD, make sure to upgrade `pynvim` when you upgrade

Neovim:

```

pip2 install --upgrade pynvim

pip3 install --upgrade pynvim

```

### Install from source[¶](#install-from-source "Permalink to this headline")

Clone the repository somewhere on your disk and enter to the repository:

```

git clone https://github.com/neovim/pynvim.git

cd pynvim

```

Now you can install it on your system:

```

pip2 install .

pip3 install .

```

Python Plugin API[¶](#python-plugin-api "Permalink to this headline")

---------------------------------------------------------------------

Neovim has a new mechanism for defining plugins,

as well as a number of extensions to the python API.

The API extensions are accessible no matter if the traditional `:python` interface or the new mechanism is used,

as discussed on [Remote (new-style) plugins](index.html#document-usage/remote-plugins).

### Nvim API methods: `vim.api`[¶](#nvim-api-methods-vim-api "Permalink to this headline")

Exposes Neovim API methods.

For instance to call `nvim\_strwidth`:

```

result = vim.api.strwidth("some text")

```

Note the initial `nvim\_` is not included.

Also, object methods can be called directly on their object:

```

buf = vim.current.buffer

length = buf.api.line\_count()

```

calls `nvim\_buf\_line\_count`.

Alternatively msgpack requests can be invoked directly:

```

result = vim.request("nvim\_strwith", "some text")

length = vim.request("nvim\_buf\_line\_count", buf)

```

Both `vim.api` and `vim.request` can take an `async\_=True` keyword argument

to instead send a msgpack notification. Nvim will execute the API method the

same way, but python will not wait for it to finish, so the return value is

unavailable.

### Vimscript functions: `vim.funcs`[¶](#vimscript-functions-vim-funcs "Permalink to this headline")

Exposes vimscript functions (both builtin and global user defined functions) as a python namespace.

For instance to set the value of a register:

```

vim.funcs.setreg('0', ["some", "text"], 'l')

```

These functions can also take the `async\_=True` keyword argument, just like API

methods.

### Lua integration[¶](#lua-integration "Permalink to this headline")

Python plugins can define and invoke lua code in Nvim’s in-process lua

interpreter. This is especially useful in asynchronous contexts, where an async

event handler can schedule a complex operation with many api calls to be

executed by nvim without interleaved processing of user input or other event

sources (unless requested).

The recommended usage is the following pattern. First use `vim.exec\_lua(code)`

to define a module with lua functions:

```

vim.exec\_lua("""

 local a = vim.api

 local function add(a,b)

 return a+b

 end

 local function buffer\_ticks()

 local ticks = {}

 for \_, buf in ipairs(a.nvim\_list\_bufs()) do

 ticks[#ticks+1] = a.nvim\_buf\_get\_changedtick(buf)

 end

 return ticks

 end

 \_testplugin = {add=add, buffer\_ticks=buffer\_ticks}

""")

```

Alternatively, place the code in `/lua/testplugin.lua` under your plugin repo

root, and use `vim.exec\_lua("\_testplugin = require('testplugin')")`.

In both cases, replace `testplugin` with a unique string based on your plugin

name.

Then, the module can be acessed as `vim.lua.\_testplugin`.

```

mod = vim.lua.\_testplugin

mod.add(2,3) # => 5

mod.buffer\_ticks() # => list of ticks

```

These functions can also take the `async\_=True` keyword argument, just like API

methods.

It is also possible to pass arguments directly to a code block. Using

`vim.exec\_lua(code, args...)`, the arguments will be available in lua as `...`.

### Async calls[¶](#async-calls "Permalink to this headline")

The API is not thread-safe in general.

However, `vim.async\_call` allows a spawned thread to schedule code to be executed on the main thread.

This method could also be called from `:python` or a synchronous request handler,

to defer some execution that shouldn’t block Neovim:

```

:python vim.async\_call(myfunc, args...)

```

Note that this code will still block the plugin host if it does long-running computations.

Intensive computations should be done in a separate thread (or process),

and `vim.async\_call` can be used to send results back to Neovim.

Some methods accept an `async\_` keyword argument: `vim.eval`,

`vim.command`, `vim.request` as well as the `vim.funcs`, `vim.api` and

``vim.lua`` wrappers. When `async\_=True` is passed the client will not wait

for Neovim to complete the request (which also means that the return value is

unavailable).

Remote (new-style) plugins[¶](#remote-new-style-plugins "Permalink to this headline")

-------------------------------------------------------------------------------------

Neovim allows Python 3 plugins to be defined by placing python files or packages in `rplugin/python3/` (in a `runtimepath` folder).

Python 2 rplugins are also supported and placed in `rplugin/python/`,

but are considered deprecated.

Further added library features will only be available on Python 3.

Rplugins follow the structure of this example:

```

import pynvim

@pynvim.plugin

class TestPlugin(object):

    def \_\_init\_\_(self, nvim):

        self.nvim = nvim

    @pynvim.function('TestFunction', sync=True)

    def testfunction(self, args):

        return 3

    @pynvim.command('TestCommand', nargs='\*', range='')

    def testcommand(self, args, range):

        self.nvim.current.line = ('Command with args: {}, range: {}'

                                  .format(args, range))

    @pynvim.autocmd('BufEnter', pattern='\*.py', eval='expand("<afile>")', sync=True)

    def on\_bufenter(self, filename):

        self.nvim.out\_write('testplugin is in ' + filename + '\n')

```

If `sync=True` is supplied Neovim will wait for the handler to finish

(this is required for function return values),

but by default handlers are executed asynchronously.

Normally async handlers (`sync=False`, the default)

are blocked while a synchronous handler is running.

This ensures that async handlers can call requests without Neovim confusing these requests with requests from a synchronous handler.

To execute an asynchronous handler even when other handlers are running,

add `allow\_nested=True` to the decorator.

This handler must then not make synchronous Neovim requests,

but it can make asynchronous requests, i.e. passing `async\_=True`.

Note

Plugin objects are constructed the first time any request of the class is

invoked. Any error in `\_\_init\_\_` will be reported as an error from this

first request. A well-behaved rplugin will not start executing until its

functionality is requested by the user. Initialize the plugin when user

invokes a command, or use an appropriate autocommand, e.g. FileType if it

makes sense to automatically start the plugin for a given filetype. Plugins

must not invoke API methods (or really do anything with non-trivial

side-effects) in global module scope, as the module might be loaded as part

of executing UpdateRemotePlugins.

You need to run `:UpdateRemotePlugins` in Neovim for changes in the specifications to have effect.

For details see `:help remote-plugin` in Neovim.

For local plugin development, it’s a good idea to use an isolated vimrc:

```

cat vimrc

let &runtimepath.=','.escape(expand('<sfile>:p:h'), '\,')

```

That appends the current directory to the Nvim runtime path so Nvim can

find your plugin. You can now invoke Neovim:

```

nvim -u ./vimrc

```

Then run `:UpdateRemotePlugins` and your plugin should be activated.

In case you run into some issues, you can list your loaded plugins from inside

Neovim by running `:scriptnames` like so.:

```

:scriptnames

1: ~/path/to/your/plugin-git-repo/vimrc

2: /usr/share/nvim/runtime/filetype.vim

...

25: /usr/share/nvim/runtime/plugin/zipPlugin.vim

26: ~/path/to/your/plugin-git-repo/plugin/lucid.vim

```

You can also inspect the `&runtimepath` like this:

```

:set runtimepath

runtimepath=~/.config/nvim,/etc/xdg/nvim,~/.local/share/nvim/site,...,

,~/g/path/to/your/plugin-git-repo

" Or alternatively

:echo &rtp

```

Plugin Decorators[¶](#module-pynvim.plugin "Permalink to this headline")

------------------------------------------------------------------------

Plugin decorators.

### Plugin[¶](#plugin "Permalink to this headline")

`pynvim.plugin.``plugin`(*cls*)[[source]](_modules/pynvim/plugin/decorators.html#plugin)[¶](#pynvim.plugin.plugin "Permalink to this definition")

Tag a class as a plugin.

This decorator is required to make the class methods discoverable by the

plugin\_load method of the host.

### Command[¶](#command "Permalink to this headline")

`pynvim.plugin.``command`(*name*, *nargs=0*, *complete=None*, *range=None*, *count=None*, *bang=False*, *register=False*, *sync=False*, *allow\_nested=False*, *eval=None*)[[source]](_modules/pynvim/plugin/decorators.html#command)[¶](#pynvim.plugin.command "Permalink to this definition")

Tag a function or plugin method as a Nvim command handler.

### Autocmd[¶](#autocmd "Permalink to this headline")

`pynvim.plugin.``autocmd`(*name*, *pattern='\*'*, *sync=False*, *allow\_nested=False*, *eval=None*)[[source]](_modules/pynvim/plugin/decorators.html#autocmd)[¶](#pynvim.plugin.autocmd "Permalink to this definition")

Tag a function or plugin method as a Nvim autocommand handler.

### Function[¶](#function "Permalink to this headline")

`pynvim.plugin.``function`(*name*, *range=False*, *sync=False*, *allow\_nested=False*, *eval=None*)[[source]](_modules/pynvim/plugin/decorators.html#function)[¶](#pynvim.plugin.function "Permalink to this definition")

Tag a function or plugin method as a Nvim function handler.

Nvim Class[¶](#nvim-class "Permalink to this headline")

-------------------------------------------------------

An instance of this class is used by remote plugins.

*class* `pynvim.api.``Nvim`(*session*, *channel\_id*, *metadata*, *types*, *decode=False*, *err\_cb=None*)[[source]](_modules/pynvim/api/nvim.html#Nvim)[¶](#pynvim.api.Nvim "Permalink to this definition")

Class that represents a remote Nvim instance.

This class is main entry point to Nvim remote API, it is a wrapper

around Session instances.

The constructor of this class must not be called directly. Instead, the

from\_session class method should be used to create the first instance

from a raw Session instance.

Subsequent instances for the same session can be created by calling the

with\_decode instance method to change the decoding behavior or

SubClass.from\_nvim(nvim) where SubClass is a subclass of Nvim, which

is useful for having multiple Nvim objects that behave differently

without one affecting the other.

When this library is used on python3.4+, asyncio event loop is guaranteed

to be used. It is available as the “loop” attribute of this class. Note

that asyncio callbacks cannot make blocking requests, which includes

accessing state-dependent attributes. They should instead schedule another

callback using nvim.async\_call, which will not have this restriction.

`async_call`(*fn*, *\*args*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.async_call)[¶](#pynvim.api.Nvim.async_call "Permalink to this definition")

Schedule fn to be called by the event loop soon.

This function is thread-safe, and is the only way code not

on the main thread could interact with nvim api objects.

This function can also be called in a synchronous

event handler, just before it returns, to defer execution

that shouldn’t block neovim.

`call`(*name*, *\*args*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.call)[¶](#pynvim.api.Nvim.call "Permalink to this definition")

Call a vimscript function.

`chdir`(*dir\_path*)[[source]](_modules/pynvim/api/nvim.html#Nvim.chdir)[¶](#pynvim.api.Nvim.chdir "Permalink to this definition")

Run os.chdir, then all appropriate vim stuff.

`close`()[[source]](_modules/pynvim/api/nvim.html#Nvim.close)[¶](#pynvim.api.Nvim.close "Permalink to this definition")

Close the nvim session and release its resources.

`command`(*string*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.command)[¶](#pynvim.api.Nvim.command "Permalink to this definition")

Execute a single ex command.

`command_output`(*string*)[[source]](_modules/pynvim/api/nvim.html#Nvim.command_output)[¶](#pynvim.api.Nvim.command_output "Permalink to this definition")

Execute a single ex command and return the output.

`err_write`(*msg*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.err_write)[¶](#pynvim.api.Nvim.err_write "Permalink to this definition")

Print msg as an error message.

The message is buffered (won’t display) until linefeed (“n”).

`eval`(*string*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.eval)[¶](#pynvim.api.Nvim.eval "Permalink to this definition")

Evaluate a vimscript expression.

`exec_lua`(*code*, *\*args*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.exec_lua)[¶](#pynvim.api.Nvim.exec_lua "Permalink to this definition")

Execute lua code.

Additional parameters are available as … inside the lua chunk.

Only statements are executed. To evaluate an expression, prefix it

with return: return my\_function(…)

There is a shorthand syntax to call lua functions with arguments:

> 

> nvim.lua.func(1,2)

> nvim.lua.mymod.myfunction(data, async\_=True)

is equivalent to

> 

> nvim.exec\_lua(“return func(…)”, 1, 2)

> nvim.exec\_lua(“mymod.myfunction(…)”, data, async\_=True)

Note that with async\_=True there is no return value.

`feedkeys`(*keys*, *options=''*, *escape\_csi=True*)[[source]](_modules/pynvim/api/nvim.html#Nvim.feedkeys)[¶](#pynvim.api.Nvim.feedkeys "Permalink to this definition")

Push keys to Nvim user input buffer.

Options can be a string with the following character flags:

- ‘m’: Remap keys. This is default.

- ‘n’: Do not remap keys.

- ‘t’: Handle keys as if typed; otherwise they are handled as if coming

> 

> from a mapping. This matters for undo, opening folds, etc.

`foreach_rtp`(*cb*)[[source]](_modules/pynvim/api/nvim.html#Nvim.foreach_rtp)[¶](#pynvim.api.Nvim.foreach_rtp "Permalink to this definition")

Invoke cb for each path in ‘runtimepath’.

Call the given callable for each path in ‘runtimepath’ until either

callable returns something but None, the exception is raised or there

are no longer paths. If stopped in case callable returned non-None,

vim.foreach\_rtp function returns the value returned by callable.

*classmethod* `from_nvim`(*nvim*)[[source]](_modules/pynvim/api/nvim.html#Nvim.from_nvim)[¶](#pynvim.api.Nvim.from_nvim "Permalink to this definition")

Create a new Nvim instance from an existing instance.

*classmethod* `from_session`(*session*)[[source]](_modules/pynvim/api/nvim.html#Nvim.from_session)[¶](#pynvim.api.Nvim.from_session "Permalink to this definition")

Create a new Nvim instance for a Session instance.

This method must be called to create the first Nvim instance, since it

queries Nvim metadata for type information and sets a SessionHook for

creating specialized objects from Nvim remote handles.

`input`(*bytes*)[[source]](_modules/pynvim/api/nvim.html#Nvim.input)[¶](#pynvim.api.Nvim.input "Permalink to this definition")

Push bytes to Nvim low level input buffer.

Unlike feedkeys(), this uses the lowest level input buffer and the

call is not deferred. It returns the number of bytes actually

written(which can be less than what was requested if the buffer is

full).

`list_runtime_paths`()[[source]](_modules/pynvim/api/nvim.html#Nvim.list_runtime_paths)[¶](#pynvim.api.Nvim.list_runtime_paths "Permalink to this definition")

Return a list of paths contained in the ‘runtimepath’ option.

`new_highlight_source`()[[source]](_modules/pynvim/api/nvim.html#Nvim.new_highlight_source)[¶](#pynvim.api.Nvim.new_highlight_source "Permalink to this definition")

Return new src\_id for use with Buffer.add\_highlight.

`next_message`()[[source]](_modules/pynvim/api/nvim.html#Nvim.next_message)[¶](#pynvim.api.Nvim.next_message "Permalink to this definition")

Block until a message(request or notification) is available.

If any messages were previously enqueued, return the first in queue.

If not, run the event loop until one is received.

`out_write`(*msg*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.out_write)[¶](#pynvim.api.Nvim.out_write "Permalink to this definition")

Print msg as a normal message.

The message is buffered (won’t display) until linefeed (“n”).

`quit`(*quit\_command='qa!'*)[[source]](_modules/pynvim/api/nvim.html#Nvim.quit)[¶](#pynvim.api.Nvim.quit "Permalink to this definition")

Send a quit command to Nvim.

By default, the quit command is ‘qa!’ which will make Nvim quit without

saving anything.

`replace_termcodes`(*string*, *from\_part=False*, *do\_lt=True*, *special=True*)[[source]](_modules/pynvim/api/nvim.html#Nvim.replace_termcodes)[¶](#pynvim.api.Nvim.replace_termcodes "Permalink to this definition")

Replace any terminal code strings by byte sequences.

The returned sequences are Nvim’s internal representation of keys,

for example:

<esc> -> ‘x1b’

<cr> -> ‘r’

<c-l> -> ‘x0c’

<up> -> ‘x80ku’

The returned sequences can be used as input to feedkeys.

`request`(*name*, *\*args*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.request)[¶](#pynvim.api.Nvim.request "Permalink to this definition")

Send an API request or notification to nvim.

It is rarely needed to call this function directly, as most API

functions have python wrapper functions. The api object can

be also be used to call API functions as methods:

> 

> vim.api.err\_write(‘ERRORn’, async\_=True)

> vim.current.buffer.api.get\_mark(‘.’)

is equivalent to

> 

> vim.request(‘nvim\_err\_write’, ‘ERRORn’, async\_=True)

> vim.request(‘nvim\_buf\_get\_mark’, vim.current.buffer, ‘.’)

Normally a blocking request will be sent. If the async\_ flag is

present and True, a asynchronous notification is sent instead. This

will never block, and the return value or error is ignored.

`run_loop`(*request\_cb*, *notification\_cb*, *setup\_cb=None*, *err\_cb=None*)[[source]](_modules/pynvim/api/nvim.html#Nvim.run_loop)[¶](#pynvim.api.Nvim.run_loop "Permalink to this definition")

Run the event loop to receive requests and notifications from Nvim.

This should not be called from a plugin running in the host, which

already runs the loop and dispatches events to plugins.

`stop_loop`()[[source]](_modules/pynvim/api/nvim.html#Nvim.stop_loop)[¶](#pynvim.api.Nvim.stop_loop "Permalink to this definition")

Stop the event loop being started with run\_loop.

`strwidth`(*string*)[[source]](_modules/pynvim/api/nvim.html#Nvim.strwidth)[¶](#pynvim.api.Nvim.strwidth "Permalink to this definition")

Return the number of display cells string occupies.

Tab is counted as one cell.

`subscribe`(*event*)[[source]](_modules/pynvim/api/nvim.html#Nvim.subscribe)[¶](#pynvim.api.Nvim.subscribe "Permalink to this definition")

Subscribe to a Nvim event.

`ui_attach`(*width*, *height*, *rgb=None*, *\*\*kwargs*)[[source]](_modules/pynvim/api/nvim.html#Nvim.ui_attach)[¶](#pynvim.api.Nvim.ui_attach "Permalink to this definition")

Register as a remote UI.

After this method is called, the client will receive redraw

notifications.

`ui_detach`()[[source]](_modules/pynvim/api/nvim.html#Nvim.ui_detach)[¶](#pynvim.api.Nvim.ui_detach "Permalink to this definition")

Unregister as a remote UI.

`ui_try_resize`(*width*, *height*)[[source]](_modules/pynvim/api/nvim.html#Nvim.ui_try_resize)[¶](#pynvim.api.Nvim.ui_try_resize "Permalink to this definition")

Notify nvim that the client window has resized.

If possible, nvim will send a redraw request to resize.

`unsubscribe`(*event*)[[source]](_modules/pynvim/api/nvim.html#Nvim.unsubscribe)[¶](#pynvim.api.Nvim.unsubscribe "Permalink to this definition")

Unsubscribe to a Nvim event.

`with_decode`(*decode=True*)[[source]](_modules/pynvim/api/nvim.html#Nvim.with_decode)[¶](#pynvim.api.Nvim.with_decode "Permalink to this definition")

Initialize a new Nvim instance.

Buffer Class[¶](#buffer-class "Permalink to this headline")

-----------------------------------------------------------

*class* `pynvim.api.``Buffer`(*session*, *code\_data*)[[source]](_modules/pynvim/api/buffer.html#Buffer)[¶](#pynvim.api.Buffer "Permalink to this definition")

A remote Nvim buffer.

`add_highlight`(*hl\_group*, *line*, *col\_start=0*, *col\_end=-1*, *src\_id=-1*, *async\_=None*, *\*\*kwargs*)[[source]](_modules/pynvim/api/buffer.html#Buffer.add_highlight)[¶](#pynvim.api.Buffer.add_highlight "Permalink to this definition")

Add a highlight to the buffer.

`append`(*lines*, *index=-1*)[[source]](_modules/pynvim/api/buffer.html#Buffer.append)[¶](#pynvim.api.Buffer.append "Permalink to this definition")

Append a string or list of lines to the buffer.

`clear_highlight`(*src\_id*, *line\_start=0*, *line\_end=-1*, *async\_=None*, *\*\*kwargs*)[[source]](_modules/pynvim/api/buffer.html#Buffer.clear_highlight)[¶](#pynvim.api.Buffer.clear_highlight "Permalink to this definition")

Clear highlights from the buffer.

`mark`(*name*)[[source]](_modules/pynvim/api/buffer.html#Buffer.mark)[¶](#pynvim.api.Buffer.mark "Permalink to this definition")

Return (row, col) tuple for a named mark.

`name`[¶](#pynvim.api.Buffer.name "Permalink to this definition")

Get the buffer name.

`number`[¶](#pynvim.api.Buffer.number "Permalink to this definition")

Get the buffer number.

`range`(*start*, *end*)[[source]](_modules/pynvim/api/buffer.html#Buffer.range)[¶](#pynvim.api.Buffer.range "Permalink to this definition")

Return a Range object, which represents part of the Buffer.

`update_highlights`(*src\_id*, *hls*, *clear\_start=0*, *clear\_end=-1*, *clear=False*, *async\_=True*)[[source]](_modules/pynvim/api/buffer.html#Buffer.update_highlights)[¶](#pynvim.api.Buffer.update_highlights "Permalink to this definition")

Add or update highlights in batch to avoid unnecessary redraws.

A src\_id must have been allocated prior to use of this function. Use

for instance nvim.new\_highlight\_source() to get a src\_id for your

plugin.

hls should be a list of highlight items. Each item should be a list

or tuple on the form (“GroupName”, linenr, col\_start, col\_end) or

(“GroupName”, linenr) to highlight an entire line.

By default existing highlights are preserved. Specify a line range with

clear\_start and clear\_end to replace highlights in this range. As a

shorthand, use clear=True to clear the entire buffer before adding the

new highlights.

`valid`[¶](#pynvim.api.Buffer.valid "Permalink to this definition")

Return True if the buffer still exists.

Window Class[¶](#window-class "Permalink to this headline")

-----------------------------------------------------------

*class* `pynvim.api.``Window`(*session*, *code\_data*)[[source]](_modules/pynvim/api/window.html#Window)[¶](#pynvim.api.Window "Permalink to this definition")

A remote Nvim window.

`buffer`[¶](#pynvim.api.Window.buffer "Permalink to this definition")

Get the Buffer currently being displayed by the window.

`col`[¶](#pynvim.api.Window.col "Permalink to this definition")

0-indexed, on-screen window position(col) in display cells.

`cursor`[¶](#pynvim.api.Window.cursor "Permalink to this definition")

Get the (row, col) tuple with the current cursor position.

`height`[¶](#pynvim.api.Window.height "Permalink to this definition")

Get the window height in rows.

`number`[¶](#pynvim.api.Window.number "Permalink to this definition")

Get the window number.

`row`[¶](#pynvim.api.Window.row "Permalink to this definition")

0-indexed, on-screen window position(row) in display cells.

`tabpage`[¶](#pynvim.api.Window.tabpage "Permalink to this definition")

Get the Tabpage that contains the window.

`valid`[¶](#pynvim.api.Window.valid "Permalink to this definition")

Return True if the window still exists.

`width`[¶](#pynvim.api.Window.width "Permalink to this definition")

Get the window width in rows.

Tabpage Class[¶](#tabpage-class "Permalink to this headline")

-------------------------------------------------------------

*class* `pynvim.api.``Tabpage`(*\*args*)[[source]](_modules/pynvim/api/tabpage.html#Tabpage)[¶](#pynvim.api.Tabpage "Permalink to this definition")

A remote Nvim tabpage.

`number`[¶](#pynvim.api.Tabpage.number "Permalink to this definition")

Get the tabpage number.

`valid`[¶](#pynvim.api.Tabpage.valid "Permalink to this definition")

Return True if the tabpage still exists.

`window`[¶](#pynvim.api.Tabpage.window "Permalink to this definition")

Get the Window currently focused on the tabpage.

Development[¶](#development "Permalink to this headline")

---------------------------------------------------------

If you change the code, you need to run:

```

pip2 install .

pip3 install .

```

for the changes to have effect.

Alternatively you could execute Neovim with the `$PYTHONPATH` environment variable:

```

PYTHONPATH=/path/to/pynvim nvim

```

But note this is not completely reliable,

as installed packages can appear before `$PYTHONPATH` in the python search path.

You need to rerun this command if you have changed the code,

in order for Neovim to use it for the plugin host.

To run the tests execute:

```

python -m pytest

```

This will run the tests in an embedded instance of Neovim, with the current

directory added to `sys.path`.

If you want to test a different version than `nvim` in `$PATH` use:

```

NVIM\_CHILD\_ARGV='["/path/to/nvim", "-u", "NONE", "--embed", "--headless"]' pytest

```

Alternatively, if you want to see the state of nvim, you could use:

```

export NVIM\_LISTEN\_ADDRESS=/tmp/nvimtest

xterm -e "nvim -u NONE"&

python -m pytest

```

But note you need to restart Neovim every time you run the tests!

Substitute your favorite terminal emulator for `xterm`.

### Troubleshooting[¶](#troubleshooting "Permalink to this headline")

You can run the plugin host in Neovim with logging enabled to debug errors:

```

NVIM\_PYTHON\_LOG\_FILE=logfile NVIM\_PYTHON\_LOG\_LEVEL=DEBUG nvim

```

As more than one Python host process might be started,

the log filenames take the pattern `logfile\_pyX\_KIND`

where `X` is the major python version (2 or 3)

and `KIND` is either “rplugin” or “script” (for the `:python[3]` script interface).

If the host cannot start at all,

the error could be found in `~/.nvimlog` if `nvim` was compiled with logging.

### Usage through the Python REPL[¶](#usage-through-the-python-repl "Permalink to this headline")

A number of different transports are supported,

but the simplest way to get started is with the python REPL.

First, start Neovim with a known address (or use the `$NVIM\_LISTEN\_ADDRESS` of a running instance):

```

NVIM\_LISTEN\_ADDRESS=/tmp/nvim nvim

```

In another terminal,

connect a python REPL to Neovim (note that the API is similar to the one exposed by the [python-vim bridge](http://vimdoc.sourceforge.net/htmldoc/if_pyth.html#python-vim)):

```

>>> from pynvim 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.current.buffer # Get the current buffer

>>> buffer[0] = 'replace first line'

>>> buffer[:] = ['replace whole buffer']

>>> nvim.command('vsplit')

>>> nvim.windows[1].width = 10

>>> nvim.vars['global\_var'] = [1, 2, 3]

>>> nvim.eval('g:global\_var')

[1, 2, 3]

```

You can embed Neovim into your python application instead of binding to a running neovim instance:

```

>>> from pynvim import attach

>>> nvim = attach('child', argv=["/bin/env", "nvim", "--embed", "--headless"])

```

The tests can be consulted for more examples.

