If_pyth

Nvim 的 :help 頁面, 原始碼 使用 tree-sitter-vimdoc 解析器產生


NVim 的 Python 介面 python Python
請參閱 provider-python 以獲取更多資訊。
:python :py E263 E264 E887 :[range]py[thon] {stmt} 執行 Python 陳述式 {stmt}。一個簡單的檢查 :python 指令是否正常運作
:python print("Hello")
:[range]py[thon] << [trim] [{endmarker}] {script} {endmarker} 執行 Python 腳本 {script}。對於在 Vim 腳本中包含 python 程式碼很有用。需要 Python,請參閱 script-here
如果從 "<<" 之後省略 [endmarker],則必須在 {script} 之後使用點 '.',類似於 :append:insert 指令。請參閱 :let-heredoc 以獲取更多資訊。
範例
function! IcecreamInitialize()
python << EOF
class StrawberryIcecream:
        def __call__(self):
                print('EAT ME')
EOF
endfunction
查看你擁有的 Python 版本
:python print(sys.version)
不需要 "import sys",它是預設完成的。
python-環境
在 Vim 中設定的環境變數並不總是可在 Python 中使用。這取決於 Vim 和 Python 的建置方式。另請參閱 https://docs.python.org/3/library/os.html#os.environ
注意:Python 對縮排非常敏感。請確保 "class" 行和 "EOF" 沒有任何縮排。
:pydo
:[range]pydo {body} 針對 [range] 中的每一行,執行 Python 函式 "def _vim_pydo(line, linenr): {body}",該函式參數設定為每一行的文字,不包含尾隨的 <EOL>,以及目前的行號。函式應返回一個字串或 None。如果返回字串,則會成為目前回合中該行的文字。[range] 的預設值是整個檔案:"1,$"。
範例
:pydo return "%s\t%d" % (line[::-1], len(line))
:pydo if line: return "%4d: %s" % (linenr, line)
可以將 :pydo:py 結合使用,以使用 python 過濾範圍。例如
: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} 執行 {file} 中的 Python 腳本。整個參數用作單一檔案名稱。
這兩個指令的本質相同 - 它們執行一段 Python 程式碼,其中「目前範圍」python-range 設定為給定的行範圍。
在 :python 的情況下,要執行的程式碼在命令列中。在 :pyfile 的情況下,要執行的程式碼是給定檔案的內容。
Python 指令不能在 沙箱中使用。
若要傳遞參數,您需要明確設定 sys.argv[]。範例
:python sys.argv = ["foo", "bar"]
:pyfile myscript.py
以下是一些範例 python-examples
:python from vim import *
:python current.line = str.upper(current.line)
:python print("Hello")
:python str = current.buffer[42]
請注意,變更 (例如 "import" 陳述式) 會從一個指令持續到下一個指令,就像 Python REPL 一樣。
script-here
當內嵌使用腳本語言時,如果該語言不受支援,您可能想要跳過此步驟。
if has('python')
  python << EOF
    print("python works")
EOF
endif
請注意,"EOF" 必須位於行首,且前面沒有空格。

vim 模組 python-vim

Python 程式碼透過 "vim" 模組取得對 vim 的所有存取權 (有一個例外 - 請參閱下方的 python-output)。vim 模組實作了兩個方法、三個常數和一個錯誤物件。您必須在使用之前匯入 vim 模組
:python import vim
概述
: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
"vim" 模組的方法
vim.command(str) python-command
執行 vim (ex-mode) 指令 str。傳回 None。範例
:py vim.command("set tw=72")
:py vim.command("%s/aaa/bbb/g")
以下定義執行 Normal 模式指令
def normal(str):
        vim.command("normal "+str)
# Note the use of single quotes to delimit a string containing
# double quotes
normal('"a2dd"aP')
vim.eval(str) python-eval
使用 vim 內部運算式評估器 (請參閱 expression) 評估運算式 str。將運算式結果傳回為
如果 Vim 運算式評估為字串或數字,則為字串
如果 Vim 運算式評估為 Vim 清單,則為清單
如果 Vim 運算式評估為 Vim 字典,則為字典。字典和清單會以遞迴方式展開。範例
:py text_width = vim.eval("&tw")
:py str = vim.eval("12+12")                # NB result is a string! Use
                                    # int() to convert to a
                                    # number.
