مقداردهی اولیه و نهایی‌سازی مفسر

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

پیش از مقداردهی اولیه پایتون

In an application embedding Python, the Py_Initialize() function must be called before using any other Python/C API functions; with the exception of a few functions.

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

نکته

Despite their apparent similarity to some of the functions listed above, the following functions should not be called before the interpreter has been initialized: Py_EncodeLocale(), and Py_RunMain().

راه‌اندازی و نهایی‌سازی مفسر

void Py_Initialize()
قسمتی از ABI پایدار.

مفسر پایتون را راه‌اندازی می‌کند. در برنامه‌ای که پایتون را تعبیه می‌کند، این تابع باید پیش از استفاده از هر تابع دیگری از Python/C API فراخوانی شود؛ برای استثناهای معدود، پیش از راه‌اندازی پایتون را ببینید.

این کار جدول ماژول‌های بارگذاری‌شده (sys.modules) را مقداردهی اولیه می‌کند و ماژول‌های بنیادی builtins، __main__ و sys را ایجاد می‌کند. همچنین مسیر جستجوی ماژول (sys.path) را مقداردهی اولیه می‌کند. این کار sys.argv را تنظیم نمی‌کند؛ برای این منظور از API پیکربندی مقداردهی اولیه پایتون استفاده کنید. این کار هنگام فراخوانی برای بار دوم (بدون فراخوانی Py_FinalizeEx() پیش از آن) یک عملیات بی‌اثر است. هیچ مقدار بازگشتی وجود ندارد؛ در صورت شکست مقداردهی اولیه، خطای مهلک رخ می‌دهد.

از Py_InitializeFromConfig() برای سفارشی‌سازی پیکربندی راه‌اندازی پایتون استفاده کنید.

نکته

در ویندوز، حالت کنسول را از O_TEXT به O_BINARY تغییر می‌دهد که بر استفاده‌های غیرپایتونی از کنسول با استفاده از زمان اجرای C (C Runtime) نیز تأثیر می‌گذارد.

void Py_InitializeEx(int initsigs)
قسمتی از ABI پایدار.

اگر initsigs برابر 1 باشد، این تابع مانند Py_Initialize() عمل می‌کند. اگر initsigs برابر 0 باشد، از ثبت هندلرهای سیگنال در زمان راه‌اندازی صرف‌نظر می‌کند، که این امر می‌تواند زمانی مفید باشد که سی‌پایتون به‌عنوان بخشی از یک برنامه بزرگ‌تر تعبیه شده باشد.

از Py_InitializeFromConfig() برای سفارشی‌سازی پیکربندی راه‌اندازی پایتون استفاده کنید.

PyStatus Py_InitializeFromConfig(const PyConfig *config)

پایتون را از پیکربندی config مقداردهی اولیه کنید، همان‌طور که در مقداردهی اولیه با PyConfig توضیح داده‌شده است.

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

تغییر یافته در نسخه‌ی 3.16: The function no longer returns an exit code if a command line option wants to exit Python. Instead, the option is processed in Py_RunMain().

int Py_IsInitialized()
قسمتی از ABI پایدار.

هنگامی که مفسر پایتون مقداردهی اولیه شده باشد، true (غیرصفر) را برمی‌گرداند و در غیر این صورت false (صفر) را برمی‌گرداند. پس از فراخوانی Py_FinalizeEx()، این تابع تا زمانی که Py_Initialize() دوباره فراخوانی شود، false برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.15: این تابع تا زمانی که مقداردهی اولیه به‌طور کامل تکمیل نشده باشد، از جمله ایمپورت ماژول site، دیگر مقدار true را برنمی‌گرداند. پیش‌تر ممکن بود در حالی که Py_Initialize() هنوز در حال اجرا بود، مقدار true را برگرداند.

int Py_IsFinalizing()
قسمتی از ABI پایدار از نسخه‌ی 3.13.

اگر مفسر اصلی پایتون در حال خاموش شدن باشد، مقدار true (غیرصفر) را برمی‌گرداند. در غیر این صورت مقدار false (صفر) را برمی‌گرداند.

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

