diff options
Diffstat (limited to 'runtime/doc/if_pyth.txt')
| -rw-r--r-- | runtime/doc/if_pyth.txt | 974 |
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: |