*if_pyth.txt*   Nvim


		  NVIM REFERENCE MANUAL


The Python Interface to NVim				*if_pyth* *python* *Python*

See |provider-python| for more information.

                                      Type |gO| to see the table of contents.

==============================================================================
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: >vim
				:python print("Hello")

:[range]py[thon] << [trim] [{endmarker}]
{script}
{endmarker}
			Execute Python script {script}.  Useful for including
			python code in Vim scripts.  Requires Python, 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.

Example: >vim
	function! IcecreamInitialize()
	python << EOF
	class StrawberryIcecream:
		def __call__(self):
			print('EAT ME')
	EOF
	endfunction

To see what version of Python you have: >vim
	: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 build.  Also see
https://docs.python.org/3/library/os.html#os.environ

Note: Python is very sensitive to 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:
>vim
	: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: >vim

	: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: >vim

	:python sys.argv = ["foo", "bar"]
	:pyfile myscript.py

Here are some examples					*python-examples*
>vim
	:python from vim import *
	:python current.line = str.upper(current.line)
	:python print("Hello")
	:python str = current.buffer[42]

Note that changes (such as the "import" statements) persist from one command
to the next, just like the Python REPL.

							*script-here*
When using a script language in-line, you might want to skip this when the
language isn't supported.
>vim
   if has('python')
     python << EOF
       print("python works")
   EOF
   endif
<
Note that "EOF" must be at the start of the line without preceding white
space.

==============================================================================
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: >vim
	:python import vim

Overview >vim