int Py_FinalizeEx()
قسمتی از ABI پایدار از نسخه‌ی 3.6.

تمام مقداردهی‌های اولیه‌ای که توسط Py_Initialize() و استفاده‌های بعدی از توابع Python/C API انجام شده‌اند را لغو می‌کند، و تمام زیرمفسرهایی (به Py_NewInterpreter() در ادامه مراجعه کنید) که از آخرین فراخوانی Py_Initialize() ایجاد شده‌اند و هنوز نابود نشده‌اند را نابود می‌کند. این تابع در صورت فراخوانی برای بار دوم (بدون فراخوانی مجدد Py_Initialize() در ابتدا) یک عملیات بی‌اثر است.

از آنجا که این تابع معکوسِ Py_Initialize() است، باید در همان نخ و با همان مفسرِ فعال فراخوانی شود. این به معنای نخ اصلی و مفسر اصلی است. این تابع هرگز نباید در حین اجرای Py_RunMain() فراخوانی شود.

معمولاً مقدار بازگشتی 0 است. اگر هنگام نهایی‌سازی (تخلیه داده‌های بافرشده) خطاهایی رخ داده باشد، -1 بازگردانده می‌شود.

توجه داشته باشید که پایتون تلاش حداکثری خود را برای آزادسازی تمام حافظه‌ای که توسط مفسر پایتون تخصیص یافته است، انجام می‌دهد. بنابراین، هر ماژول توسعه‌ای C باید مطمئن شود که همه‌ی اشیای PyObject که پیش‌تر تخصیص یافته‌اند، پیش از استفاده از آن‌ها در فراخوانی‌های بعدی Py_Initialize() به‌درستی پاک‌سازی می‌شوند. در غیر این صورت، ممکن است آسیب‌پذیری‌ها و رفتار نادرست ایجاد شود.

این تابع به دلایل متعددی ارائه شده است. یک برنامه جاساز ممکن است بخواهد پایتون را از نو راه‌اندازی کند، بدون آنکه لازم باشد خودِ برنامه را راه‌اندازی مجدد کند. برنامه‌ای که مفسر پایتون را از یک کتابخانه بارگذاری‌پذیر پویا (یا DLL) بارگذاری کرده است، ممکن است بخواهد پیش از تخلیه DLL، تمام حافظه تخصیص‌یافته توسط پایتون را آزاد کند. در جریان ردیابی نشت حافظه در یک برنامه، ممکن است توسعه‌دهنده‌ای بخواهد پیش از خروج از برنامه، تمام حافظه تخصیص‌یافته توسط پایتون را آزاد کند.

باگ‌ها و هشدارها: تخریب ماژول‌ها و اشیاء موجود در ماژول‌ها به ترتیب تصادفی انجام می‌شود؛ این ممکن است باعث شود مخرب‌ها (متدهای __del__()) هنگامی که به اشیاء دیگر (حتی توابع) یا ماژول‌ها وابسته‌اند، شکست بخورند. ماژول‌های توسعه‌ای که به‌صورت پویا توسط پایتون بارگذاری شده‌اند، تخلیه نمی‌شوند. مقادیر کمی از حافظه‌ی تخصیص‌یافته توسط مفسر پایتون ممکن است آزاد نشوند (اگر نشتی حافظه پیدا کردید، لطفاً آن را گزارش کنید). حافظه‌ی درگیر در ارجاع‌های چرخه‌ای میان اشیاء آزاد نمی‌شود. همه‌ی رشته‌های درونی‌سازی‌شده (interned strings) صرف‌نظر از شمارش ارجاع‌شان آزاد می‌شوند. مقداری از حافظه‌ی تخصیص‌یافته توسط ماژول‌های توسعه‌ای ممکن است آزاد نشود. برخی ماژول‌های توسعه‌ای ممکن است اگر روال مقداردهی اولیه‌شان بیش از یک بار فراخوانی شود، به‌درستی کار نکنند؛ این می‌تواند در صورتی رخ دهد که برنامه‌ای Py_Initialize() و Py_FinalizeEx() را بیش از یک بار فراخوانی کند. Py_FinalizeEx() نباید به‌صورت بازگشتی از درون خود فراخوانی شود. بنابراین، هیچ کدی که ممکن است به‌عنوان بخشی از فرایند خاموش‌شدن مفسر اجرا شود، نباید آن را فراخوانی کند؛ مانند هندلرهای atexit، نهایی‌سازهای شیء، یا هر کدی که ممکن است هنگام تخلیه‌ی پرونده‌های stdout و stderr اجرا شود.

یک رویداد حسابرسی cpython._PySys_ClearAuditHooks را بدون هیچ آرگومانی ایجاد می‌کند.

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

void Py_Finalize()
قسمتی از ABI پایدار.

این نسخه‌ای سازگار با نسخه‌های پیشین از Py_FinalizeEx() است که مقدار بازگشتی را نادیده می‌گیرد.

int Py_BytesMain(int argc, char **argv)
قسمتی از ABI پایدار از نسخه‌ی 3.8.

مشابه Py_Main() است، اما argv آرایه‌ای از رشته‌های بایت است و به برنامه‌ی فراخواننده اجازه می‌دهد مرحله‌ی کدگشایی متن را به ران‌تایم سی‌پایتون واگذار کند.

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

int Py_Main(int argc, wchar_t **argv)
قسمتی از ABI پایدار.

برنامه اصلی مفسر استاندارد که یک چرخه کامل مقداردهی اولیه/نهایی‌سازی را در بر می‌گیرد، و همچنین رفتار اضافی برای پیاده‌سازی خواندن تنظیمات پیکربندی از محیط و خط فرمان و سپس اجرای __main__ مطابق با خط فرمان.

این برای برنامه‌هایی فراهم شده است که می‌خواهند از رابط کامل خط فرمان سی‌پایتون پشتیبانی کنند، نه صرفاً ران‌تایم پایتون را در برنامه‌ای بزرگ‌تر تعبیه کنند.

پارامترهای argc و argv مشابه پارامترهایی هستند که به تابع main() یک برنامه‌ی C پاس داده می‌شوند، با این تفاوت که ورودی‌های argv ابتدا با استفاده از Py_DecodeLocale() به wchar_t تبدیل می‌شوند. همچنین توجه به این نکته مهم است که ورودی‌های فهرست آرگومان‌ها ممکن است به‌گونه‌ای تغییر داده شوند که به رشته‌هایی غیر از رشته‌های پاس‌داده‌شده اشاره کنند (با این حال، محتویات رشته‌هایی که فهرست آرگومان‌ها به آن‌ها اشاره می‌کند، تغییر نمی‌کنند).

اگر فهرست آرگومان‌ها نمایانگر خط فرمان معتبر پایتون نباشد، مقدار بازگشتی 2 است و در غیر این صورت همانند Py_RunMain() است.

بر اساس APIهای پیکربندی ران‌تایم سی‌پایتون که در بخش پیکربندی ران‌تایم مستند شده‌اند (و بدون در نظر گرفتن مدیریت خطا)، Py_Main تقریباً معادل است با:

PyConfig config;
PyConfig_InitPythonConfig(&config);
PyConfig_SetArgv(&config, argc, argv);
Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);

Py_RunMain();

در استفاده‌ی معمول، یک برنامه تعبیه‌کننده این تابع را به‌جای فراخوانی مستقیم Py_Initialize()، Py_InitializeEx() یا Py_InitializeFromConfig() فراخوانی می‌کند و تمام تنظیمات همان‌گونه که در جای دیگر این مستندات توضیح داده شده است، اعمال خواهند شد. اگر این تابع در عوض پس از یک فراخوانی قبلی از API مقداردهی اولیه‌ی ران‌تایم فراخوانی شود، دقیقاً اینکه کدام تنظیمات پیکربندی محیطی و خط فرمان به‌روزرسانی خواهند شد، وابسته به نسخه است (زیرا به این بستگی دارد که کدام تنظیمات به‌درستی از این پشتیبانی می‌کنند که پس از آن‌که یک‌بار در نخستین مقداردهی اولیه‌ی ران‌تایم تنظیم شده‌اند، تغییر کنند).

