neovim

if_pyth.txt (24835B)

---

*if_pyth.txt*   Nvim


	  NVIM REFERENCE MANUAL


The Python Interface to NVim				*if_pyth* *python* *Python*

See |provider-python| for more information.

                                     Type |gO| to see the table of contents.

==============================================================================
Commands						*python-commands*

				*:python* *:py* *E263* *E264* *E887*
:[range]py[thon] {stmt}
		Execute Python statement {stmt}.  A simple check if
		the `:python` command is working: >vim
			:python print("Hello")

:[range]py[thon] << [trim] [{endmarker}]
{script}
{endmarker}
		Execute Python script {script}.  Useful for including
		python code in Vim scripts.  Requires Python, see
		|script-here|.

If [endmarker] is omitted from after the "<<", a dot '.' must be used after
{script}, like for the |:append| and |:insert| commands.  Refer to
|:let-heredoc| for more information.

Example: >vim
function! IcecreamInitialize()
python << EOF
class StrawberryIcecream:
	def __call__(self):
		print('EAT ME')
EOF
endfunction

To see what version of Python you have: >vim
:python print(sys.version)

There is no need to "import sys", it's done by default.

						*python-environment*
Environment variables set in Vim are not always available in Python.  This
depends on how Vim and Python were build.  Also see
https://docs.python.org/3/library/os.html#os.environ

Note: Python is very sensitive to indenting.  Make sure the "class" line and
"EOF" do not have any indent.

						*:pydo*
:[range]pydo {body}	Execute Python function "def _vim_pydo(line, linenr):
		{body}" for each line in the [range], with the
		function arguments being set to the text of each line
		in turn, without a trailing <EOL>, and the current
		line number.  The function should return a string or
		None.  If a string is returned, it becomes the text of
		the line in the current turn.  The default for [range]
		is the whole file: "1,$".

Examples:
>vim
:pydo return "%s\t%d" % (line[::-1], len(line))
:pydo if line: return "%4d: %s" % (linenr, line)
<
One can use `:pydo` in possible conjunction with `:py` to filter a range using
python.  For example: >vim

:py3 << EOF
needle = vim.eval('@a')
replacement = vim.eval('@b')

def py_vim_string_replace(str):
	return str.replace(needle, replacement)
EOF
:'<,'>py3do return py_vim_string_replace(line)
<
						*:pyfile* *:pyf*
:[range]pyf[ile] {file}
		Execute the Python script in {file}.  The whole
		argument is used as a single file name.

Both of these commands do essentially the same thing - they execute a piece of
Python code, with the "current range" |python-range| set to the given line
range.

In the case of :python, the code to execute is in the command-line.
In the case of :pyfile, the code to execute is the contents of the given file.

Python commands cannot be used in the |sandbox|.

To pass arguments you need to set sys.argv[] explicitly.  Example: >vim

:python sys.argv = ["foo", "bar"]
:pyfile myscript.py

Here are some examples					*python-examples*
>vim
:python from vim import *
:python current.line = str.upper(current.line)
:python print("Hello")
:python str = current.buffer[42]

Note that changes (such as the "import" statements) persist from one command
to the next, just like the Python REPL.

						*script-here*
When using a script language in-line, you might want to skip this when the
language isn't supported.
>vim
  if has('python')
    python << EOF
      print("python works")
  EOF
  endif
<
Note that "EOF" must be at the start of the line without preceding white
space.

==============================================================================
The vim module							*python-vim*

Python code gets all of its access to vim (with one exception - see
|python-output| below) via the "vim" module.  The vim module implements two
methods, three constants, and one error object.  You need to import the vim
module before using it: >vim
:python import vim

Overview >vim
:py print("Hello")		# displays a message
:py vim.command(cmd)		# execute an Ex command
:py w = vim.windows[n]		# gets window "n"
:py cw = vim.current.window	# gets the current window
:py b = vim.buffers[n]		# gets buffer "n"
:py cb = vim.current.buffer	# gets the current buffer
:py w.height = lines		# sets the window height
:py w.cursor = (row, col)	# sets the window cursor position
:py pos = w.cursor		# gets a tuple (row, col)
:py name = b.name		# gets the buffer file name
:py line = b[n]			# gets a line from the buffer
:py lines = b[n:m]		# gets a list of lines
:py num = len(b)		# gets the number of lines
:py b[n] = str			# sets a line in the buffer
:py b[n:m] = [str1, str2, str3]	# sets a number of lines at once
:py del b[n]			# deletes a line
:py del b[n:m]			# deletes a number of lines


