readline --- giao diện đọc GNU

---

Mô-đun readline xác định một số chức năng để tạo điều kiện thuận lợi cho việc hoàn thành và đọc/ghi các tệp lịch sử từ trình thông dịch Python. Mô-đun này có thể được sử dụng trực tiếp hoặc thông qua mô-đun rlcompleter, hỗ trợ hoàn thành mã định danh Python tại dấu nhắc tương tác. Các cài đặt được thực hiện bằng mô-đun này sẽ ảnh hưởng đến hành vi của cả lời nhắc tương tác của trình thông dịch và lời nhắc do chức năng input() tích hợp sẵn cung cấp.

Các liên kết phím của dòng đọc có thể được định cấu hình thông qua tệp khởi tạo, thường là .inputrc trong thư mục chính của bạn. Xem Readline Init File trong hướng dẫn sử dụng GNU Readline để biết thông tin về định dạng và cấu trúc được phép của tệp đó cũng như các khả năng của thư viện Readline nói chung.

sẵn có: not Android, not iOS, not WASI.

Mô-đun này không được hỗ trợ trên mobile platforms hoặc WebAssembly platforms.

Đây là một optional module. Nếu nó bị thiếu trong bản sao CPython của bạn, hãy tìm tài liệu từ nhà phân phối của bạn (nghĩa là bất kỳ ai đã cung cấp Python cho bạn). Nếu bạn là nhà phân phối, hãy xem Yêu cầu đối với các mô-đun tùy chọn.

sẵn có: Unix.

Ghi chú

Thư viện Readline cơ bản API có thể được thư viện editline (libedit) triển khai thay vì readline GNU. Trên macOS, mô-đun readline phát hiện thư viện nào đang được sử dụng trong thời gian chạy.

Tệp cấu hình cho editline khác với tệp cấu hình của GNU. Nếu bạn tải chuỗi cấu hình theo chương trình, bạn có thể sử dụng backend để xác định thư viện nào đang được sử dụng.

Nếu bạn sử dụng mô phỏng readline editline/libedit trên macOS thì tệp khởi tạo nằm trong thư mục chính của bạn có tên là .editrc. Ví dụ: nội dung sau trong ~/.editrc sẽ BẬT liên kết phím vi và hoàn thành TAB:

trăn: liên kết -v
python: liên kết ^I rl_complete

Cũng lưu ý rằng các thư viện khác nhau có thể sử dụng các định dạng tệp lịch sử khác nhau. Khi chuyển đổi thư viện cơ bản, các tệp lịch sử hiện có có thể không sử dụng được.

readline.backend

Tên của thư viện Readline cơ bản đang được sử dụng, "readline" hoặc "editline".

Added in version 3.13.

tập tin ban đầu

Các hàm sau liên quan đến tệp init và cấu hình người dùng:

readline.parse_and_bind(string)

Thực thi dòng init được cung cấp trong đối số string. Điều này gọi rl_parse_and_bind() trong thư viện cơ bản.

readline.read_init_file([filename])

Thực thi một tập tin khởi tạo readline. Tên tệp mặc định là tên tệp cuối cùng được sử dụng. Điều này gọi rl_read_init_file() trong thư viện cơ bản. Nó tạo ra một auditing event open với tên tệp nếu được cung cấp và "<readline_init_file>" nếu không, bất kể thư viện giải quyết tệp nào.

Thay đổi trong phiên bản 3.14: Sự kiện kiểm tra đã được thêm vào.

Bộ đệm dòng

Các chức năng sau hoạt động trên bộ đệm dòng:

readline.get_line_buffer()

Trả về nội dung hiện tại của bộ đệm dòng (rl_line_buffer trong thư viện cơ bản).

readline.insert_text(string)

Chèn văn bản vào bộ đệm dòng tại vị trí con trỏ. Điều này gọi rl_insert_text() trong thư viện cơ bản nhưng bỏ qua giá trị trả về.

readline.redisplay()

Thay đổi nội dung hiển thị trên màn hình để phản ánh nội dung hiện tại của bộ đệm dòng. Điều này gọi rl_redisplay() trong thư viện cơ bản.

Tệp lịch sử

Các chức năng sau hoạt động trên một tệp lịch sử:

readline.read_history_file([filename])

Tải tệp lịch sử đọc dòng và thêm nó vào danh sách lịch sử. Tên tệp mặc định là ~/.history. Điều này gọi read_history() trong thư viện cơ bản và tạo ra một auditing event open với tên tệp nếu được cung cấp và "~/.history" nếu không.

Thay đổi trong phiên bản 3.14: Sự kiện kiểm tra đã được thêm vào.

readline.write_history_file([filename])

Lưu danh sách lịch sử vào tệp lịch sử đọc dòng, ghi đè bất kỳ tệp hiện có nào. Tên tệp mặc định là ~/.history. Điều này gọi write_history() trong thư viện cơ bản và tạo ra một auditing event open với tên tệp nếu được cung cấp và "~/.history" nếu không.