vim.strwidth(str) python-strwidth
類似 strwidth():傳回 str 佔用的顯示儲存格數量,tab 算作一個儲存格。
vim.foreach_rtp(callable) python-foreach_rtp
針對 'runtimepath' 中的每個路徑,呼叫給定的可呼叫物件,直到可呼叫物件傳回非 None 的值、引發例外狀況或不再有路徑。如果因為可呼叫物件傳回非 None 的值而停止,則 vim.foreach_rtp 函式會傳回可呼叫物件傳回的值。
vim.chdir(*args, **kwargs) python-chdir
vim.fchdir(*args, **kwargs) python-fchdir
執行 os.chdir 或 os.fchdir,然後執行所有適當的 vim 項目。注意:您不應直接使用這些函式,而應使用 os.chdir 和 os.fchdir。如果 os.fchdir 不存在,則 vim.fchdir 的行為未定義。
"vim" 模組的錯誤物件
vim.error python-error
在遇到 Vim 錯誤時,Python 會引發 vim.error 類型的例外狀況。範例
try:
        vim.command("put a")
except vim.error:
        # nothing in register a
"vim" 模組的常數
請注意,這些實際上不是常數 - 您可以重新指派它們。但這很愚蠢,因為這樣您會失去對變數所參照的 vim 物件的存取權。
vim.buffers python-buffers
提供對 vim 緩衝區清單存取的對應物件。該物件支援以下操作
: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
提供對 vim 視窗清單存取的序列物件。該物件支援以下操作
: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
注意:vim.windows 物件始終存取目前的索引標籤頁面。python-tabpage。windows 物件會繫結至父 python-tabpage 物件,且始終使用該索引標籤頁面的視窗 (如果索引標籤頁面已刪除,則會擲回 vim.error)。您可以保留兩者的參考,而無需保留對 vim 模組物件或 python-tabpage 的參考,它們在此情況下不會失去其屬性。
vim.tabpages python-tabpages
提供對 vim 索引標籤頁面清單存取的序列物件。該物件支援以下操作
: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
一個提供 (透過特定屬性) 對 vim 中各種「目前」物件存取的物件:vim.current.line 目前行 (RW) 字串 vim.current.buffer 目前緩衝區 (RW) 緩衝區 vim.current.window 目前視窗 (RW) 視窗 vim.current.tabpage 目前索引標籤頁面 (RW) 索引標籤頁面 vim.current.range 目前行範圍 (RO) 範圍
最後一個案例值得稍作解釋。當 :python 或 :pyfile 指令指定範圍時,此行範圍會成為「目前範圍」。範圍有點像緩衝區,但所有存取權都限制為行的子集。有關更多詳細資訊,請參閱 python-range
注意:當指派給 vim.current.{buffer,window,tabpage} 時,它會分別預期有效的 python-bufferpython-windowpython-tabpage 物件。指派會觸發正常 (使用 autocommand) 切換至給定的緩衝區、視窗或索引標籤頁面。這是唯一在 python 中切換 UI 物件的方式:您無法指派給 python-tabpage.window 屬性。若要在不觸發 autocommand 的情況下切換,請使用
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
類似字典的物件,其中包含全域 (g:) 和 vim (v:) 變數的字典。
vim.options python-options
部分支援對應協定的物件 (支援設定和取得項目),提供對全域選項的讀寫存取權。注意::set 不同,這僅提供對全域選項的存取權。您無法使用此物件來取得或設定本機選項的值,或以任何方式存取本機專用選項。如果不存在具有此名稱的全域選項,則會引發 KeyError (也就是說,不會對 全域本機選項和僅限全域選項引發 KeyError,但會對視窗和緩衝區本機選項引發 KeyError)。請使用 python-buffer 物件來存取緩衝區本機選項,並使用 python-window 物件來存取視窗本機選項。
此物件的類型可透過 vim 模組的 "Options" 屬性取得。
Python 的輸出 python-output
Vim 會在 Vim 訊息區域中顯示所有 Python 程式碼輸出。正常輸出顯示為資訊訊息,而錯誤輸出顯示為錯誤訊息。
在實作方面,這表示所有傳送到 sys.stdout 的輸出 (包括 print 陳述式的輸出) 都會顯示為資訊訊息,而所有傳送到 sys.stderr 的輸出 (包括錯誤追溯) 都會顯示為錯誤訊息。
python-輸入
不支援輸入 (透過 sys.stdin,包括 input() 和 raw_input()),且可能會導致程式當機。這可能應該修復。
在 python 中,vim.VIM_SPECIAL_PATH 特殊目錄用來取代 'runtimepath' 中找到的路徑清單:將此目錄放在 sys.path 和 vim.path_hooks 中,python 會嘗試從 {rtp}/python3 和 {rtp}/pythonx 載入模組,針對 'runtimepath' 中找到的每個 {rtp}
實作類似於以下內容,但以 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
與 vim 路徑 hook 搭配使用的字串常數。如果 vim 安裝的路徑 hook 要求處理除等於 vim.VIM_SPECIAL_PATH 常數的路徑之外的任何項目,則會引發 ImportError。在唯一其他情況下,它會使用特殊載入器。
注意:您不得直接使用此常數的值,而應始終使用 vim.VIM_SPECIAL_PATH 物件。
vim.find_module(...) python-find_module
vim.path_hook(path) python-path_hook
用來實作如上所述路徑載入的方法或物件。除非您需要使用 sys.meta_path 執行某些操作,否則您不應直接使用這些方法或物件中的任何一個。不保證未來 vim 版本中會存在任何物件。
vim._get_paths python-_get_paths
傳回路徑清單的方法,路徑 hook 會搜尋這些路徑。您不應依賴此方法在未來版本中存在,但可以將其用於偵錯。
它會針對 'runtimepath' 中的每個 {rtp},傳回 {rtp}/python3 和 {rtp}/pythonx 目錄的清單。

