if_pyth.txt   Nvim


                  VIM REFERENCE MANUAL    by Paul Moore

The Python Interface to Vim                             python Python

See provider-python for more information. {Nvim}

                                      Type gO to see the table of contents.

1. 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:

python print "Hello"

:[range]py[thon] << {endmarker}
{script}
{endmarker}
                        Execute Python script {script}.
                        Note: This command doesn't work when Python isn't
                        available.  To avoid errors, see script-here.

{endmarker} must NOT be preceded by any white space.  If {endmarker} is
omitted from after the "<<", a dot '.' must be used after {script}, like
for the :append and :insert commands.
This form of the :python command is mainly useful for including python code
in Vim scripts.

Example:

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

To see what version of Python you have:

python import sys
python print(sys.version)

Note: Python is very sensitive to the 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:

pydo return "%s\t%d" % (line[::-1], len(line))
pydo if line: return "%4d: %s" % (linenr, 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:

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

Here are some examples                                  python-examples

python from vim import *
python from string import upper
python current.line = upper(current.line)
python print "Hello"
python str = current.buffer[42]

(Note that changes - like the imports - persist from one command to the next,
just like in the Python interpreter.)

                                                        script-here
When using a script language in-line, you might want to skip this when the
language isn't supported.  Note that this mechanism doesn't work:

if has('python')
  python << EOF
    this will NOT work!
EOF
endif

Instead, put the Python command in a function and call that function:

if has('python')
  function DefPython()
    python << EOF
      this works
EOF
  endfunction
  call DefPython()
endif

Note that "EOF" must be at the start of the line.

2. 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:

python import vim

Overview

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:

py vim.command("set tw=72")
py vim.command("%s/aaa/bbb/g")

        The following definition executes Normal mode commands:

def normal(str):
        vim.command("normal "+str)
# Note the use of single quotes to delimit a string containing
# double quotes
normal('"a2dd"aP')

                                                                E659
        The ":python" command cannot be used recursively with Python 2.2 and
        older.  This only works with Python 2.3 and later:

py vim.command("python print 'Hello again Python'")

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 dictionary
        Dictionaries and lists are recursively expanded.
        Examples:

:py text_width = vim.eval("&tw")
:py str = vim.eval("12+12")         # NB result is a string! Use
                                    # string.atoi() to convert to
                                    # a number.

vim.bindeval(str)                                       python-bindeval
        Like python-eval, but returns special objects described in 
        python-bindeval-objects. These python objects let you modify (List 
        or Dictionary) or call (Funcref) vim objects.

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:

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:

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:

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:

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 autocommands) 
        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

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. Identical to vim.bindeval("g:")  , 
        but faster.

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.

                    python2-directory 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}/python2 (or python3) and {rtp}/pythonx (for both python versions) for 
each {rtp} found in 'runtimepath'.

Implementation is similar to the following, but written in C:

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}/python2 (or {rtp}/python3) and 
        {rtp}/pythonx directories for each {rtp} in 'runtimepath'.

3. 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-variables.
        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:

py b.append(f.readlines())

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

Examples (assume b is the current buffer)

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<

4. 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))

5. 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.

6. 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.

7. vim.bindeval objects                         python-bindeval-objects