Thay đổi trong phiên bản 3.14: Sự kiện kiểm tra đã được thêm vào.

readline.append_history_file(nelements[, filename])

Nối các mục lịch sử nelements cuối cùng vào một tệp. Tên tệp mặc định là ~/.history. Tệp phải tồn tại. Điều này gọi append_history() trong thư viện cơ bản. Hàm này chỉ tồn tại nếu Python được biên dịch cho phiên bản thư viện hỗ trợ nó. Nó tạo ra một auditing event open với tên tệp nếu được cung cấp và "~/.history" nếu không.

Added in version 3.5.

Thay đổi trong phiên bản 3.14: Sự kiện kiểm tra đã được thêm vào.

readline.get_history_length()

readline.set_history_length(length)

Đặt hoặc trả về số dòng mong muốn để lưu trong tệp lịch sử. Hàm write_history_file() sử dụng giá trị này để cắt bớt tệp lịch sử bằng cách gọi history_truncate_file() trong thư viện cơ bản. Giá trị âm ngụ ý kích thước tệp lịch sử không giới hạn.

Danh sách lịch sử

Các chức năng sau hoạt động trên danh sách lịch sử toàn cầu:

readline.clear_history()

Xóa lịch sử hiện tại. Điều này gọi clear_history() trong thư viện cơ bản. Hàm Python chỉ tồn tại nếu Python được biên dịch cho phiên bản thư viện hỗ trợ nó.

readline.get_current_history_length()

Trả về số lượng mục hiện có trong lịch sử. (Điều này khác với get_history_length(), trả về số dòng tối đa sẽ được ghi vào tệp lịch sử.)

readline.get_history_item(index)

Trả về nội dung hiện tại của mục lịch sử tại index. Chỉ mục mục là dựa trên một. Điều này gọi history_get() trong thư viện cơ bản.

readline.remove_history_item(pos)

Xóa mục lịch sử được chỉ định bởi vị trí của nó khỏi lịch sử. Vị trí dựa trên số không. Điều này gọi remove_history() trong thư viện cơ bản.

readline.replace_history_item(pos, line)

Thay thế mục lịch sử được chỉ định theo vị trí của nó bằng line. Vị trí dựa trên số không. Điều này gọi replace_history_entry() trong thư viện cơ bản.

readline.add_history(line)

Nối line vào bộ đệm lịch sử, như thể đó là dòng cuối cùng được nhập. Điều này gọi add_history() trong thư viện cơ bản.

readline.set_auto_history(enabled)

Bật hoặc tắt cuộc gọi tự động tới add_history() khi đọc dữ liệu đầu vào qua đường đọc. Đối số enabled phải là giá trị Boolean mà khi đúng sẽ bật lịch sử tự động và khi sai sẽ tắt lịch sử tự động.

Added in version 3.6.

Lịch sử tự động được bật theo mặc định và các thay đổi đối với tính năng này không tồn tại qua nhiều phiên.

Móc khởi động

readline.set_startup_hook([function])

Đặt hoặc xóa hàm được gọi lại bằng lệnh gọi lại rl_startup_hook của thư viện cơ bản. Nếu function được chỉ định, nó sẽ được sử dụng làm hàm hook mới; nếu bị bỏ qua hoặc None, mọi chức năng đã được cài đặt sẽ bị xóa. Hook được gọi mà không có đối số ngay trước khi dòng đọc in dấu nhắc đầu tiên.

readline.set_pre_input_hook([function])

Đặt hoặc xóa hàm được gọi lại bằng lệnh gọi lại rl_pre_input_hook của thư viện cơ bản. Nếu function được chỉ định, nó sẽ được sử dụng làm hàm hook mới; nếu bị bỏ qua hoặc None, mọi chức năng đã được cài đặt sẽ bị xóa. Hook được gọi mà không có đối số sau khi dấu nhắc đầu tiên được in và ngay trước khi dòng đọc bắt đầu đọc các ký tự đầu vào. Hàm này chỉ tồn tại nếu Python được biên dịch cho phiên bản thư viện hỗ trợ nó.

Hoàn thành

Các chức năng sau đây liên quan đến việc triển khai chức năng hoàn thành từ tùy chỉnh. Tính năng này thường được vận hành bằng phím Tab và có thể gợi ý cũng như tự động hoàn thành một từ đang được nhập. Theo mặc định, Readline được thiết lập để rlcompleter sử dụng để hoàn thành mã định danh Python cho trình thông dịch tương tác. Nếu mô-đun readline được sử dụng với bộ hoàn chỉnh tùy chỉnh thì phải đặt một bộ dấu phân cách từ khác.

readline.set_completer([function])

Đặt hoặc xóa chức năng hoàn thiện. Nếu function được chỉ định, nó sẽ được sử dụng làm hàm hoàn thiện mới; nếu bị bỏ qua hoặc None, mọi chức năng hoàn chỉnh đã được cài đặt sẽ bị xóa. Hàm hoàn chỉnh được gọi là function(text, state), dành cho state trong 0, 1, 2, ..., cho đến khi nó trả về một giá trị không phải chuỗi. Nó sẽ trả về lần hoàn thành tiếp theo có thể bắt đầu bằng text.

