summaryrefslogtreecommitdiffstats
path: root/runtime/doc/if_pyth.txt
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--runtime/doc/if_pyth.txt974
1 files changed, 974 insertions, 0 deletions
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
new file mode 100644
index 0000000..c2a0094
--- /dev/null
+++ b/runtime/doc/if_pyth.txt
@@ -0,0 +1,974 @@
+*if_pyth.txt* For Vim version 9.0. Last change: 2022 Feb 22
+
+
+ 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|
+11. Python X |python_x|
+12. Building with Python support |python-building|
+
+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|.
+
+NOTE: Python 2 is old and no longer being developed. Using Python 3 is highly
+recommended. Python 2 support will be dropped when it does not work properly
+anymore.
+
+==============================================================================
+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] << [trim] [{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|.
+
+If [endmarker] is omitted from after the "<<", a dot '.' must be used after
+{script}, like for the |:append| and |:insert| commands. Refer to
+|:let-heredoc| for more information.
+
+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 print(sys.version)
+
+There is no need to import sys, it's done by default.
+
+ *python-environment*
+Environment variables set in Vim are not always available in Python. This
+depends on how Vim and Python were built. Also see
+https://docs.python.org/3/library/os.html#os.environ
+
+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)
+<
+One can use `:pydo` in possible conjunction with `:py` to filter a range using
+python. For example: >
+
+ :py3 << EOF
+ needle = vim.eval('@a')
+ replacement = vim.eval('@b')
+
+ def py_vim_string_replace(str):
+ return str.replace(needle, replacement)
+ EOF
+ :'<,'>py3do return py_vim_string_replace(line)
+<
+ *:pyfile* *:pyf*
+:[range]pyf[ile] {file}
+ Execute the Python script in {file}. The whole
+ argument is used as a single file name.
+
+Both of these commands do essentially the same thing - they execute a piece of
+Python code, with the "current range" |python-range| set to the given line
+range.
+
+In the case of :python, the code to execute is in the command-line.
+In the case of :pyfile, the code to execute is the contents of the given file.
+
+Python commands cannot be used in the |sandbox|.
+
+To pass arguments you need to set sys.argv[] explicitly. Example: >
+
+ :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: >
+ :" value of the 'textwidth' option
+ :py text_width = vim.eval("&tw")
+ :
+ :" contents of the 'a' register
+ :py a_reg = vim.eval("@a")
+ :
+ :" Result is a string! Use string.atoi() to convert to a number.
+ :py str = vim.eval("12+12")
+ :
+ :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. 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))`.
+
+ Attributes (read-only):
+ Attribute Description ~
+ name Function name.
+ args `None` or a |python-List| object with arguments. Note
+ that this is a copy of the arguments list, constructed
+ each time you request this attribute. Modifications made
+ to the list will be ignored (but not to the containers
+ inside argument list: this is like |copy()| and not
+ |deepcopy()|).
+ self `None` or a |python-Dictionary| object with self
+ dictionary. Note that explicit `self` keyword used when
+ calling resulting object overrides this attribute.
+ auto_rebind Boolean. True if partial created from this Python object
+ and stored in the Vim script dictionary should be
+ automatically rebound to the dictionary it is stored in
+ when this dictionary is indexed. Exposes Vim internal
+ difference between `dict.func` (auto_rebind=True) and
+ `function(dict.func,dict)` (auto_rebind=False). This
+ attribute makes no sense if `self` attribute is `None`.
+
+ Constructor additionally accepts `args`, `self` and `auto_rebind`
+ keywords. If `args` and/or `self` argument is given then it constructs
+ a partial, see |function()|. `auto_rebind` is only used when `self`
+ argument is given, otherwise it is assumed to be `True` regardless of
+ whether it was given or not. If `self` is given then it defaults to
+ `False`.
+
+ 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
+
+ p = vim.Function('DictFun', self={})
+ print f()
+ p = vim.Function('tr', args=['abc', 'a'])
+ print f('b')
+
+==============================================================================
+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.
+|pyxeval()| is also available.
+
+The Python value "None" is converted to v:none.
+
+==============================================================================
+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.
+
+
+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 'pythondll'
+or 'pythonthreedll' option can be also used to specify the Python DLL.
+
+The name of the DLL should match the Python version Vim was compiled with.
+Currently the name for Python 2 is "python27.dll", that is for Python 2.7.
+That is the default value for 'pythondll'. For Python 3 it is python36.dll
+(Python 3.6). To know for sure edit "gvim.exe" and search for
+"python\d*.dll\c".
+
+
+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*
+:[range]py3 {stmt}
+:[range]py3 << [trim] [{endmarker}]
+{script}
+{endmarker}
+
+:[range]python3 {stmt}
+:[range]python3 << [trim] [{endmarker}]
+{script}
+{endmarker}
+ The `:py3` and `:python3` commands work similar to `:python`. A
+ simple check if the `:py3` command is working: >
+ :py3 print("Hello")
+<
+ To see what version of Python you have: >
+ :py3 import sys
+ :py3 print(sys.version)
+< *:py3file*
+:[range]py3f[ile] {file}
+ The `:py3file` command works similar to `:pyfile`.
+ *:py3do*
+:[range]py3do {body}
+ The `:py3do` command works similar to `:pydo`.
+
+
+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!")
+<
+ *E1266*
+This error can occur when Python 3 cannot load the required modules. This
+means that your Python 3 is not correctly installed or there are some mistakes
+in your settings. Please check the following items:
+1. Make sure that Python 3 is correctly installed. Also check the version of
+ python.
+2. Check the 'pythonthreedll' option.
+3. Check the 'pythonthreehome' option.
+4. Check the PATH environment variable if you don't set 'pythonthreedll'.
+ On MS-Windows, you can use where.exe to check which dll will be loaded.
+ E.g. >
+ where.exe python310.dll
+5. Check the PYTHONPATH and PYTHONHOME environment variables.
+
+ *has-python*
+You can test what Python version is available with: >
+ if has('python')
+ echo 'there is Python 2.x'
+ endif
+ if 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.
+
+To avoid loading the dynamic library, only check if Vim was compiled with
+python support: >
+ if has('python_compiled')
+ echo 'compiled with Python 2.x support'
+ if has('python_dynamic')
+ echo 'Python 2.x dynamically loaded'
+ endif
+ endif
+ if has('python3_compiled')
+ echo 'compiled with Python 3.x support'
+ if has('python3_dynamic')
+ echo 'Python 3.x dynamically loaded'
+ endif
+ endif
+
+This also tells you whether Python is dynamically loaded, which will fail if
+the runtime library cannot be found.
+
+==============================================================================
+11. Python X *python_x* *pythonx*
+
+Because most python code can be written so that it works with Python 2.6+ and
+Python 3 the pyx* functions and commands have been written. They work exactly
+the same as the Python 2 and 3 variants, but select the Python version using
+the 'pyxversion' setting.
+
+You should set 'pyxversion' in your |.vimrc| to prefer Python 2 or Python 3
+for Python commands. If you change this setting at runtime you may risk that
+state of plugins (such as initialization) may be lost.
+
+If you want to use a module, you can put it in the {rtp}/pythonx directory.
+See |pythonx-directory|.
+
+ *:pyx* *:pythonx*
+The `:pyx` and `:pythonx` commands work similar to `:python`. A simple check
+if the `:pyx` command is working: >
+ :pyx print("Hello")
+
+To see what version of Python is being used: >
+ :pyx import sys
+ :pyx print(sys.version)
+<
+ *:pyxfile* *python_x-special-comments*
+The `:pyxfile` command works similar to `:pyfile`. However you can add one of
+these comments to force Vim using `:pyfile` or `:py3file`: >
+ #!/any string/python2 " Shebang. Must be the first line of the file.
+ #!/any string/python3 " Shebang. Must be the first line of the file.
+ # requires python 2.x " Maximum lines depend on 'modelines'.
+ # requires python 3.x " Maximum lines depend on 'modelines'.
+Unlike normal modelines, the bottom of the file is not checked.
+If none of them are found, the 'pyxversion' setting is used.
+ *W20* *W21*
+If Vim does not support the selected Python version a silent message will be
+printed. Use `:messages` to read them.
+
+ *:pyxdo*
+The `:pyxdo` command works similar to `:pydo`.
+
+ *has-pythonx*
+You can test if pyx* commands are available with: >
+ if has('pythonx')
+ echo 'pyx* commands are available. (Python ' .. &pyx .. ')'
+ endif
+
+When compiled with only one of |+python| or |+python3|, the has() returns 1.
+When compiled with both |+python| and |+python3|, the test depends on the
+'pyxversion' setting. If 'pyxversion' is 0, it tests Python 3 first, and if
+it is not available then Python 2. If 'pyxversion' is 2 or 3, it tests only
+Python 2 or 3 respectively.
+
+Note that for `has('pythonx')` to work it may try to dynamically load Python 3
+or 2. This may have side effects, especially when Vim can only load one of
+the two.
+
+If a user prefers Python 2 and want to fallback to Python 3, he needs to set
+'pyxversion' explicitly in his |.vimrc|. E.g.: >
+ if has('python')
+ set pyx=2
+ elseif has('python3')
+ set pyx=3
+ endif
+
+==============================================================================
+12. Building with Python support *python-building*
+
+A few hints for building with Python 2 or 3 support.
+
+UNIX
+
+See src/Makefile for how to enable including the Python interface.
+
+On Ubuntu you will want to install these packages for Python 2:
+ python
+ python-dev
+For Python 3:
+ python3
+ python3-dev
+For Python 3.6:
+ python3.6
+ python3.6-dev
+
+If you have more than one version of Python 3, you need to link python3 to the
+one you prefer, before running configure.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: