code --- کلاس‌های پایه مفسر

کد منبع: Lib/code.py

---

ماژول code امکاناتی برای پیاده‌سازی حلقه‌های خواندن-ارزیابی-چاپ (REPL) در پایتون فراهم می‌کند. دو کلاس و توابع کمکی گنجانده شده‌اند که می‌توان از آن‌ها برای ساخت برنامه‌هایی استفاده کرد که اعلان مفسر تعاملی را ارائه می‌دهند.

class code.InteractiveInterpreter(locals=None)

این کلاس به تجزیه و وضعیت مفسر (فضای نام کاربر) می‌پردازد؛ به بافر کردن ورودی، نمایش اعلان یا نام‌گذاری پرونده ورودی نمی‌پردازد (نام پرونده همیشه به‌صورت صریح ارسال می‌شود). آرگومان اختیاری locals نگاشتی را برای استفاده به‌عنوان فضای نامی که کد در آن اجرا خواهد شد مشخص می‌کند؛ مقدار پیش‌فرض آن یک دیکشنری تازه‌ساخته است که در آن کلید '__name__' روی '__console__' و کلید '__doc__' روی None تنظیم شده است.

توجه داشته باشید که اشیای توابع و کلاس‌های ایجادشده تحت یک نمونه InteractiveInterpreter به فضای نام مشخص‌شده توسط locals تعلق خواهند داشت. آن‌ها تنها در صورتی قابل پیکل (pickleable) هستند که locals فضای نام یک ماژول موجود باشد.

class code.InteractiveConsole(locals=None, filename='<console>', local_exit=False)

به‌دقت رفتار مفسر تعاملی پایتون را شبیه‌سازی می‌کند. این کلاس بر پایه InteractiveInterpreter ساخته شده و اعلان‌دهی با استفاده از sys.ps1 و sys.ps2 آشنا و همچنین بافرینگ ورودی را اضافه می‌کند. اگر local_exit درست باشد، exit() و quit() در کنسول SystemExit را پرتاب نمی‌کنند، بلکه به کد فراخوان بازمی‌گردند.

تغییر یافته در نسخه‌ی 3.13: پارامتر local_exit افزوده شد.

code.interact(banner=None, readfunc=None, local=None, exitmsg=None, local_exit=False)

تابعی برای سهولت اجرای حلقه‌ی خواندن-ارزیابی-چاپ. این تابع یک نمونه‌ی جدید از InteractiveConsole ایجاد می‌کند و، در صورت ارائه‌شدن readfunc، آن را تنظیم می‌کند تا به‌عنوان متد InteractiveConsole.raw_input() استفاده شود. اگر local ارائه‌شده باشد، به سازنده‌ی InteractiveConsole ارسال می‌شود تا به‌عنوان فضای نام پیش‌فرض برای حلقه‌ی مفسر استفاده شود. اگر local_exit ارائه‌شده باشد، به سازنده‌ی InteractiveConsole ارسال می‌شود. سپس متد interact() این نمونه اجرا می‌شود، درحالی‌که banner و exitmsg، در صورت ارائه‌شدن، به‌عنوان بنر و پیام خروج برای استفاده ارسال می‌شوند. شیء کنسول پس از استفاده دور انداخته می‌شود.

تغییر یافته در نسخه‌ی 3.6: پارامتر exitmsg اضافه شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر local_exit افزوده شد.

code.compile_command(source, filename='<input>', symbol='single')

این تابع برای برنامه‌هایی مفید است که می‌خواهند حلقه‌ی اصلی مفسر پایتون (معروف به حلقه‌ی خواندن-ارزیابی-چاپ) را شبیه‌سازی کنند. بخش دشوار، تشخیص این موضوع است که کاربر چه زمانی یک دستور ناقص وارد کرده است که می‌توان آن را با وارد کردن متن بیشتر کامل کرد (در مقابل یک دستور کامل یا یک خطای سینتکسی). این تابع تقریباً همیشه همان تصمیمی را می‌گیرد که حلقه‌ی اصلی واقعی مفسر می‌گیرد.

source رشته منبع است؛ filename نام پرونده اختیاری است که منبع از آن خوانده شده است، با پیش‌فرض '<input>'؛ و symbol نماد شروع اختیاری دستور زبان است که باید 'single' (پیش‌فرض)، 'eval' یا 'exec' باشد.

اگر دستور کامل و معتبر باشد، یک شیء کد (همانند compile(source, filename, symbol)) را بازمی‌گرداند؛ اگر دستور ناتمام باشد، None را بازمی‌گرداند؛ اگر دستور کامل باشد و حاوی خطای سینتکسی باشد، SyntaxError را پرتاب می‌کند، یا اگر دستور حاوی یک لفظی نامعتبر باشد، OverflowError یا ValueError را پرتاب می‌کند.

اشیای مفسر تعاملی

InteractiveInterpreter.runsource(source, filename='<input>', symbol='single')

مقداری کد منبع را در مفسر کامپایل و اجرا می‌کند. آرگومان‌ها همان آرگومان‌های compile_command() هستند؛ پیش‌فرض برای filename برابر '<input>' و برای symbol برابر 'single' است. یکی از چند حالت ممکن است رخ دهد:

• ورودی نادرست است؛ compile_command() استثنایی پرتاب کرد (SyntaxError یا OverflowError). با فراخوانی متد showsyntaxerror()، یک ردگیری سینتکسی چاپ خواهد شد. runsource() مقدار False را بازمی‌گرداند.