vim.Dictionary object                           python-Dictionary
    Dictionary-like object providing access to vim Dictionary type.
    Attributes:
        Attribute  Description 
        locked     One of                       python-.locked
                    Value           Description 
                    zero            Variable is not locked
                    vim.VAR_LOCKED  Variable is locked, but can be unlocked
                    vim.VAR_FIXED   Variable is locked and can't be unlocked
                   Read-write. You can unlock locked variable by assigning 
                   True   or False   to this attribute. No recursive locking 
                   is supported.
        scope      One of
                    Value              Description 
                    zero               Dictionary is not a scope one
                    vim.VAR_DEF_SCOPE  g: or l: dictionary
                    vim.VAR_SCOPE      Other scope dictionary,
                                       see internal-variables
    Methods (note: methods do not support keyword arguments):
        Method      Description 
        keys()      Returns a list with dictionary keys.
        values()    Returns a list with dictionary values.
        items()     Returns a list of 2-tuples with dictionary contents.
        update(iterable), update(dictionary), update(**kwargs)
                    Adds keys to dictionary.
        get(key[, default=None])
                    Obtain key from dictionary, returning the default if it is 
                    not present.
        pop(key[, default])
                    Remove specified key from dictionary and return 
                    corresponding value. If key is not found and default is 
                    given returns the default, otherwise raises KeyError.
        popitem()
                    Remove random key from dictionary and return (key, value) 
                    pair.
        has_key(key)
                    Check whether dictionary contains specified key, similar 
                    to key in dict  .

        __new__(), __new__(iterable), __new__(dictionary), __new__(update)
                    You can use vim.Dictionary()   to create new vim 
                    dictionaries. d=vim.Dictionary(arg)   is the same as 
                    d=vim.bindeval('{}');d.update(arg)  . Without arguments 
                    constructs empty dictionary.

    Examples:

d = vim.Dictionary(food="bar")          # Constructor
d['a'] = 'b'                            # Item assignment
print d['a']                            # getting item
d.update({'c': 'd'})                    # .update(dictionary)
d.update(e='f')                         # .update(**kwargs)
d.update((('g', 'h'), ('i', 'j')))      # .update(iterable)
for key in d.keys():                    # .keys()
for val in d.values():                  # .values()
for key, val in d.items():              # .items()
print isinstance(d, vim.Dictionary)     # True
for key in d:                           # Iteration over keys
class Dict(vim.Dictionary):             # Subclassing

    Note: when iterating over keys you should not modify dictionary.

vim.List object                                 python-List
    Sequence-like object providing access to vim List type.
    Supports .locked   attribute, see python-.locked. Also supports the 
    following methods:
        Method          Description 
        extend(item)    Add items to the list.

        __new__(), __new__(iterable)
                        You can use vim.List()   to create new vim lists. 
                        l=vim.List(iterable)   is the same as 
                        l=vim.bindeval('[]');l.extend(iterable)  . Without 
                        arguments constructs empty list.
    Examples:

l = vim.List("abc")             # Constructor, result: ['a', 'b', 'c']
l.extend(['abc', 'def'])        # .extend() method
print l[1:]                     # slicing
l[:0] = ['ghi', 'jkl']          # slice assignment
print l[0]                      # getting item
l[0] = 'mno'                    # assignment
for i in l:                     # iteration
print isinstance(l, vim.List)   # True
class List(vim.List):           # Subclassing

vim.Function object                             python-Function
    Function-like object, acting like vim Funcref object. Supports .name   
    attribute and is callable. Accepts special keyword argument self  , see 
    Dictionary-function. You can also use vim.Function(name)   constructor, 
    it is the same as vim.bindeval('function(%s)'%json.dumps(name))  .

    Examples:

f = vim.Function('tr')                  # Constructor
print f('abc', 'a', 'b')                # Calls tr('abc', 'a', 'b')
vim.command('''
    function DictFun() dict
        return self
    endfunction
''')
f = vim.bindeval('function("DictFun")')
print f(self={})                        # Like call('DictFun', [], {})
print isinstance(f, vim.Function)       # True

8. 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.

9. Python 3                                             python3

                                                        :py3 :python3
The :py3   and :python3   commands work similar to :python  .  A simple check
if the :py3   command is working:

py3 print("Hello")

To see what version of Python you have:

py3 import sys
py3 print(sys.version)

                                                        :py3file
The :py3file   command works similar to :pyfile  .
                                                        :py3do
The :py3do   command works similar to :pydo  .

                                                        E880
Raising SystemExit exception in python isn't endorsed way to quit vim, use:

py vim.command("qall!")

                                                        has-python
You can test what Python version is available with:

if has('python')
  echo 'there is Python 2.x'
elseif has('python3')
  echo 'there is Python 3.x'
endif

Note however, that if Python 2 and 3 are both available, but not loaded,
these has() calls will try to load them.

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