int Py_FrozenMain(int argc, char **argv)

برنامه‌ی اصلی برای یک برنامه‌ی «فریزشده»ی پایتون (یک فایل اجرایی که مفسر را به همراه بایت‌کد ماژول‌های برنامه، آن‌طور که توسط ابزار freeze تولید می‌شود، تعبیه می‌کند؛ رجوع کنید به Tools/freeze).

این تابع مفسر را مقداردهی اولیه می‌کند، ماژول فریزشده‌ی با نام __main__ را ایمپورت می‌کند، و مفسر را نهایی‌سازی می‌کند. ماژول‌های فریزشده باید قبل از فراخوانی این تابع در PyImport_FrozenModules ثبت شده باشند؛ اگر __main__ در میان آن‌ها نباشد، یک خطای مهلک رخ داده است.

argc و argv رشته‌های بایتی مشابه آرگومان‌های تابع main یک برنامه‌ی C هستند و با PyConfig_SetBytesArgv() به مفسر ارسال می‌شوند. برخلاف Py_Main()، آرگومان‌ها به عنوان گزینه‌های خط فرمان پایتون تجزیه نمی‌شوند (PyConfig.parse_argv برابر با 0 است)، بنابراین همه آن‌ها در sys.argv در اختیار برنامه قرار می‌گیرند. جدا از آن، مفسر از تنظیمات پایتون استفاده می‌کند، بنابراین متغیرهای محیطی مانند PYTHONPATH لحاظ می‌شوند. هشدارهای مربوط به تنظیمات مسیر (PyConfig.pathconfig_warnings) سرکوب می‌شوند. اگر PYTHONINSPECT تنظیم شده باشد و ورودی استاندارد یک پایانه باشد، پس از اتمام __main__، یک اعلان تعاملی اجرا می‌شود، درست مانند گزینه‌ی -i.

اگر __main__ بدون استثنای مدیریت‌نشده اجرا شود، 0 را برمی‌گرداند، در غیر این صورت 1، و اگر نهایی‌سازی مفسر با شکست مواجه شود 120 (رجوع کنید به Py_FinalizeEx()). یک SystemExit مدیریت‌نشده فرایند را خاتمه می‌دهد. اگر مفسر نتواند مقداردهی اولیه شود، فرایند از طریق Py_ExitStatusException() خارج می‌شود.

در ویندوز، این تابع توسط DLL پایتون صادر نمی‌شود. در عوض، ابزار freeze پرونده‌ی Python/frozenmain.c را به همراه قلاب‌های مختص ویندوز که تابع به آن‌ها نیاز دارد، در برنامه‌ی فریزشده کامپایل می‌کند.

int Py_RunMain(void)

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

دستور (PyConfig.run_command)، اسکریپت (PyConfig.run_filename) یا ماژول (PyConfig.run_module) مشخص‌شده در خط فرمان یا در پیکربندی را اجرا می‌کند. اگر هیچ‌کدام از این مقادیر تنظیم نشده باشند، پوسته تعاملی پایتون (REPL) را با استفاده از فضای نام سراسری ماژول __main__ اجرا می‌کند.

اگر PyConfig.inspect تنظیم نشده باشد (پیش‌فرض)، مقدار بازگشتی در صورت خروج عادی مفسر (یعنی بدون ایجاد استثنا) 0 خواهد بود، در صورت وقوع استثنای مدیریت‌نشده‌ی SystemExit برابر با وضعیت خروج آن، و برای هر استثنای مدیریت‌نشده‌ی دیگر 1.

اگر PyConfig.inspect تنظیم شده باشد (مانند زمانی که از گزینه‌ی -i استفاده می‌شود)، به‌جای آنکه هنگام خروج مفسر بازگشت رخ دهد، اجرا در یک اعلان تعاملی پایتون (REPL) با استفاده از فضای نام سراسری ماژول __main__ از سر گرفته می‌شود. اگر مفسر با یک استثنا خارج شده باشد، آن استثنا بلافاصله در نشست REPL پرتاب می‌شود. سپس مقدار بازگشتی تابع بر اساس نحوه‌ی خاتمه‌ی نشست REPL تعیین می‌شود: 0، 1، یا وضعیت یک SystemExit، همان‌طور که در بالا مشخص شده است.

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