• ورودی ناقص است و به ورودی بیشتری نیاز است؛ compile_command() None را برگرداند. runsource() True را برمی‌گرداند.

• ورودی کامل است؛ compile_command() یک شیء کد برگرداند. کد با فراخوانی runcode() اجرا می‌شود (که استثناهای ران‌تایم را نیز مدیریت می‌کند، به‌جز SystemExit). runsource() False را برمی‌گرداند.

می‌توان از مقدار بازگشتی برای تصمیم‌گیری درباره‌ی استفاده از sys.ps1 یا sys.ps2 به‌عنوان اعلان خط بعدی استفاده کرد.

InteractiveInterpreter.runcode(code)

یک شیء کد را اجرا می‌کند. هنگامی که یک استثنا رخ می‌دهد، showtraceback() برای نمایش یک ردگیری پشته فراخوانی می‌شود. همه‌ی استثناها گرفته می‌شوند، به‌جز SystemExit، که اجازه دارد منتشر شود.

نکته‌ای در مورد KeyboardInterrupt: این استثنا ممکن است در جاهای دیگری از این کد رخ دهد و ممکن است همیشه گرفته نشود. فراخواننده باید برای رسیدگی به آن آماده باشد.

InteractiveInterpreter.showsyntaxerror(filename=None)

خطای سینتکسی‌ای را که به‌تازگی رخ داده است نمایش می‌دهد. این کار ردگیری پشته را نمایش نمی‌دهد، زیرا برای خطاهای سینتکسی هیچ ردگیری پشته‌ای وجود ندارد. اگر filename داده شود، این نام به‌جای نام پرونده پیش‌فرض ارائه‌شده توسط پارسر پایتون در استثنا گنجانده می‌شود، زیرا آن پارسر همیشه هنگام خواندن از یک رشته از '<string>' استفاده می‌کند. خروجی توسط متد write() نوشته می‌شود.

InteractiveInterpreter.showtraceback()

استثنایی را که به‌تازگی رخ داده است نمایش می‌دهیم. نخستین آیتم پشته را حذف می‌کنیم، زیرا درون پیاده‌سازی شیء مفسر قرار دارد. خروجی توسط متد write() نوشته می‌شود.

تغییر یافته در نسخه‌ی 3.5: ردگیری پشته زنجیره‌ای کامل به‌جای تنها ردگیری پشته اصلی نمایش داده می‌شود.

InteractiveInterpreter.write(data)

یک رشته را در جریان خطای استاندارد (sys.stderr) می‌نویسد. کلاس‌های مشتق‌شده باید این متد را بازنویسی کنند تا در صورت نیاز، پردازش خروجی مناسب را فراهم کنند.

اشیای کنسول تعاملی

کلاس InteractiveConsole زیرکلاسی از InteractiveInterpreter است، بنابراین همه‌ی متدهای اشیای مفسر و همچنین موارد افزودنی زیر را ارائه می‌دهد.

InteractiveConsole.interact(banner=None, exitmsg=None)

تا حد زیادی کنسول تعاملی پایتون را شبیه‌سازی می‌کند. آرگومان اختیاری banner بنری را مشخص می‌کند که پیش از نخستین تعامل چاپ می‌شود؛ به‌طور پیش‌فرض، بنری مشابه بنر چاپ‌شده توسط مفسر استاندارد پایتون را چاپ می‌کند و پس از آن، نام کلاس شیء کنسول در پرانتز می‌آید (تا با مفسر واقعی اشتباه گرفته نشود — چون بسیار نزدیک است!).

آرگومان اختیاری exitmsg یک پیام خروج را مشخص می‌کند که هنگام خروج چاپ می‌شود. برای جلوگیری از چاپ پیام خروج، رشته خالی را بدهید. اگر exitmsg داده نشود یا None باشد، یک پیام پیش‌فرض چاپ می‌شود.

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

تغییر یافته در نسخه‌ی 3.6: هنگام خروج، یک پیام خروج چاپ می‌شود.

InteractiveConsole.push(line)

یک خط از متن منبع را به مفسر ارسال کنید. خط نباید به نویسه‌ی خط جدید ختم شود؛ ممکن است شامل نویسه‌های خط جدید داخلی باشد. خط به یک بافر افزوده می‌شود و متد runsource() مفسر با محتوای به‌هم‌پیوسته‌ی بافر به‌عنوان منبع فراخوانی می‌شود. اگر این نشان دهد که دستور اجراشده یا نامعتبر است، بافر بازنشانی می‌شود؛ در غیر این صورت، دستور ناقص است و بافر به همان حالت پس از افزودن خط باقی می‌ماند. مقدار بازگشتی در صورتی True است که به ورودی بیشتری نیاز باشد، و در صورتی False است که خط به شکلی پردازش‌شده باشد (این همانند runsource() است).

InteractiveConsole.resetbuffer()

هرگونه متن منبع پردازش‌نشده را از بافر ورودی حذف کنید.

InteractiveConsole.raw_input(prompt='')

یک اعلان را می‌نویسد و یک خط را می‌خواند. خط برگردانده‌شده شامل نویسه‌ی خط جدید پایانی نیست. هنگامی که کاربر دنباله‌ی کلیدهای EOF را وارد کند، EOFError پرتاب می‌شود. پیاده‌سازی پایه از sys.stdin می‌خواند؛ یک زیرکلاس می‌تواند این را با پیاده‌سازی متفاوتی جایگزین کند.