Hàm hoàn thiện đã cài đặt được gọi bằng lệnh gọi lại entry_func được chuyển tới rl_completion_matches() trong thư viện cơ bản. Chuỗi text xuất phát từ tham số đầu tiên của lệnh gọi lại rl_attempted_completion_function của thư viện cơ bản.

readline.get_completer()

Nhận chức năng hoàn chỉnh hoặc None nếu chưa đặt chức năng hoàn chỉnh.

readline.get_completion_type()

Nhận loại hoàn thành đang được thử. Điều này trả về biến rl_completion_type trong thư viện cơ bản dưới dạng số nguyên.

readline.get_begidx()

readline.get_endidx()

Lấy chỉ mục bắt đầu hoặc kết thúc của phạm vi hoàn thành. Các chỉ mục này là các đối số start và end được chuyển đến hàm gọi lại rl_attempted_completion_function của thư viện cơ bản. Các giá trị có thể khác nhau trong cùng một kịch bản chỉnh sửa đầu vào dựa trên việc triển khai dòng đọc C cơ bản. Ví dụ: libedit được biết là hoạt động khác với libreadline.

readline.set_completer_delims(string)

readline.get_completer_delims()

Đặt hoặc lấy các dấu phân cách từ để hoàn thành. Chúng xác định điểm bắt đầu của từ cần được xem xét để hoàn thành (phạm vi hoàn thành). Các hàm này truy cập vào biến rl_completer_word_break_characters trong thư viện cơ bản.

readline.set_completion_display_matches_hook([function])

Đặt hoặc xóa chức năng hiển thị hoàn thành. Nếu function được chỉ định, nó sẽ được sử dụng làm chức năng hiển thị hoàn thành mới; nếu bị bỏ qua hoặc None, mọi chức năng hiển thị hoàn thành đã được cài đặt sẽ bị xóa. Việc này đặt hoặc xóa lệnh gọi lại rl_completion_display_matches_hook trong thư viện cơ bản. Chức năng hiển thị hoàn thành được gọi là function(substitution, [matches], longest_match_length) mỗi lần cần hiển thị kết quả khớp.

Ví dụ

Ví dụ sau đây minh họa cách sử dụng chức năng đọc và ghi lịch sử của mô-đun readline để tự động tải và lưu tệp lịch sử có tên .python_history từ thư mục chính của người dùng. Mã bên dưới thường được thực thi tự động trong các phiên tương tác từ tệp PYTHONSTARTUP của người dùng.

nhập khẩu atexit
hệ điều hành nhập khẩu
nhập dòng đọc

histfile = os.path.join(os.path.expanduser("~"), ".python_history")
thử:
    readline.read_history_file(histfile)
    Lịch sử # default len là -1 (vô hạn), có thể phát triển ngang ngược
    readline.set_history_length(1000)
ngoại trừ FileNotFoundError:
    vượt qua

atexit.register(readline.write_history_file, histfile)

Mã này thực sự được chạy tự động khi Python chạy trong interactive mode (xem Cấu hình đường đọc).

Ví dụ sau đạt được mục tiêu tương tự nhưng hỗ trợ các phiên tương tác đồng thời, bằng cách chỉ thêm lịch sử mới.

nhập khẩu atexit
hệ điều hành nhập khẩu
nhập dòng đọc
histfile = os.path.join(os.path.expanduser("~"), ".python_history")

thử:
    readline.read_history_file(histfile)
    h_len = readline.get_current_history_length()
ngoại trừ FileNotFoundError:
    open(histfile, 'wb').close()
    h_len = 0

lưu chắc chắn(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(lưu, h_len, histfile)

Ví dụ sau mở rộng lớp code.InteractiveConsole để hỗ trợ lưu/khôi phục lịch sử.

nhập khẩu atexit
mã nhập khẩu
hệ điều hành nhập khẩu
nhập dòng đọc

lớp HistoryConsole(code.InteractiveConsole):
    def __init__(self,locals=None, filename="<console>",
                 histfile=os.path.expanduser("~/.console-history")):
        code.InteractiveConsole.__init__(bản thân, người dân địa phương, tên tệp)
        self.init_history(histfile)

    def init_history(self, histfile):
        readline.parse_and_bind("tab: hoàn thành")
        if hasattr(readline, "read_history_file"):
            thử:
                readline.read_history_file(histfile)
            ngoại trừ FileNotFoundError:
                vượt qua
            atexit.register(self.save_history, histfile)

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

Ghi chú

Zz000zz mới được giới thiệu trong phiên bản 3.13 không hỗ trợ dòng đọc. Tuy nhiên, readline vẫn có thể được sử dụng bằng cách đặt biến môi trường PYTHON_BASIC_REPL.