برای مثالی از یک پایتون سفارشی‌شده که همیشه در حالت ایزوله با استفاده از Py_RunMain() اجرا می‌شود، به پیکربندی پایتون مراجعه کنید.

int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void*), void *data)
این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

برای مفسر هدف interp یک کال‌بک atexit ثبت می‌کند. این مشابه Py_AtExit() است، اما یک مفسر صریح و اشاره‌گر داده برای کال‌بک دریافت می‌کند.

باید یک attached thread state برای interp وجود داشته باشد.

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

احتیاط‌های مربوط به نهایی‌سازی مفسر

در مرحله‌ی پایانی خاموش شدن مفسر، پس از تلاش برای منتظر ماندن تا خروج نخ‌های غیر دِیمِن (هرچند این فرایند ممکن است با KeyboardInterrupt قطع شود) و اجرای توابع atexit، زمان اجرا در وضعیت نهایی‌سازی قرار می‌گیرد؛ یعنی Py_IsFinalizing() و sys.is_finalizing() مقدار true را برمی‌گردانند. در این مرحله، فقط نخ نهایی‌سازی (نخی که فرایند نهایی‌سازی را آغاز کرده است؛ این نخ معمولاً نخ اصلی است) مجاز است یک وضعیت نخ را به متصل کند.

سایر نخ‌هایی که در طول نهایی‌سازی تلاش می‌کنند متصل شوند، چه به‌طور صریح (مانند طریق PyThreadState_Ensure() یا Py_END_ALLOW_THREADS) و چه به‌طور ضمنی (مانند بین دستورالعمل‌های بایت‌کد)، وارد یک وضعیت مسدودشده‌ی دائمی خواهند شد. به طور کلی، این بی‌خطر است، اما می‌تواند منجر به بن‌بست شود. به عنوان مثال، ممکن است یک نخ در حالی که قفلی را در اختیار دارد به‌طور دائم مسدود شود، به این معنی که نخ نهایی‌سازی هرگز نمی‌تواند آن قفل را به‌دست آورد.

پیش از سی‌پایتون ۳.۱۳، نخ به جای معلق ماندن خارج می‌شد که منجر به مشکلات دیگری می‌شد (یادداشت هشدار در PyThread_exit_thread() را ببینید).

زشت است؟ بله. از پایتون ۳.۱۵ به بعد، تعدادی از رابط‌های برنامه‌نویسی (API) سی وجود دارند که با جلوگیری موقت از نهایی‌سازی، اجتناب از این مشکلات را امکان‌پذیر می‌کنند:

همچنین ببینید

PEP 788 طراحی، انگیزه و دلیل منطقی این APIها را توضیح می‌دهد.

type PyInterpreterGuard
قسمتی از ABI پایدار (به‌عنوان یک ساختار مبهم) از نسخه‌ی 3.15.

یک ساختار نگهبان مفسر کدر.

با نگه‌داشتن یک نگهبان مفسر، فراخواننده می‌تواند اطمینان حاصل کند که مفسر تا زمانی که نگهبان بسته نشده است (از طریق PyInterpreterGuard_Close()) نهایی نخواهد شد.

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

نگه‌داشتن یک نگهبان برای یک مفسر شبیه به نگه‌داشتن یک ارجاع قوی به یک شیء پایتون است، با این تفاوت که نهایی‌سازی به‌طور خودکار پس از آزاد شدن همه‌ی نگهبان‌ها اتفاق نمی‌افتد: بلکه نیازمند یک فراخوانی صریح Py_EndInterpreter() است.

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

PyInterpreterGuard *PyInterpreterGuard_FromCurrent(void)
قسمتی از ABI پایدار از نسخه‌ی 3.15.

یک نگهبان نهایی‌سازی برای مفسر فعلی ایجاد کنید. این کار تا زمان بسته شدن نگهبان، از نهایی‌سازی جلوگیری می‌کند.

