readline --- رابط GNU readline

---

ماژول readline تعدادی تابع را برای تسهیل تکمیل و خواندن/نوشتن پرونده‌های تاریخچه‌ی مفسر پایتون تعریف می‌کند. می‌توان از این ماژول به‌طور مستقیم یا از طریق ماژول rlcompleter استفاده کرد، که از تکمیل شناسه‌های پایتون در اعلان تعاملی پشتیبانی می‌کند. تنظیمات انجام‌شده با استفاده از این ماژول بر رفتار هم اعلان تعاملی مفسر و هم اعلان‌های ارائه‌شده توسط تابع توکار input() تأثیر می‌گذارد.

می‌توانید کلیدبندی‌های Readline را از طریق یک پرونده راه‌اندازی پیکربندی کنید، که معمولاً .inputrc در پوشه‌ی خانگی شما قرار دارد. برای اطلاعات در مورد قالب و ساختارهای مجاز آن پرونده و قابلیت‌های کتابخانه‌ی Readline به‌طور کلی، به Readline Init File در راهنمای GNU Readline مراجعه کنید.

دسترس‌پذیری: not Android, not iOS, not WASI.

این ماژول در سکوهای موبایل یا سکوهای WebAssembly پشتیبانی نمی‌شود.

این یک optional module است. اگر این ماژول در نسخه CPython شما وجود ندارد، به مستندات توزیع‌کننده خود (یعنی هر کسی که پایتون را در اختیار شما قرار داده است) مراجعه کنید. اگر توزیع‌کننده هستید، نیازمندی‌های ماژول‌های اختیاری را ببینید.

دسترس‌پذیری: Unix.

توجه

ممکن است API زیربنایی کتابخانه Readline به‌جای GNU readline توسط کتابخانه‌ی editline (libedit) پیاده‌سازی شده باشد. در macOS، ماژول readline تشخیص می‌دهد که کدام کتابخانه در ران‌تایم استفاده می‌شود.

پرونده‌ی پیکربندی editline با پرونده‌ی پیکربندی GNU readline متفاوت است. اگر رشته‌های پیکربندی را به‌صورت برنامه‌ای بارگذاری کنید، می‌توانید از backend برای تشخیص اینکه کدام کتابخانه استفاده می‌شود استفاده کنید.

اگر در macOS از شبیه‌سازی readline با editline/libedit استفاده می‌کنید، پرونده راه‌اندازی که در پوشه‌ی خانگی شما قرار دارد، .editrc نامیده می‌شود. برای مثال، محتوای زیر در ~/.editrc کلیدبندی‌های vi و تکمیل با TAB را فعال می‌کند:

python:bind -v
python:bind ^I rl_complete

همچنین توجه داشته باشید که کتابخانه‌های مختلف ممکن است از قالب‌های پرونده تاریخچه‌ی متفاوتی استفاده کنند. هنگام تعویض کتابخانه‌ی پایه، پرونده‌های تاریخچه‌ی موجود ممکن است غیرقابل‌استفاده شوند.

readline.backend

نام کتابخانه‌ی Readline زیربنایی در حال استفاده، که یا "readline" یا "editline" است.

اضافه شده در نسخه‌ی 3.13.

پرونده init

توابع زیر به پرونده init و پیکربندی کاربر مربوط می‌شوند:

readline.parse_and_bind(string)

خط راه‌اندازی (init) ارائه‌شده در آرگومان string را اجرا می‌کند. این تابع rl_parse_and_bind() را در کتابخانه زیرین فراخوانی می‌کند.

readline.read_init_file([filename])

یک پرونده راه‌اندازی readline را اجرا می‌کند. نام پرونده پیش‌فرض، آخرین نام پرونده استفاده‌شده است. این تابع rl_read_init_file() را در کتابخانه زیرین فراخوانی می‌کند. این تابع یک رویداد حسابرسی open را با نام پرونده در صورت داده‌شدن، و در غیر این صورت با "<readline_init_file>" پرتاب می‌کند، صرف‌نظر از اینکه کتابخانه کدام پرونده را حل می‌کند.