緩衝區物件 python-buffer

緩衝區物件代表 vim 緩衝區。您可以使用多種方式取得它們
透過 vim.current.buffer (python-current)
從索引 vim.buffers (python-buffers) 取得
從視窗的 "buffer" 屬性 (python-window) 取得
Buffer 物件有兩個唯讀屬性 - name (緩衝區的完整檔案名稱) 和 number (緩衝區編號)。它們也有三個方法 (append、mark 和 range;見下方)。
您也可以將 Buffer 物件視為序列物件。在此情況下,它們的作用就像是字串列表 (是的,它們是可變的),每個元素都是緩衝區的一行。所有常見的序列操作,包括索引、索引賦值、切片和切片賦值,都如您所預期地運作。請注意,索引 (切片) 緩衝區的結果是一個字串 (字串列表)。這有一個不尋常的結果 - b[:] 與 b 不同。特別是,"b[:] = None" 會刪除整個緩衝區,而 "b = None" 只會更新變數 b,對緩衝區沒有任何影響。
Buffer 索引從零開始,這在 Python 中是正常的。這與從 1 開始的 vim 行號不同。這在處理使用 vim 行號的標記 (見下方) 時尤其相關。
Buffer 物件屬性如下:b.vars 類似字典的物件,用於存取 緩衝區變數。b.options 映射物件 (支援項目取得、設定和刪除),提供對緩衝區本機選項和 全域-本機 選項的緩衝區本機值的存取。如果選項是視窗本機的,請使用 python-window.options,此物件將引發 KeyError。如果選項是 全域-本機,並且本機值遺失,則取得它將返回 None。b.name 字串,RW。包含緩衝區名稱 (完整路徑)。注意:當賦值給 b.name 時,會啟動 BufFilePreBufFilePost 自動指令。b.number 緩衝區編號。可以用作 python-buffers 鍵。唯讀。b.valid True 或 False。當對應的緩衝區被清除時,緩衝區物件將失效。
Buffer 物件的方法如下:b.append(str) 在緩衝區中附加一行 b.append(str, nr) 同上,在「nr」行下方 b.append(list) 在緩衝區中附加一個行列表 請注意,向 append 方法提供字串列表的選項與 Python 內建物件列表的等效方法不同。b.append(list, nr) 同上,在「nr」行下方 b.mark(name) 返回一個元組 (row,col),表示命名標記的位置 (也可以取得 []"<> 標記) b.range(s,e) 返回一個範圍物件 (請參閱 python-range),表示給定緩衝區中行號 s 和 e 之間的包含部分。
請注意,當新增一行時,它不能包含換行符 '\n'。允許並忽略尾隨的 '\n',因此您可以執行
:py b.append(f.readlines())
可以使用 vim 模組的 "Buffer" 屬性來取得 Buffer 物件類型。
範例 (假設 b 是目前的緩衝區)
: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<

範圍物件 python-range

範圍物件表示 vim 緩衝區的一部分。您可以透過多種方式取得它們
透過 vim.current.range (python-current)
從緩衝區的 range() 方法 (python-buffer)
範圍物件在操作上幾乎與緩衝區物件相同。但是,所有操作都限制在範圍內的行 (當然,此行範圍可能會由於切片賦值、行刪除或 range.append() 方法而變更)。
範圍物件的屬性如下:r.start 緩衝區中第一行的索引 r.end 緩衝區中最後一行的索引
範圍物件的方法如下:r.append(str) 在範圍中附加一行 r.append(str, nr) 同上,在「nr」行之後 r.append(list) 在範圍中附加一個行列表 請注意,向 append 方法提供字串列表的選項與 Python 內建物件列表的等效方法不同。r.append(list, nr) 同上,在「nr」行之後
可以使用 vim 模組的 "Range" 屬性來取得範圍物件類型。
範例 (假設 r 是目前的範圍): # 將範圍內的所有行傳送到預設印表機 vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))

視窗物件 python-window

視窗物件表示 vim 視窗。您可以透過多種方式取得它們
透過 vim.current.window (python-current)
從索引 vim.windows (python-windows) 取得
從索引分頁的 "windows" 屬性 (python-tabpage) 取得
從分頁的 "window" 屬性 (python-tabpage) 取得
您只能透過視窗物件的屬性來操作它們。它們沒有方法,也沒有序列或其他介面。
視窗屬性如下:buffer (唯讀) 此視窗中顯示的緩衝區 cursor (讀寫) 視窗中的目前游標位置 這是一個元組 (row,col)。height (讀寫) 視窗高度,以行為單位 width (讀寫) 視窗寬度,以列為單位 vars (唯讀) 視窗的 w: 變數。屬性不可賦值,但您可以透過這種方式變更視窗變數 options (唯讀) 視窗本機選項。屬性不可賦值,但您可以透過這種方式變更視窗選項。僅提供對視窗本機選項的存取權,對於緩衝區本機使用 python-buffer,對於全域選項則使用 python-options。如果選項是 全域-本機,並且本機值遺失,則取得它將返回 None。number (唯讀) 視窗編號。第一個視窗的編號為 1。如果無法確定,則為零 (例如,當視窗物件屬於其他分頁時)。row、col (唯讀) 在顯示儲存格中的螢幕視窗位置。第一個位置為零。tabpage (唯讀) 視窗分頁。valid (讀寫) True 或 False。當關閉對應的視窗時,視窗物件將失效。
只有當螢幕水平分割時,height 屬性才可寫入。只有當螢幕垂直分割時,width 屬性才可寫入。
可以使用 vim 模組的 "Window" 屬性來取得視窗物件類型。

分頁物件 python-tabpage

分頁物件表示 vim 分頁。您可以透過多種方式取得它們
透過 vim.current.tabpage (python-current)
從索引 vim.tabpages (python-tabpages) 取得
您可以使用此物件來存取分頁視窗。它們沒有方法,也沒有序列或其他介面。
分頁屬性如下:number 分頁編號,如 tabpagenr() 返回的編號。windows 類似於 python-windows,但用於目前的分頁。vars 分頁的 t: 變數。window 目前分頁視窗。valid True 或 False。當關閉對應的分頁時,分頁物件將失效。
可以使用 vim 模組的 "TabPage" 屬性來取得 TabPage 物件類型。

pyeval() 和 py3eval() Vim 函數 python-pyeval

為了方便雙向介面,您可以使用 pyeval()py3eval() 函數來評估 Python 表達式並將它們的值傳遞給 Vim 腳本。pyxeval() 也可用。

Python 3 python3

由於 Python 3 是 Nvim 中唯一支援的版本,因此在目前版本中,"python" 與 "python3" 同義。但是,旨在支援較舊版本 Nvim 以及 Vim 的程式碼,如果需要 Python 3,應優先明確使用 "python3" 變體。
:py3 :python3 :[範圍]py3 {stmt} :[範圍]py3 << [trim] [{endmarker}] {script} {endmarker}
:[範圍]python3 {stmt} :[範圍]python3 << [trim] [{endmarker}] {script} {endmarker} :py3:python3 命令的工作方式類似於 :python。簡單檢查 :py3 命令是否正在運作
:py3 print("Hello")
查看你擁有的 Python 版本
:py3 import sys
:py3 print(sys.version)
:py3file
:[範圍]py3f[ile] {file} :py3file 命令的工作方式類似於 :pyfile:py3do
:[範圍]py3do {body} :py3do 命令的工作方式類似於 :pydo
E880
在 python 中引發 SystemExit 例外狀況並不是結束 vim 的推薦方式,請使用
:py vim.command("qall!")
has-python
您可以使用以下命令測試 Python 是否可用
if has('pythonx')
  echo 'there is Python'
endif
if has('python3')
  echo 'there is Python 3.x'
endif
不再支援 Python 2。因此,has('python') 為了向後相容性,始終返回零。

Python X python_x pythonx

引入 "pythonx" 和 "pyx" 前置詞,用於適用於 Python 2.6+ 和 Python 3 的 python 程式碼。由於 Nvim 僅支援 Python 3,因此所有這些命令現在都與它們的 "python3" 等效命令同義。
:pyx :pythonx :pyx:pythonx 的工作方式與 :python3 相同。檢查 :pyx 是否運作
:pyx print("Hello")
查看正在使用的 Python 版本
:pyx import sys
:pyx print(sys.version)
:pyxfile python_x-special-comments :pyxfile 的工作方式與 :py3file 相同。
:pyxdo
:pyxdo 的工作方式與 :py3do 相同。
has-pythonx
檢查 pyx* 函數和命令是否可用
if has('pythonx')
  echo 'pyx* commands are available. (Python ' .. &pyx .. ')'
endif
主要
命令索引
快速參考