برای نمونه:

// Temporarily prevent finalization.
PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
if (guard == NULL) {
   // Finalization has already started or we're out of memory.
   return NULL;
}

Py_BEGIN_ALLOW_THREADS;
// Do some critical processing here. For example, we can safely acquire
// locks that might be acquired by the finalization thread.
Py_END_ALLOW_THREADS;

// Now that we're done with our critical processing, the interpreter is
// allowed to finalize again.
PyInterpreterGuard_Close(guard);

این تابع در صورت موفقیت، یک نگهبان برای مفسر فعلی برمی‌گرداند؛ و در صورت شکست، مقدار NULL را به همراه تنظیم یک استثنا برمی‌گرداند.

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

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

فراخواننده باید یک وضعیت نخ متصل‌شده را نگه دارد.

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

PyInterpreterGuard *PyInterpreterGuard_FromView(PyInterpreterView *view)
قسمتی از ABI پایدار از نسخه‌ی 3.15.

ایجاد یک نگهبان نهایی‌سازی برای یک مفسر از طریق یک نما.

این تابع در صورت موفقیت، نگهبانی را نسبت به مفسر بازنمایی‌شده توسط view برمی‌گرداند. نما پس از فراخوانی این تابع هم‌چنان معتبر است. نگهبان باید در نهایت با PyInterpreterGuard_Close() بسته شود.

اگر مفسر دیگر وجود نداشته باشد، از پیش در حال نهایی‌سازی باشد یا حافظه‌اش تمام شده باشد، این تابع NULL را بدون تنظیم استثنا برمی‌گرداند.

فراخواننده نیازی به نگه داشتن یک وضعیت نخ متصل‌شده ندارد.

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

void PyInterpreterGuard_Close(PyInterpreterGuard *guard)
قسمتی از ABI پایدار از نسخه‌ی 3.15.

بستن یک نگهبان مفسر، به مفسر اجازه می‌دهد اگر نگهبان دیگری باقی نمانده باشد، نهایی‌سازی را آغاز کند. اگر نگهبان مفسری هرگز بسته نشود، مفسر هنگام تلاش برای ورود به مرحله‌ی نهایی‌سازی، به‌طور بی‌نهایت منتظر خواهد ماند!

پس از بسته شدن نگهبان مفسر، ممکن است نتوان از آن در PyThreadState_Ensure() استفاده کرد. انجام این کار به رفتار نامشخص منجر خواهد شد.

این تابع نمی‌تواند با شکست مواجه شود و فراخواننده نیازی به نگهداری یک وضعیت نخ متصل ندارد.

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

نماهای مفسر

در برخی موارد، ممکن است دسترسی به مفسری که شاید حذف شده باشد، ضروری باشد. این کار را می‌توان با استفاده از نماهای مفسر انجام داد.

type PyInterpreterView
قسمتی از ABI پایدار (به‌عنوان یک ساختار مبهم) از نسخه‌ی 3.15.

یک نمای کدر از یک مفسر.

این یک روش نخ‌ایمن برای دسترسی به مفسری است که ممکن است در حال نهایی‌سازی بوده یا از پیش نابود شده باشد.

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

PyInterpreterView *PyInterpreterView_FromCurrent(void)
قسمتی از ABI پایدار از نسخه‌ی 3.15.

ایجاد یک نما به مفسر فعلی.

این تابع عموماً به این منظور استفاده می‌شود که در کنار PyInterpreterGuard_FromView() یا PyThreadState_EnsureFromView() به کار رود.

این تابع در صورت موفقیت، نمایی به مفسر فعلی برمی‌گرداند؛ و در صورت شکست، مقدار NULL را به همراه تنظیم یک استثنا برمی‌گرداند.

فراخواننده باید یک وضعیت نخ متصل‌شده را نگه دارد.

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

void PyInterpreterView_Close(PyInterpreterView *view)
قسمتی از ABI پایدار از نسخه‌ی 3.15.

بستن یک نمای مفسر.

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

این تابع نمی‌تواند با شکست مواجه شود و فراخواننده نیازی به نگهداری یک وضعیت نخ متصل ندارد.

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

