| *if_pyth.txt* For Vim version 7.4. Last change: 2015 Nov 10 |
| |
| |
| 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. Tab page objects |python-tabpage| |
| 7. vim.bindeval objects |python-bindeval-objects| |
| 8. pyeval(), py3eval() Vim functions |python-pyeval| |
| 9. Dynamic loading |python-dynamic| |
| 10. 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. |
| Both can be available at the same time, but read |python-2-and-3|. |
| |
| ============================================================================== |
| 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 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. |
| |
| *: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,$". |
| {not in Vi} |
| |
| 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. {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 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 |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 > |
| 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-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: > |
| :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 VimL. |
| |
| ============================================================================== |
| 9. Dynamic loading *python-dynamic* |
| |
| On MS-Windows and Unix the Python library can be loaded dynamically. The |
| |:version| output then includes |+python/dyn| or |+python3/dyn|. |
| |
| This means that Vim will search for the Python DLL or shared library file only |
| when needed. When you don't use the Python interface you don't need it, thus |
| you can use Vim without this file. |
| |
| On MS-Windows 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". |
| |
| On Unix the 'pythondll' or 'pythonthreedll' option can be used to specify the |
| Python shared library file instead of DYNAMIC_PYTHON_DLL or |
| DYNAMIC_PYTHON3_DLL file what were specified at compile time. The version of |
| the shared library must match the Python 2.x or Python 3 version Vim was |
| compiled with. |
| |
| ============================================================================== |
| 10. 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") |
| < *:py3file* |
| The `:py3file` command works similar to `:pyfile`. |
| *:py3do* *E863* |
| The `:py3do` command works similar to `:pydo`. |
| |
| |
| 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: *python-2-and-3* |
| |
| 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. |
| |
| *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 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: |