readline --- GNU readline 接口?

初始化文件?

下列函數(shù)與初始化文件和用戶配置有關(guān)：

readline.parse_and_bind(string)?

執(zhí)行在 string 參數(shù)中提供的初始化行。 此函數(shù)會調(diào)用底層庫中的 rl_parse_and_bind()。

readline.read_init_file([filename])?

執(zhí)行一個 readline 初始化文件。 默認文件名為最近所使用的文件名。 此函數(shù)會調(diào)用底層庫中的 rl_read_init_file()。

行緩沖區(qū)?

下列函數(shù)會在行緩沖區(qū)上操作。

readline.get_line_buffer()?

返回行緩沖區(qū)的當(dāng)前內(nèi)容 (底層庫中的 rl_line_buffer)。

readline.insert_text(string)?

將文本插入行緩沖區(qū)的當(dāng)前游標(biāo)位置。 該函數(shù)會調(diào)用底層庫中的 rl_insert_text()，但會忽略其返回值。

readline.redisplay()?

改變屏幕的顯示以反映行緩沖區(qū)的當(dāng)前內(nèi)容。 該函數(shù)會調(diào)用底層庫中的 rl_redisplay()。

歷史文件?

下列函數(shù)會在歷史文件上操作：

readline.read_history_file([filename])?

載入一個 readline 歷史文件，并將其添加到歷史列表。 默認文件名為 ~/.history。 此函數(shù)會調(diào)用底層庫中的 read_history()。

readline.write_history_file([filename])?

將歷史列表保存為 readline 歷史文件，覆蓋任何現(xiàn)有文件。 默認文件名為 ~/.history。 此函數(shù)會調(diào)用底層庫中的 write_history()。

readline.append_history_file(nelements[, filename])?

將歷史列表的最后 nelements 項添加到歷史文件。 默認文件名為 ~/.history。 文件必須已存在。 此函數(shù)會調(diào)用底層庫中的 append_history()。 此函數(shù)僅當(dāng) Python 編譯包帶有支持此功能的庫版本時才會存在。

3.5 新版功能.

readline.get_history_length()?

readline.set_history_length(length)?

設(shè)置或返回需要保存到歷史文件的行數(shù)。 write_history_file() 函數(shù)會通過調(diào)用底層庫中的 history_truncate_file() 以使用該值來截取歷史文件。 負值意味著不限制歷史文件的大小。

歷史列表?

以下函數(shù)會在全局歷史列表上操作：

readline.clear_history()?

清除當(dāng)前歷史。 此函數(shù)會調(diào)用底層庫的 clear_history()。 此 Python 函數(shù)僅當(dāng) Python 編譯包帶有支持此功能的庫版本時才會存在。

readline.get_current_history_length()?

返回歷史列表的當(dāng)前項數(shù)。 （此函數(shù)不同于 get_history_length()，后者是返回將被寫入歷史文件的最大行數(shù)。）

readline.get_history_item(index)?

返回序號為 index 的歷史條目的當(dāng)前內(nèi)容。 條目序號從一開始。 此函數(shù)會調(diào)用底層庫中的 history_get()。

readline.remove_history_item(pos)?

從歷史列表中移除指定位置上的歷史條目。 條目位置從零開始。 此函數(shù)會調(diào)用底層庫中的 remove_history()。

readline.replace_history_item(pos, line)?

將指定位置上的歷史條目替換為 line。 條目位置從零開始。 此函數(shù)會調(diào)用底層庫中的 replace_history_entry()。

readline.add_history(line)?

將 line 添加到歷史緩沖區(qū)，相當(dāng)于是最近輸入的一行。 此函數(shù)會調(diào)用底層庫中的 add_history()。

readline.set_auto_history(enabled)?

啟用或禁用當(dāng)通過 readline 讀取輸入時自動調(diào)用 add_history()。 enabled 參數(shù)應(yīng)為一個布爾值，當(dāng)其為真值時啟用自動歷史，當(dāng)其為假值時禁用自動歷史。

3.6 新版功能.

CPython implementation detail: Auto history is enabled by default, and changes to this do not persist across multiple sessions.

啟動鉤子?

readline.set_startup_hook([function])?

設(shè)置或移除底層庫的 rl_startup_hook 回調(diào)所發(fā)起調(diào)用的函數(shù)。 如果指定了 function，它將被用作新的鉤子函數(shù)；如果省略或為 None，任何已安裝的函數(shù)將被移除。 鉤子函數(shù)將在 readline 打印第一個提示信息之前不帶參數(shù)地被調(diào)用。

readline.set_pre_input_hook([function])?

設(shè)置或移除底層庫的 rl_pre_input_hook 回調(diào)所發(fā)起調(diào)用的函數(shù)。 如果指定了 function，它將被用作新的鉤子函數(shù)；如果省略或為 None，任何已安裝的函數(shù)將被移除。 鉤子函數(shù)將在打印第一個提示信息之后、readline 開始讀取輸入字符之前不帶參數(shù)地被調(diào)用。 此函數(shù)僅當(dāng) Python 編譯包帶有支持此功能的庫版本時才會存在。