PyInterpreterView *PyInterpreterView_FromMain(void)
قسمتی از ABI پایدار از نسخه‌ی 3.15.

ایجاد یک نما برای مفسر اصلی (اولین مفسر پیش‌فرض در یک فرایند پایتون؛ نگاه کنید به PyInterpreterState_Main()).

این تابع در صورت موفقیت، نمایی به مفسر اصلی برمی‌گرداند؛ و در صورت شکست، NULL را بدون تنظیم استثنا برمی‌گرداند. شکست نشان‌دهنده‌ی این است که حافظه‌ی فرایند تمام شده است.

هنگامی که فراخواننده نتواند یک اشاره‌گر مفسر یا نما را فراهم کند، مانند زمانی که یک کتابخانه‌ی نخ‌کشی بومی پارامتری به شکل void *arg که بتواند یک PyInterpreterGuard یا PyInterpreterView را حمل کند ارائه نمی‌دهد، از این تابع استفاده کنید. در کدهایی که از مفسرهای فرعی پشتیبانی می‌کنند، PyInterpreterView_FromCurrent() را ترجیح دهید تا نگهبان به جای مفسر اصلی، مفسر فراخواننده را پیگیری کند.

فراخواننده نیازی به نگه داشتن یک وضعیت نخ متصل‌شده ندارد.

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

پارامترهای در سطح فرایند

const char *Py_GetVersion()
قسمتی از ABI پایدار.

نسخه‌ی این مفسر پایتون را برمی‌گرداند. این رشته‌ای است که چیزی شبیه به این است

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

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

همچنین ثابت Py_Version را ببینید.

const char *Py_GetPlatform()
قسمتی از ABI پایدار.

شناسه پلتفرم را برای پلتفرم فعلی برمی‌گرداند. در یونیکس، این شناسه از نام «رسمی» سیستم‌عامل — که به حروف کوچک تبدیل شده — و به دنبال آن شماره بازنگری اصلی تشکیل می‌شود؛ برای مثال، برای Solaris 2.x که با نام SunOS 5.x نیز شناخته می‌شود، مقدار 'sunos5' است. در macOS این مقدار 'darwin' است. در ویندوز این مقدار 'win' است. رشته‌ی بازگردانده‌شده به حافظه‌ی ایستا اشاره می‌کند؛ فراخوان‌کننده نباید مقدار آن را تغییر دهد. این مقدار در کد پایتون به‌صورت sys.platform در دسترس است.

const char *Py_GetCopyright()
قسمتی از ABI پایدار.

رشته‌ی رسمی حق نشر برای نسخه‌ی فعلی پایتون را برمی‌گرداند، برای مثال

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

رشته‌ی بازگشتی به حافظه‌ی ایستا اشاره می‌کند؛ فراخوان‌کننده نباید مقدار آن را تغییر دهد. این مقدار برای کد پایتون به‌صورت sys.copyright در دسترس است.

const char *Py_GetCompiler()
قسمتی از ABI پایدار.

بازگرداندن نشانه‌ای از کامپایلر استفاده‌شده برای ساخت نسخه‌ی فعلی پایتون، داخل کروشه، برای مثال:

[GCC 2.7.2.2]

رشته‌ی بازگردانده‌شده به حافظه‌ی ایستا اشاره می‌کند؛ فراخواننده نباید مقدار آن را تغییر دهد. این مقدار به‌عنوان بخشی از متغیر sys.version برای کد پایتون در دسترس است.

const char *Py_GetBuildInfo()
قسمتی از ABI پایدار.

اطلاعات مربوط به شماره ترتیبی و تاریخ و زمان ساخت نمونه‌ی فعلی مفسر پایتون را برمی‌گرداند، برای مثال

#67, Aug  1 1997, 22:34:28

رشته‌ی بازگردانده‌شده به حافظه‌ی ایستا اشاره می‌کند؛ فراخواننده نباید مقدار آن را تغییر دهد. این مقدار به‌عنوان بخشی از متغیر sys.version برای کد پایتون در دسترس است.