تغییر یافته در نسخه‌ی 3.14: رویداد حسابرسی افزوده شد.

بافر خط

توابع زیر بر بافر خط عمل می‌کنند:

readline.get_line_buffer()

محتوای فعلی بافر خط (rl_line_buffer در کتابخانه زیرین) را برمی‌گرداند.

readline.insert_text(string)

متن را در بافر خط در موقعیت مکان‌نما درج می‌کند. این تابع rl_insert_text() را در کتابخانه زیرین فراخوانی می‌کند، اما مقدار بازگشتی را نادیده می‌گیرد.

readline.redisplay()

آنچه را که روی صفحه نمایش داده می‌شود تغییر دهید تا محتوای فعلی بافر خط (line buffer) را بازتاب دهد. این کار rl_redisplay() را در کتابخانه زیرین فراخوانی می‌کند.

پرونده تاریخچه

توابع زیر روی یک پرونده تاریخچه عمل می‌کنند:

readline.read_history_file([filename])

یک پرونده تاریخچه‌ی readline را بارگذاری می‌کند و آن را به فهرست تاریخچه اضافه می‌کند. نام پیش‌فرض پرونده ~/.history است. این تابع read_history() را در کتابخانه زیرین فراخوانی می‌کند و یک رویداد حسابرسی open را با نام پرونده در صورت ارائه‌شدن و در غیر این صورت با "~/.history" پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.14: رویداد حسابرسی افزوده شد.

readline.write_history_file([filename])

فهرست تاریخچه را در یک پرونده تاریخچه‌ی readline ذخیره می‌کند و هر پرونده موجود را بازنویسی می‌کند. نام پرونده پیش‌فرض ~/.history است. این تابع write_history() را در کتابخانه‌ی زیرین فراخوانی می‌کند و یک رویداد حسابرسی open را با نام پرونده در صورت داده‌شدن و در غیر این صورت با "~/.history" پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.14: رویداد حسابرسی افزوده شد.

readline.append_history_file(nelements[, filename])

آخرین nelements آیتم از تاریخچه را به یک پرونده می‌افزاید. نام پیش‌فرض پرونده ~/.history است. پرونده باید از قبل وجود داشته باشد. این تابع، append_history() را در کتابخانه زیرین فراخوانی می‌کند. این تابع تنها در صورتی وجود دارد که پایتون برای نسخه‌ای از کتابخانه که آن را پشتیبانی می‌کند کامپایل شده باشد. این تابع یک رویداد حسابرسی open را همراه با نام پرونده در صورت ارائه‌شدن و در غیر این صورت همراه با "~/.history" پرتاب می‌کند.

اضافه شده در نسخه‌ی 3.5.

تغییر یافته در نسخه‌ی 3.14: رویداد حسابرسی افزوده شد.

readline.get_history_length()

readline.set_history_length(length)

تنظیم یا بازگرداندن تعداد سطرهای مورد نظر برای ذخیره در پرونده تاریخچه. تابع write_history_file() از این مقدار برای کوتاه کردن پرونده تاریخچه، با فراخوانی history_truncate_file() در کتابخانه زیرین استفاده می‌کند. مقادیر منفی به معنای نامحدود بودن اندازه پرونده تاریخچه هستند.

فهرست تاریخچه

توابع زیر روی یک فهرست تاریخچه‌ی سراسری عمل می‌کنند:

readline.clear_history()

تاریخچه‌ی فعلی را پاک می‌کند. این کار clear_history() را در کتابخانه‌ی زیربنایی فراخوانی می‌کند. این تابع پایتون فقط در صورتی وجود دارد که پایتون برای نسخه‌ای از کتابخانه کامپایل شده باشد که از آن پشتیبانی کند.

readline.get_current_history_length()

تعداد آیتم‌های فعلی در تاریخچه را برمی‌گرداند. (این با get_history_length() متفاوت است، که حداکثر تعداد سطرهایی را که در یک پرونده تاریخچه نوشته خواهند شد، برمی‌گرداند.)