Methods of the "vim" module

vim.command(str)					*python-command*
Executes the vim (ex-mode) command str.  Returns None.
Examples: >vim
    :py vim.command("set tw=72")
    :py vim.command("%s/aaa/bbb/g")
<	The following definition executes Normal mode commands: >python
	def normal(str):
		vim.command("normal "+str)
	# Note the use of single quotes to delimit a string containing
	# double quotes
	normal('"a2dd"aP')

vim.eval(str)						*python-eval*
Evaluates the expression str using the vim internal expression
evaluator (see |expression|).  Returns the expression result as:
- a string if the Vim expression evaluates to a string or number
- a list if the Vim expression evaluates to a Vim |list|
- a dictionary if the Vim expression evaluates to a Vim |dict|
- a boolean if Vim exression evaluates to |v:true| or |v:false|
- `None` if Vim expression evaluates to |v:null|
Dictionaries and lists are recursively expanded.
Examples: >vim
    :py text_width = vim.eval("&tw")
    :py str = vim.eval("12+12")		# NB result is a string! Use
					# int() to convert to a
					# number.

vim.strwidth(str)					*python-strwidth*
Like |strwidth()|: returns number of display cells str occupies, tab
is counted as one cell.

vim.foreach_rtp(callable)				*python-foreach_rtp*
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.

`vim.chdir(*args, **kwargs)`				*python-chdir*
`vim.fchdir(*args, **kwargs)`				*python-fchdir*
Run os.chdir or os.fchdir, then all appropriate vim stuff.
Note: you should not use these functions directly, use os.chdir and
      os.fchdir instead.  Behavior of vim.fchdir is undefined in case
      os.fchdir does not exist.

Error object of the "vim" module

vim.error						*python-error*
Upon encountering a Vim error, Python raises an exception of type
vim.error.
Example: >python
	try:
		vim.command("put a")
	except vim.error:
		# nothing in register a

Constants of the "vim" module

Note that these are not actually constants - you could reassign them.
But this is silly, as you would then lose access to the vim objects
to which the variables referred.

vim.buffers						*python-buffers*
A mapping object providing access to the list of vim buffers.  The
object supports the following operations: >vim
    :py b = vim.buffers[i]	# Indexing (read-only)
    :py b in vim.buffers	# Membership test
    :py n = len(vim.buffers)	# Number of elements
    :py for b in vim.buffers:	# Iterating over buffer list
<
vim.windows						*python-windows*
A sequence object providing access to the list of vim windows.  The
object supports the following operations: >vim
    :py w = vim.windows[i]	# Indexing (read-only)
    :py w in vim.windows	# Membership test
    :py n = len(vim.windows)	# Number of elements
    :py for w in vim.windows:	# Sequential access
<	Note: vim.windows object always accesses current tab page.
|python-tabpage|.windows objects are bound to parent |python-tabpage|
object and always use windows from that tab page (or throw vim.error
in case tab page was deleted).  You can keep a reference to both
without keeping a reference to vim module object or |python-tabpage|,
they will not lose their properties in this case.

vim.tabpages						*python-tabpages*
A sequence object providing access to the list of vim tab pages.  The
object supports the following operations: >vim
    :py t = vim.tabpages[i]	# Indexing (read-only)
    :py t in vim.tabpages	# Membership test
    :py n = len(vim.tabpages)	# Number of elements
    :py for t in vim.tabpages:	# Sequential access
<
vim.current						*python-current*
An object providing access (via specific attributes) to various
"current" objects available in vim:
	vim.current.line	The current line (RW)		String
	vim.current.buffer	The current buffer (RW)		Buffer
	vim.current.window	The current window (RW)		Window
	vim.current.tabpage	The current tab page (RW)	TabPage
	vim.current.range	The current line range (RO)	Range

The last case deserves a little explanation.  When the :python or
:pyfile command specifies a range, this range of lines becomes the
"current range".  A range is a bit like a buffer, but with all access
restricted to a subset of lines.  See |python-range| for more details.

