path: root/runtime/doc/if_pyth.txt

*if_pyth.txt*   For Vim version 7.3.  Last change: 2013 Jan 30


		  VIM REFERENCE MANUAL    by Paul Moore


The Python Interface to Vim				*python* *Python*

1. Commands					|python-commands|
2. The vim module				|python-vim|
3. Buffer objects				|python-buffer|
4. Range objects				|python-range|
5. Window objects				|python-window|
6. pyeval(), py3eval() Vim functions		|python-pyeval|
7. Dynamic loading				|python-dynamic|
8. Python 3					|python3|

{Vi does not have any of these commands}

The Python 2.x interface is available only when Vim was compiled with the
|+python| feature.
The Python 3 interface is available only when Vim was compiled with the
|+python3| feature.

==============================================================================
1. Commands						*python-commands*

					*:python* *:py* *E205* *E263* *E264*
:[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 the Python
			feature wasn't compiled in.  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
<
Note: Python is very sensitive to the indenting.  Make sure the "class" line
and "EOF" do not have any indent.

							*:pyfile* *:pyf*
:[range]pyf[ile] {file}
			Execute the Python script in {file}.  The whole
			argument is used as a single file name.  {not in Vi}

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

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

	    :py tagList = vim.eval('taglist("eval_expr")')
<	The latter will return a python list of python dicts, for instance:
	[{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name':
	'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}]

vim.bindeval(str)					*python-bindeval*
	Like |python-eval|, but
	1. if expression evaluates to |List| or |Dictionary| it is returned as 
	   vimlist or vimdictionary python type that are connected to original 
	   list or dictionary. Thus modifications to these objects imply 
	   modifications of the original.

	   Additionally, vimlist and vimdictionary type have read-write 
	   `.locked` attribute that returns
	     Value           Meaning ~
	     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
	   integer constants. If variable is not fixed, you can do 
	   `var.locked=True` to lock it and `var.locked=False` to unlock. 
	   There is no recursive locking like |:lockvar|! does. There is also 
	   no way to lock a specific key or check whether it is locked (in any 
	   case these locks are ignored by anything except |:let|: |extend()| 
	   does not care, neither does python interface).

	   Vimdictionary type also supports `.scope` attribute which is one of
	     Value              Meaning ~
	     zero               Dictionary is not a scope one
	     vim.VAR_DEF_SCOPE  Function-local or global scope dictionary
	     vim.VAR_SCOPE      Other scope dictionary

	2. if expression evaluates to a function reference, then it returns 
	   callable vimfunction object. Use self keyword argument to assign 
	   |self| object for dictionary functions.

	Note: this function has the same behavior as |lua-eval| (except that 
	      lua does not support running vim functions), |python-eval| is 
	      kept for backwards compatibility in order not to make scripts 
	      relying on outputs of vim.eval() being a copy of original or 
	      vim.eval("1") returning a string.



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 sequence 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:	# Sequential access
<
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
<
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 (RO)		Buffer
		vim.current.window	The current window (RO)		Window
		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.


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.

==============================================================================
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 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())

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

==============================================================================
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"

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

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
The height attribute is writable only if the screen is split horizontally.
The width attribute is writable only if the screen is split vertically.

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

==============================================================================
7. Dynamic loading					*python-dynamic*

On MS-Windows the Python library can be loaded dynamically.  The |:version|
output then includes |+python/dyn|.

This means that Vim will search for the Python DLL file only when needed.
When you don't use the Python interface you don't need it, thus you can use
Vim without this DLL file.

To use the Python interface the Python DLL must be in your search path.  In a
console window type "path" to see what directories are used.

The name of the DLL must match the Python version Vim was compiled with.
Currently the name is "python24.dll".  That is for Python 2.4.  To know for
sure edit "gvim.exe" and search for "python\d*.dll\c".

==============================================================================
8. Python 3						*python3*

							*:py3* *:python3*
The |:py3| and |:python3| commands work similar to |:python|.  A simple check
if the `:py3` command is wrong: >
	:py3 print("Hello")
<							*:py3file*
The |:py3file| command works similar to |:pyfile|.


Vim can be built in four ways (:version output):
1. No Python support	    (-python, -python3)
2. Python 2 support only    (+python or +python/dyn, -python3)
3. Python 3 support only    (-python, +python3 or +python3/dyn)
4. Python 2 and 3 support   (+python/dyn, +python3/dyn)

Some more details on the special case 4:

When Python 2 and Python 3 are both supported they must be loaded dynamically.

When doing this on Linux/Unix systems and importing global symbols, this leads
to a crash when the second Python version is used.  So either global symbols
are loaded but only one Python version is activated, or no global symbols are
loaded. The latter makes Python's "import" fail on libraries that expect the
symbols to be provided by Vim.
							*E836* *E837*
Vim's configuration script makes a guess for all libraries based on one
standard Python library (termios).  If importing this library succeeds for
both Python versions, then both will be made available in Vim at the same
time.  If not, only the version first used in a session will be enabled.
When trying to use the other one you will get the E836 or E837 error message.

Here Vim's behavior depends on the system in which it was configured.  In a
system where both versions of Python were configured with --enable-shared,
both versions of Python will be activated at the same time.  There will still
be problems with other third party libraries that were not linked to
libPython.

To work around such problems there are these options:
1. The problematic library is recompiled to link to the according
   libpython.so.
2. Vim is recompiled for only one Python version.
3. You undefine PY_NO_RTLD_GLOBAL in auto/config.h after configuration.  This
   may crash Vim though.

							*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 when Python 2 and 3 are both available and loaded
dynamically, these has() calls will try to load them.  If only one can be
loaded at a time, just checking if Python 2 or 3 are available will prevent
the other one from being available.

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