1*if_pyth.txt* For Vim version 7.3. Last change: 2010 Aug 13 2 3 4 VIM REFERENCE MANUAL by Paul Moore 5 6 7The Python Interface to Vim *python* *Python* 8 91. Commands |python-commands| 102. The vim module |python-vim| 113. Buffer objects |python-buffer| 124. Range objects |python-range| 135. Window objects |python-window| 146. Dynamic loading |python-dynamic| 157. Python 3 |python3| 16 17{Vi does not have any of these commands} 18 19The Python 2.x interface is available only when Vim was compiled with the 20|+python| feature. 21The Python 3 interface is available only when Vim was compiled with the 22|+python3| feature. 23 24============================================================================== 251. Commands *python-commands* 26 27 *:python* *:py* *E205* *E263* *E264* 28:[range]py[thon] {stmt} 29 Execute Python statement {stmt}. 30 31:[range]py[thon] << {endmarker} 32{script} 33{endmarker} 34 Execute Python script {script}. 35 Note: This command doesn't work when the Python 36 feature wasn't compiled in. To avoid errors, see 37 |script-here|. 38 39{endmarker} must NOT be preceded by any white space. If {endmarker} is 40omitted from after the "<<", a dot '.' must be used after {script}, like 41for the |:append| and |:insert| commands. 42This form of the |:python| command is mainly useful for including python code 43in Vim scripts. 44 45Example: > 46 function! IcecreamInitialize() 47 python << EOF 48 class StrawberryIcecream: 49 def __call__(self): 50 print 'EAT ME' 51 EOF 52 endfunction 53< 54Note: Python is very sensitive to the indenting. Also make sure the "class" 55line and "EOF" do not have any indent. 56 57 *:pyfile* *:pyf* 58:[range]pyf[ile] {file} 59 Execute the Python script in {file}. The whole 60 argument is used as a single file name. {not in Vi} 61 62Both of these commands do essentially the same thing - they execute a piece of 63Python code, with the "current range" |python-range| set to the given line 64range. 65 66In the case of :python, the code to execute is in the command-line. 67In the case of :pyfile, the code to execute is the contents of the given file. 68 69Python commands cannot be used in the |sandbox|. 70 71To pass arguments you need to set sys.argv[] explicitly. Example: > 72 73 :python import sys 74 :python sys.argv = ["foo", "bar"] 75 :pyfile myscript.py 76 77Here are some examples *python-examples* > 78 79 :python from vim import * 80 :python from string import upper 81 :python current.line = upper(current.line) 82 :python print "Hello" 83 :python str = current.buffer[42] 84 85(Note that changes - like the imports - persist from one command to the next, 86just like in the Python interpreter.) 87 88============================================================================== 892. The vim module *python-vim* 90 91Python code gets all of its access to vim (with one exception - see 92|python-output| below) via the "vim" module. The vim module implements two 93methods, three constants, and one error object. You need to import the vim 94module before using it: > 95 :python import vim 96 97Overview > 98 :py print "Hello" # displays a message 99 :py vim.command(cmd) # execute an Ex command 100 :py w = vim.windows[n] # gets window "n" 101 :py cw = vim.current.window # gets the current window 102 :py b = vim.buffers[n] # gets buffer "n" 103 :py cb = vim.current.buffer # gets the current buffer 104 :py w.height = lines # sets the window height 105 :py w.cursor = (row, col) # sets the window cursor position 106 :py pos = w.cursor # gets a tuple (row, col) 107 :py name = b.name # gets the buffer file name 108 :py line = b[n] # gets a line from the buffer 109 :py lines = b[n:m] # gets a list of lines 110 :py num = len(b) # gets the number of lines 111 :py b[n] = str # sets a line in the buffer 112 :py b[n:m] = [str1, str2, str3] # sets a number of lines at once 113 :py del b[n] # deletes a line 114 :py del b[n:m] # deletes a number of lines 115 116 117Methods of the "vim" module 118 119vim.command(str) *python-command* 120 Executes the vim (ex-mode) command str. Returns None. 121 Examples: > 122 :py vim.command("set tw=72") 123 :py vim.command("%s/aaa/bbb/g") 124< The following definition executes Normal mode commands: > 125 def normal(str): 126 vim.command("normal "+str) 127 # Note the use of single quotes to delimit a string containing 128 # double quotes 129 normal('"a2dd"aP') 130< *E659* 131 The ":python" command cannot be used recursively with Python 2.2 and 132 older. This only works with Python 2.3 and later: > 133 :py vim.command("python print 'Hello again Python'") 134 135vim.eval(str) *python-eval* 136 Evaluates the expression str using the vim internal expression 137 evaluator (see |expression|). Returns the expression result as: 138 - a string if the Vim expression evaluates to a string or number 139 - a list if the Vim expression evaluates to a Vim list 140 - a dictionary if the Vim expression evaluates to a Vim dictionary 141 Dictionaries and lists are recursively expanded. 142 Examples: > 143 :py text_width = vim.eval("&tw") 144 :py str = vim.eval("12+12") # NB result is a string! Use 145 # string.atoi() to convert to 146 # a number. 147 148 :py tagList = vim.eval('taglist("eval_expr")') 149< The latter will return a python list of python dicts, for instance: 150 [{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name': 151 'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}] 152 153 154 155Error object of the "vim" module 156 157vim.error *python-error* 158 Upon encountering a Vim error, Python raises an exception of type 159 vim.error. 160 Example: > 161 try: 162 vim.command("put a") 163 except vim.error: 164 # nothing in register a 165 166Constants of the "vim" module 167 168 Note that these are not actually constants - you could reassign them. 169 But this is silly, as you would then lose access to the vim objects 170 to which the variables referred. 171 172vim.buffers *python-buffers* 173 A sequence object providing access to the list of vim buffers. The 174 object supports the following operations: > 175 :py b = vim.buffers[i] # Indexing (read-only) 176 :py b in vim.buffers # Membership test 177 :py n = len(vim.buffers) # Number of elements 178 :py for b in vim.buffers: # Sequential access 179< 180vim.windows *python-windows* 181 A sequence object providing access to the list of vim windows. The 182 object supports the following operations: > 183 :py w = vim.windows[i] # Indexing (read-only) 184 :py w in vim.windows # Membership test 185 :py n = len(vim.windows) # Number of elements 186 :py for w in vim.windows: # Sequential access 187< 188vim.current *python-current* 189 An object providing access (via specific attributes) to various 190 "current" objects available in vim: 191 vim.current.line The current line (RW) String 192 vim.current.buffer The current buffer (RO) Buffer 193 vim.current.window The current window (RO) Window 194 vim.current.range The current line range (RO) Range 195 196 The last case deserves a little explanation. When the :python or 197 :pyfile command specifies a range, this range of lines becomes the 198 "current range". A range is a bit like a buffer, but with all access 199 restricted to a subset of lines. See |python-range| for more details. 200 201 202Output from Python *python-output* 203 Vim displays all Python code output in the Vim message area. Normal 204 output appears as information messages, and error output appears as 205 error messages. 206 207 In implementation terms, this means that all output to sys.stdout 208 (including the output from print statements) appears as information 209 messages, and all output to sys.stderr (including error tracebacks) 210 appears as error messages. 211 212 *python-input* 213 Input (via sys.stdin, including input() and raw_input()) is not 214 supported, and may cause the program to crash. This should probably be 215 fixed. 216 217============================================================================== 2183. Buffer objects *python-buffer* 219 220Buffer objects represent vim buffers. You can obtain them in a number of ways: 221 - via vim.current.buffer (|python-current|) 222 - from indexing vim.buffers (|python-buffers|) 223 - from the "buffer" attribute of a window (|python-window|) 224 225Buffer objects have one read-only attribute - name - the full file name for 226the buffer. They also have three methods (append, mark, and range; see below). 227 228You can also treat buffer objects as sequence objects. In this context, they 229act as if they were lists (yes, they are mutable) of strings, with each 230element being a line of the buffer. All of the usual sequence operations, 231including indexing, index assignment, slicing and slice assignment, work as 232you would expect. Note that the result of indexing (slicing) a buffer is a 233string (list of strings). This has one unusual consequence - b[:] is different 234from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas 235"b = None" merely updates the variable b, with no effect on the buffer. 236 237Buffer indexes start at zero, as is normal in Python. This differs from vim 238line numbers, which start from 1. This is particularly relevant when dealing 239with marks (see below) which use vim line numbers. 240 241The buffer object methods are: 242 b.append(str) Append a line to the buffer 243 b.append(str, nr) Idem, below line "nr" 244 b.append(list) Append a list of lines to the buffer 245 Note that the option of supplying a list of strings to 246 the append method differs from the equivalent method 247 for Python's built-in list objects. 248 b.append(list, nr) Idem, below line "nr" 249 b.mark(name) Return a tuple (row,col) representing the position 250 of the named mark (can also get the []"<> marks) 251 b.range(s,e) Return a range object (see |python-range|) which 252 represents the part of the given buffer between line 253 numbers s and e |inclusive|. 254 255Note that when adding a line it must not contain a line break character '\n'. 256A trailing '\n' is allowed and ignored, so that you can do: > 257 :py b.append(f.readlines()) 258 259Examples (assume b is the current buffer) > 260 :py print b.name # write the buffer file name 261 :py b[0] = "hello!!!" # replace the top line 262 :py b[:] = None # delete the whole buffer 263 :py del b[:] # delete the whole buffer 264 :py b[0:0] = [ "a line" ] # add a line at the top 265 :py del b[2] # delete a line (the third) 266 :py b.append("bottom") # add a line at the bottom 267 :py n = len(b) # number of lines 268 :py (row,col) = b.mark('a') # named mark 269 :py r = b.range(1,5) # a sub-range of the buffer 270 271============================================================================== 2724. Range objects *python-range* 273 274Range objects represent a part of a vim buffer. You can obtain them in a 275number of ways: 276 - via vim.current.range (|python-current|) 277 - from a buffer's range() method (|python-buffer|) 278 279A range object is almost identical in operation to a buffer object. However, 280all operations are restricted to the lines within the range (this line range 281can, of course, change as a result of slice assignments, line deletions, or 282the range.append() method). 283 284The range object attributes are: 285 r.start Index of first line into the buffer 286 r.end Index of last line into the buffer 287 288The range object methods are: 289 r.append(str) Append a line to the range 290 r.append(str, nr) Idem, after line "nr" 291 r.append(list) Append a list of lines to the range 292 Note that the option of supplying a list of strings to 293 the append method differs from the equivalent method 294 for Python's built-in list objects. 295 r.append(list, nr) Idem, after line "nr" 296 297Example (assume r is the current range): 298 # Send all lines in a range to the default printer 299 vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1)) 300 301============================================================================== 3025. Window objects *python-window* 303 304Window objects represent vim windows. You can obtain them in a number of ways: 305 - via vim.current.window (|python-current|) 306 - from indexing vim.windows (|python-windows|) 307 308You can manipulate window objects only through their attributes. They have no 309methods, and no sequence or other interface. 310 311Window attributes are: 312 buffer (read-only) The buffer displayed in this window 313 cursor (read-write) The current cursor position in the window 314 This is a tuple, (row,col). 315 height (read-write) The window height, in rows 316 width (read-write) The window width, in columns 317The height attribute is writable only if the screen is split horizontally. 318The width attribute is writable only if the screen is split vertically. 319 320============================================================================== 3216. Dynamic loading *python-dynamic* 322 323On MS-Windows the Python library can be loaded dynamically. The |:version| 324output then includes |+python/dyn|. 325 326This means that Vim will search for the Python DLL file only when needed. 327When you don't use the Python interface you don't need it, thus you can use 328Vim without this DLL file. 329 330To use the Python interface the Python DLL must be in your search path. In a 331console window type "path" to see what directories are used. 332 333The name of the DLL must match the Python version Vim was compiled with. 334Currently the name is "python24.dll". That is for Python 2.4. To know for 335sure edit "gvim.exe" and search for "python\d*.dll\c". 336 337============================================================================== 3387. Python 3 *python3* 339 340 *:py3* *:python3* 341The |:py3| and |:python3| commands work similar to |:python|. 342 *:py3file* 343The |:py3file| command works similar to |:pyfile|. 344 345Vim can be built in four ways (:version output): 3461. No Python support (-python, -python3) 3472. Python 2 support only (+python or +python/dyn, -python3) 3483. Python 3 support only (-python, +python3 or +python3/dyn) 3494. Python 2 and 3 support (+python/dyn, +python3/dyn) 350 351Some more details on the special case 4: 352 353When Python 2 and Python 3 are both supported they must be loaded dynamically. 354 355When doing this on Linux/Unix systems and importing global symbols, this leads 356to a crash when the second Python version is used. So either global symbols 357are loaded but only one Python version is activated, or no global symbols are 358loaded. The latter makes Python's "import" fail on libaries that expect the 359symbols to be provided by Vim. 360 *E836* *E837* 361Vim's configuration script makes a guess for all libraries based on one 362standard Python library (termios). If importing this library succeeds for 363both Python versions, then both will be made available in Vim at the same 364time. If not, only the version first used in a session will be enabled. 365When trying to use the other one you will get the E836 or E837 error message. 366 367Here Vim's behavior depends on the system in which it was configured. In a 368system where both versions of Python were configured with --enable-shared, 369both versions of Python will be activated at the same time. There will still 370be problems with other third party libraries that were not linked to 371libPython. 372 373To work around such problems there are these options: 3741. The problematic library is recompiled to link to the according 375 libpython.so. 3762. Vim is recompiled for only one Python version. 3773. You undefine PY_NO_RTLD_GLOBAL in auto/config.h after configuration. This 378 may crash Vim though. 379 380 381============================================================================== 382 vim:tw=78:ts=8:ft=help:norl: 383