Note: When assigning to vim.current.{buffer,window,tabpage} it expects
valid |python-buffer|, |python-window| or |python-tabpage| objects
respectively.  Assigning triggers normal (with |autocommand|s)
switching to given buffer, window or tab page.  It is the only way to
switch UI objects in python: you can't assign to
|python-tabpage|.window attribute.  To switch without triggering
autocommands use >vim
    py << EOF
    saved_eventignore = vim.options['eventignore']
    vim.options['eventignore'] = 'all'
    try:
        vim.current.buffer = vim.buffers[2] # Switch to buffer 2
    finally:
        vim.options['eventignore'] = saved_eventignore
    EOF
<
vim.vars						*python-vars*
vim.vvars						*python-vvars*
Dictionary-like objects holding dictionaries with global (|g:|) and
vim (|v:|) variables respectively.

vim.options						*python-options*
Object partly supporting mapping protocol (supports setting and
getting items) providing a read-write access to global options.
Note: unlike |:set| this provides access only to global options.  You
cannot use this object to obtain or set local options' values or
access local-only options in any fashion.  Raises KeyError if no
global option with such name exists (i.e. does not raise KeyError for
|global-local| options and global only options, but does for window-
and buffer-local ones).  Use |python-buffer| objects to access to
buffer-local options and |python-window| objects to access to
window-local options.

Type of this object is available via "Options" attribute of vim
module.

Output from Python					*python-output*
Vim displays all Python code output in the Vim message area.  Normal
output appears as information messages, and error output appears as
error messages.

In implementation terms, this means that all output to sys.stdout
(including the output from print statements) appears as information
messages, and all output to sys.stderr (including error tracebacks)
appears as error messages.

						*python-input*
Input (via sys.stdin, including input() and raw_input()) is not
supported, and may cause the program to crash.  This should probably
be fixed.

			  *python3-directory* *pythonx-directory*
Python 'runtimepath' handling				*python-special-path*

In python vim.VIM_SPECIAL_PATH special directory is used as a replacement for
the list of paths found in 'runtimepath': with this directory in sys.path and
vim.path_hooks in sys.path_hooks python will try to load module from
{rtp}/python3 and {rtp}/pythonx for each {rtp} found in 'runtimepath'.

Implementation is similar to the following: >python

   from imp import find_module, load_module
   import vim
   import sys

   class VimModuleLoader(object):
       def __init__(self, module):
           self.module = module

       def load_module(self, fullname, path=None):
           return self.module

   def _find_module(fullname, oldtail, path):
       idx = oldtail.find('.')
       if idx > 0:
           name = oldtail[:idx]
           tail = oldtail[idx+1:]
           fmr = find_module(name, path)
           module = load_module(fullname[:-len(oldtail)] + name, *fmr)
           return _find_module(fullname, tail, module.__path__)
       else:
           fmr = find_module(fullname, path)
           return load_module(fullname, *fmr)

   # It uses vim module itself in place of VimPathFinder class: it does not
   # matter for python which object has find_module function attached to as
   # an attribute.
   class VimPathFinder(object):
       @classmethod
       def find_module(cls, fullname, path=None):
           try:
               return VimModuleLoader(_find_module(fullname, fullname, path or vim._get_paths()))
           except ImportError:
               return None

       @classmethod
       def load_module(cls, fullname, path=None):
           return _find_module(fullname, fullname, path or vim._get_paths())

   def hook(path):
       if path == vim.VIM_SPECIAL_PATH:
           return VimPathFinder
       else:
           raise ImportError

   sys.path_hooks.append(hook)

vim.VIM_SPECIAL_PATH				*python-VIM_SPECIAL_PATH*
String constant used in conjunction with vim path hook.  If path hook
installed by vim is requested to handle anything but path equal to
vim.VIM_SPECIAL_PATH constant it raises ImportError.  In the only
other case it uses special loader.

Note: you must not use value of this constant directly, always use
      vim.VIM_SPECIAL_PATH object.

vim.find_module(...)					*python-find_module*
vim.path_hook(path)					*python-path_hook*
Methods or objects used to implement path loading as described above.
You should not be using any of these directly except for vim.path_hook
in case you need to do something with sys.meta_path. It is not
guaranteed that any of the objects will exist in the future vim
versions.

vim._get_paths						*python-_get_paths*
Methods returning a list of paths which will be searched for by path
hook.  You should not rely on this method being present in future
versions, but can use it for debugging.

It returns a list of {rtp}/python3 and {rtp}/pythonx
directories for each {rtp} in 'runtimepath'.

==============================================================================
Buffer objects						*python-buffer*

Buffer objects represent vim buffers.  You can obtain them in a number of
ways:
- via vim.current.buffer (|python-current|)
- from indexing vim.buffers (|python-buffers|)
- from the "buffer" attribute of a window (|python-window|)