readline.get_history_item(index)

محتوای جاری آیتم تاریخچه در index را بازمی‌گرداند. اندیس آیتم یک‌مبنا است. این تابع history_get() را در کتابخانه زیرین فراخوانی می‌کند.

readline.remove_history_item(pos)

آیتم تاریخچه‌ی مشخص‌شده با موقعیت آن را از تاریخچه حذف می‌کند. موقعیت مبتنی بر صفر است. این تابع remove_history() را در کتابخانه زیربنایی فراخوانی می‌کند.

readline.replace_history_item(pos, line)

آیتم تاریخچه مشخص‌شده با موقعیتش را با line جایگزین می‌کند. موقعیت از صفر شروع می‌شود. این replace_history_entry() را در کتابخانه زیرین فراخوانی می‌کند.

readline.add_history(line)

line را به بافر تاریخچه اضافه می‌کند، گویی آخرین خط تایپ‌شده بوده است. این تابع add_history() را در کتابخانه زیرین فراخوانی می‌کند.

readline.set_auto_history(enabled)

فعال یا غیرفعال کردن فراخوانی‌های خودکار add_history() هنگام خواندن ورودی از طریق readline. آرگومان enabled باید یک مقدار بولی باشد که اگر true باشد، تاریخچه خودکار را فعال می‌کند و اگر false باشد، تاریخچه خودکار را غیرفعال می‌کند.

اضافه شده در نسخه‌ی 3.6.

تاریخچه‌ی خودکار به‌طور پیش‌فرض فعال است و تغییرات آن در چندین نشست باقی نمی‌مانند.

قلاب‌های راه‌اندازی

readline.set_startup_hook([function])

تابعی را که به‌وسیله‌ی کال‌بک rl_startup_hook در کتابخانه‌ی زیرین فراخوانی می‌شود، تنظیم یا حذف کنید. اگر function تعیین شده باشد، به‌عنوان تابع قلاب جدید استفاده خواهد شد؛ اگر ذکر نشود یا None باشد، هر تابعی که از قبل نصب‌شده باشد حذف می‌شود. قلاب بدون آرگومان، درست پیش از آنکه readline نخستین اعلان را چاپ کند، فراخوانی می‌شود.

readline.set_pre_input_hook([function])

تابعی را که توسط کال‌بک rl_pre_input_hook در کتابخانه زیربنایی فراخوانی می‌شود، تنظیم یا حذف کنید. اگر function مشخص شود، به‌عنوان تابع قلاب جدید استفاده خواهد شد؛ اگر ذکر نشود یا None باشد، هر تابعی که از پیش نصب‌شده باشد حذف می‌شود. این قلاب پس از چاپ نخستین اعلان و درست پیش از آنکه readline خواندن نویسه‌های ورودی را آغاز کند، بدون آرگومان فراخوانی می‌شود. این تابع فقط در صورتی وجود دارد که پایتون برای نسخه‌ای از کتابخانه کامپایل‌شده باشد که از آن پشتیبانی می‌کند.

تکمیل

توابع زیر به پیاده‌سازی یک تابع سفارشی تکمیل کلمه مربوط می‌شوند. این قابلیت معمولاً با کلید Tab فعال می‌شود و می‌تواند کلمه‌ای را که در حال تایپ است پیشنهاد دهد و به‌طور خودکار تکمیل کند. به‌طور پیش‌فرض، Readline به‌گونه‌ای تنظیم شده است که توسط rlcompleter برای تکمیل شناسه‌های پایتون در مفسر تعاملی استفاده شود. اگر ماژول readline قرار است همراه با یک تکمیل‌کننده سفارشی استفاده شود، باید مجموعه متفاوتی از جداکننده‌های کلمه تنظیم شود.

readline.set_completer([function])