Completion?

以下函數(shù)與自定義單詞補全函數(shù)的實現(xiàn)有關(guān)。 這通常使用 Tab 鍵進行操作，能夠提示并自動補全正在輸入的單詞。 默認情況下，Readline 設(shè)置為由 rlcompleter 來補全交互模式解釋器的 Python 標(biāo)識符。 如果 readline 模塊要配合自定義的補全函數(shù)來使用，則需要設(shè)置不同的單詞分隔符。

readline.set_completer([function])?

設(shè)置或移除補全函數(shù)。 如果指定了 function，它將被用作新的補全函數(shù)；如果省略或為 None，任何已安裝的補全函數(shù)將被移除。 補全函數(shù)的調(diào)用形式為 function(text, state)，其中 state 為 0, 1, 2, ..., 直至其返回一個非字符串值。 它應(yīng)當(dāng)返回下一個以 text 開頭的候選補全內(nèi)容。

已安裝的補全函數(shù)將由傳遞給底層庫中 rl_completion_matches() 的 entry_func 回調(diào)函數(shù)來發(fā)起調(diào)用。 text 字符串來自于底層庫中 rl_attempted_completion_function 回調(diào)函數(shù)的第一個形參。

readline.get_completer()?

獲取補全函數(shù)，如果沒有設(shè)置補全函數(shù)則返回 None。

readline.get_completion_type()?

獲取正在嘗試的補全類型。 此函數(shù)會將底層庫中的 rl_completion_type 變量作為一個整數(shù)返回。

readline.get_begidx()?

readline.get_endidx()?

獲取完全范圍的開始和結(jié)束索引號。 這些索引號就是傳遞給下層庫的 rl_attempted_completion_function 回調(diào)的 start 和 end 參數(shù)。 具體值在同一個輸入編輯場景中可能不同，具體取決于下層的 C readline 實現(xiàn)。 例如：已知 libedit 的行為就不同于 libreadline。

readline.set_completer_delims(string)?

readline.get_completer_delims()?

設(shè)置或獲取補全的單詞分隔符。 此分隔符確定了要考慮補全的單詞的開始和結(jié)束位置（補全域）。 這些函數(shù)會訪問底層庫的 rl_completer_word_break_characters 變量。

readline.set_completion_display_matches_hook([function])?

設(shè)置或移除補全顯示函數(shù)。 如果指定了 function，它將被用作新的補全顯示函數(shù)；如果省略或為 None，任何已安裝的補全顯示函數(shù)將被移除。 此函數(shù)會設(shè)置或清除底層庫的 rl_completion_display_matches_hook 回調(diào)函數(shù)。 補全顯示函數(shù)會在每次需要顯示匹配項時以 function(substitution, [matches], longest_match_length) 的形式被調(diào)用。

示例?

以下示例演示了如何使用 readline 模塊的歷史讀取或?qū)懭牒瘮?shù)來自動加載和保存用戶主目錄下名為 .python_history 的歷史文件。 以下代碼通常應(yīng)當(dāng)在交互會話期間從用戶的 PYTHONSTARTUP 文件自動執(zhí)行。

import atexit
import os
import readline

histfile = os.path.join(os.path.expanduser("~"), ".python_history")
try:
    readline.read_history_file(histfile)
    # default history len is -1 (infinite), which may grow unruly
    readline.set_history_length(1000)
except FileNotFoundError:
    pass

atexit.register(readline.write_history_file, histfile)

此代碼實際上會在 Python 運行于 交互模式 時自動運行 (參見 Readline 配置)。

以下示例實現(xiàn)了同樣的目標(biāo)，但是通過只添加新歷史的方式來支持并發(fā)的交互會話。

import atexit
import os
import readline
histfile = os.path.join(os.path.expanduser("~"), ".python_history")

try:
    readline.read_history_file(histfile)
    h_len = readline.get_current_history_length()
except FileNotFoundError:
    open(histfile, 'wb').close()
    h_len = 0

def save(prev_h_len, histfile):
    new_h_len = readline.get_current_history_length()
    readline.set_history_length(1000)
    readline.append_history_file(new_h_len - prev_h_len, histfile)
atexit.register(save, h_len, histfile)

以下示例擴展了 code.InteractiveConsole 類以支持歷史保存/恢復(fù)。

import atexit
import code
import os
import readline

class HistoryConsole(code.InteractiveConsole):
    def __init__(self, locals=None, filename="<console>",
                 histfile=os.path.expanduser("~/.console-history")):
        code.InteractiveConsole.__init__(self, locals, filename)
        self.init_history(histfile)

    def init_history(self, histfile):
        readline.parse_and_bind("tab: complete")
        if hasattr(readline, "read_history_file"):
            try:
                readline.read_history_file(histfile)
            except FileNotFoundError:
                pass
            atexit.register(self.save_history, histfile)

    def save_history(self, histfile):
        readline.set_history_length(1000)
        readline.write_history_file(histfile)