Buffer objects have two read-only attributes - name - the full file name for
the buffer, and number - the buffer number.  They also have three methods
(append, mark, and range; see below).

You can also treat buffer objects as sequence objects.  In this context, they
act as if they were lists (yes, they are mutable) of strings, with each
element being a line of the buffer.  All of the usual sequence operations,
including indexing, index assignment, slicing and slice assignment, work as
you would expect.  Note that the result of indexing (slicing) a buffer is a
string (list of strings).  This has one unusual consequence - b[:] is
different from b.  In particular, "b[:] = None" deletes the whole of the
buffer, whereas "b = None" merely updates the variable b, with no effect on
the buffer.

Buffer indexes start at zero, as is normal in Python.  This differs from vim
line numbers, which start from 1.  This is particularly relevant when dealing
with marks (see below) which use vim line numbers.

The buffer object attributes are:
b.vars		Dictionary-like object used to access
		|buffer-variable|s.
b.options	Mapping object (supports item getting, setting and
		deleting) that provides access to buffer-local options
		and buffer-local values of |global-local| options.  Use
		|python-window|.options if option is window-local,
		this object will raise KeyError.  If option is
		|global-local| and local value is missing getting it
		will return None.
b.name		String, RW.  Contains buffer name (full path).
		Note: when assigning to b.name |BufFilePre| and
		|BufFilePost| autocommands are launched.
b.number	Buffer number.  Can be used as |python-buffers| key.
		Read-only.
b.valid		True or False.  Buffer object becomes invalid when
		corresponding buffer is wiped out.

The buffer object methods are:
b.append(str)	Append a line to the buffer
b.append(str, nr)  Idem, below line "nr"
b.append(list)	Append a list of lines to the buffer
		Note that the option of supplying a list of strings to
		the append method differs from the equivalent method
		for Python's built-in list objects.
b.append(list, nr)  Idem, below line "nr"
b.mark(name)	Return a tuple (row,col) representing the position
		of the named mark (can also get the []"<> marks)
b.range(s,e)	Return a range object (see |python-range|) which
		represents the part of the given buffer between line
		numbers s and e |inclusive|.

Note that when adding a line it must not contain a line break character '\n'.
A trailing '\n' is allowed and ignored, so that you can do: >vim
:py b.append(f.readlines())

Buffer object type is available using "Buffer" attribute of vim module.

Examples (assume b is the current buffer) >vim
:py print(b.name)		# write the buffer file name
:py b[0] = "hello!!!"		# replace the top line
:py b[:] = None			# delete the whole buffer
:py del b[:]			# delete the whole buffer
:py b[0:0] = [ "a line" ]	# add a line at the top
:py del b[2]			# delete a line (the third)
:py b.append("bottom")		# add a line at the bottom
:py n = len(b)			# number of lines
:py (row,col) = b.mark('a')	# named mark
:py r = b.range(1,5)		# a sub-range of the buffer
:py b.vars["foo"] = "bar"	# assign b:foo variable
:py b.options["ff"] = "dos"	# set fileformat
:py del b.options["ar"]		# same as :set autoread<

==============================================================================
Range objects						*python-range*

Range objects represent a part of a vim buffer.  You can obtain them in a
number of ways:
- via vim.current.range (|python-current|)
- from a buffer's range() method (|python-buffer|)

A range object is almost identical in operation to a buffer object.  However,
all operations are restricted to the lines within the range (this line range
can, of course, change as a result of slice assignments, line deletions, or
the range.append() method).

The range object attributes are:
r.start		Index of first line into the buffer
r.end		Index of last line into the buffer

The range object methods are:
r.append(str)	Append a line to the range
r.append(str, nr)  Idem, after line "nr"
r.append(list)	Append a list of lines to the range
		Note that the option of supplying a list of strings to
		the append method differs from the equivalent method
		for Python's built-in list objects.
r.append(list, nr)  Idem, after line "nr"

Range object type is available using "Range" attribute of vim module.

Example (assume r is the current range):
# Send all lines in a range to the default printer
vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))

==============================================================================
Window objects						*python-window*

Window objects represent vim windows.  You can obtain them in a number of
ways:
- via vim.current.window (|python-current|)
- from indexing vim.windows (|python-windows|)
- from indexing "windows" attribute of a tab page (|python-tabpage|)
- from the "window" attribute of a tab page (|python-tabpage|)