تابع تکمیل‌کننده را تنظیم یا حذف کنید. اگر function مشخص شده باشد، به‌عنوان تابع تکمیل‌کننده جدید استفاده می‌شود؛ اگر ذکر نشود یا None باشد، هر تابع تکمیل‌کننده‌ای که از پیش نصب شده باشد حذف می‌شود. تابع تکمیل‌کننده به‌صورت function(text, state) فراخوانی می‌شود، به ازای state در 0، 1، 2، ...، تا زمانی که مقداری غیررشته‌ای برگرداند. این تابع باید تکمیل ممکن بعدی را که با text آغاز می‌شود برگرداند.

تابع تکمیل‌کننده نصب‌شده توسط کال‌بک entry_func که به rl_completion_matches() در کتابخانه زیربنایی پاس داده شده است، فراخوانی می‌شود. رشته text از نخستین پارامتر کال‌بک rl_attempted_completion_function در کتابخانه زیربنایی گرفته می‌شود.

readline.get_completer()

تابع تکمیل‌کننده را دریافت می‌کند، یا اگر تابع تکمیل‌کننده‌ای تنظیم نشده باشد، None.

readline.get_completion_type()

نوع تکمیلی که برای آن اقدام می‌شود را دریافت کنید. این، متغیر rl_completion_type را در کتابخانه زیرین به‌صورت یک عدد صحیح برمی‌گرداند.

readline.get_begidx()

readline.get_endidx()

اندیس آغاز یا پایان محدوده تکمیل را دریافت کنید. این اندیس‌ها، آرگومان‌های start و end هستند که به کال‌بک rl_attempted_completion_function کتابخانه زیربنایی ارسال می‌شوند. مقادیر ممکن است در یک سناریوی ویرایش ورودی یکسان، بسته به پیاده‌سازی readline زیربنایی به زبان C متفاوت باشند. مثال: شناخته شده است که libedit رفتاری متفاوت از libreadline دارد.

readline.set_completer_delims(string)

readline.get_completer_delims()

تنظیم یا دریافت جداکننده‌های واژه برای تکمیل. این موارد آغاز واژه‌ای را که برای تکمیل در نظر گرفته می‌شود (محدوده تکمیل) تعیین می‌کنند. این توابع به متغیر rl_completer_word_break_characters در کتابخانه پایه دسترسی دارند.

readline.set_completion_display_matches_hook([function])

تابع نمایش تکمیل را تنظیم یا حذف می‌کند. اگر function مشخص شده باشد، به‌عنوان تابع نمایش تکمیل جدید استفاده خواهد شد؛ اگر ذکر نشده باشد یا None باشد، هر تابع نمایش تکمیلی که از قبل نصب‌شده باشد حذف می‌شود. این کار کال‌بک rl_completion_display_matches_hook را در کتابخانه زیرین تنظیم یا پاک می‌کند. تابع نمایش تکمیل هر بار که نیاز به نمایش موارد منطبق باشد، یک بار به صورت function(substitution, [matches], longest_match_length) فراخوانی می‌شود.

مثال

مثال زیر نشان می‌دهد که چگونه از توابع خواندن و نوشتن تاریخچه‌ی ماژول readline برای بارگذاری و ذخیره‌ی خودکار یک پرونده تاریخچه با نام .python_history از پوشه‌ی خانگی کاربر استفاده کنید. کد زیر معمولاً در طول نشست‌های تعاملی به‌طور خودکار از پرونده PYTHONSTARTUP کاربر اجرا می‌شود.

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)

این کد در واقع به‌طور خودکار زمانی اجرا می‌شود که پایتون در حالت تعاملی اجرا شود (به پیکربندی Readline مراجعه کنید).

مثال زیر همان هدف را برآورده می‌کند، اما فقط با افزودن تاریخچه‌ی جدید، از نشست‌های تعاملی همزمان پشتیبانی می‌کند.

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 را گسترش می‌دهد تا از ذخیره/بازیابی تاریخچه پشتیبانی کند.

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)

توجه

REPL جدید معرفی‌شده در نسخه 3.13 از readline پشتیبانی نمی‌کند. با این حال، همچنان می‌توان با تنظیم متغیر محیطی PYTHON_BASIC_REPL از readline استفاده کرد.