You can manipulate window objects only through their attributes.  They have no
methods, and no sequence or other interface.

Window attributes are:
buffer (read-only)	The buffer displayed in this window
cursor (read-write)	The current cursor position in the window
			This is a tuple, (row,col).
height (read-write)	The window height, in rows
width (read-write)	The window width, in columns
vars (read-only)	The window |w:| variables. Attribute is
			unassignable, but you can change window
			variables this way
options (read-only)	The window-local options. Attribute is
			unassignable, but you can change window
			options this way. Provides access only to
			window-local options, for buffer-local use
			|python-buffer| and for global ones use
			|python-options|. If option is |global-local|
			and local value is missing getting it will
			return None.
number (read-only)	Window number.  The first window has number 1.
			This is zero in case it cannot be determined
			(e.g. when the window object belongs to other
			tab page).
row, col (read-only)	On-screen window position in display cells.
			First position is zero.
tabpage (read-only)	Window tab page.
valid (read-write)	True or False. Window object becomes invalid
			when corresponding window is closed.

The height attribute is writable only if the screen is split horizontally.
The width attribute is writable only if the screen is split vertically.

Window object type is available using "Window" attribute of vim module.

==============================================================================
Tab page objects					*python-tabpage*

Tab page objects represent vim tab pages. You can obtain them in a number of
ways:
- via vim.current.tabpage (|python-current|)
- from indexing vim.tabpages (|python-tabpages|)

You can use this object to access tab page windows. They have no methods and
no sequence or other interfaces.

Tab page attributes are:
number		The tab page number like the one returned by
		|tabpagenr()|.
windows		Like |python-windows|, but for current tab page.
vars		The tab page |t:| variables.
window		Current tabpage window.
valid		True or False. Tab page object becomes invalid when
		corresponding tab page is closed.

TabPage object type is available using "TabPage" attribute of vim module.

==============================================================================
pyeval() and py3eval() Vim functions			*python-pyeval*

To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()|
functions to evaluate Python expressions and pass their values to Vim script.
|pyxeval()| is also available.

==============================================================================
Python 3						*python3*

As Python 3 is the only supported version in Nvim, "python" is synonymous
with "python3" in the current version. However, code that aims to support older
versions of Nvim, as well as Vim, should prefer to use "python3" variants
explicitly if Python 3 is required.

						*:py3* *:python3*
:[range]py3 {stmt}
:[range]py3 << [trim] [{endmarker}]
{script}
{endmarker}

:[range]python3 {stmt}
:[range]python3 << [trim] [{endmarker}]
{script}
{endmarker}
The `:py3` and `:python3` commands work similar to `:python`.  A
simple check if the `:py3` command is working: >vim
	:py3 print("Hello")
<
To see what version of Python you have: >vim
	:py3 import sys
	:py3 print(sys.version)
<							*:py3file*
:[range]py3f[ile] {file}
The `:py3file` command works similar to `:pyfile`.
						*:py3do*
:[range]py3do {body}
The `:py3do` command works similar to `:pydo`.

						*E880*
Raising SystemExit exception in python isn't endorsed way to quit vim, use:
>vim
:py vim.command("qall!")
<
						*has-python*
You can test if Python is available with: >vim
if has('pythonx')
  echo 'there is Python'
endif
if has('python3')
  echo 'there is Python 3.x'
endif

Python 2 is no longer supported. Thus `has('python')` always returns
zero for backwards compatibility reasons.

==============================================================================
Python X						*python_x* *pythonx*

The "pythonx" and "pyx" prefixes were introduced for python code which
works with Python 2.6+ and Python 3. As Nvim only supports Python 3,
all these commands are now synonymous to their "python3" equivalents.

						*:pyx* *:pythonx*
`:pyx` and `:pythonx` work the same as `:python3`.  To check if `:pyx` works: >vim
:pyx print("Hello")

To see what version of Python is being used: >vim
:pyx import sys
:pyx print(sys.version)
<
				*:pyxfile* *python_x-special-comments*
`:pyxfile` works the same as `:py3file`.

						*:pyxdo*
`:pyxdo` works the same as `:py3do`.

						*has-pythonx*
To check if `pyx*` functions and commands are available: >vim
if has('pythonx')
  echo 'pyx* commands are available. (Python ' .. &pyx .. ')'
endif
<

vim:tw=78:ts=8:noet:ft=help:norl: