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

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

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

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

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

نکته

با وجود شباهت ظاهری آن‌ها به برخی از توابع فهرست‌شده در بالا، توابع زیر پیش از مقداردهی اولیه‌ی مفسر نباید فراخوانی شوند: Py_EncodeLocale()، PyEval_InitThreads() و Py_RunMain().

متغیرهای پیکربندی سراسری

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

هنگامی که یک پرچم توسط گزینه‌ای تنظیم می‌شود، مقدار پرچم برابر با تعداد دفعاتی است که آن گزینه مشخص شده است. برای مثال، -b مقدار Py_BytesWarningFlag را روی ۱ تنظیم می‌کند و -bb مقدار Py_BytesWarningFlag را روی ۲ تنظیم می‌کند.

int Py_BytesWarningFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن، باید از تنظیم PyConfig.bytes_warning استفاده کرد؛ به پیکربندی مقدار‌دهی اولیه پایتون مراجعه کنید.

هنگام مقایسه‌ی bytes یا bytearray با str، یا bytes با int هشدار صادر می‌کند. در صورت بزرگ‌تر یا مساوی 2 بودن، خطا صادر می‌کند.

توسط گزینه‌ی -b تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_DebugFlag

این API برای سازگاری با نسخه‌های قبلی حفظ شده است: به جای آن باید PyConfig.parser_debug را تنظیم کنید؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

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

توسط گزینه‌ی -d و متغیر محیطی PYTHONDEBUG تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_DontWriteBytecodeFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید از تنظیم PyConfig.write_bytecode استفاده شود؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

اگر روی مقدار غیرصفر تنظیم شود، پایتون هنگام ایمپورت ماژول‌های منبع تلاش نمی‌کند پرونده‌های .pyc را بنویسد.

توسط گزینه‌ی -B و متغیر محیطی PYTHONDONTWRITEBYTECODE تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_FrozenFlag

این API برای سازگاری با نسخه‌های قبلی حفظ شده است: به جای آن باید PyConfig.pathconfig_warnings را تنظیم کنید؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

پرچم خصوصی استفاده‌شده توسط برنامه‌های _freeze_module و frozenmain.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_HashRandomizationFlag

این API برای سازگاری با نسخه‌های پیشین نگه داشته شده است: به جای آن باید از تنظیم PyConfig.hash_seed و PyConfig.use_hash_seed استفاده شود؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

اگر متغیر محیطی PYTHONHASHSEED به یک رشته‌ی غیرخالی تنظیم شده باشد، روی 1 تنظیم می‌شود.

اگر پرچم ناصفر باشد، متغیر محیطی PYTHONHASHSEED برای مقداردهی اولیه‌ی بذر هش مخفی خوانده می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_IgnoreEnvironmentFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.use_environment تنظیم شود؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

نادیده گرفتن تمام متغیرهای محیطی PYTHON*، مانند PYTHONPATH و PYTHONHOME، که ممکن است تنظیم شده باشند.

توسط گزینه‌های -E و -I تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_InspectFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید از تنظیم PyConfig.inspect استفاده کرد؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

وقتی یک اسکریپت به‌عنوان آرگومان اول داده شود یا از گزینه‌ی -c استفاده شود، پس از اجرای اسکریپت یا دستور وارد حالت تعاملی می‌شود، حتی زمانی که به نظر نمی‌رسد sys.stdin یک پایانه باشد.

تنظیم می‌شود توسط گزینه‌ی -i و متغیر محیطی PYTHONINSPECT.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_InteractiveFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.interactive را تنظیم کنید؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

با گزینه‌ی -i تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_IsolatedFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید از تنظیم PyConfig.isolated استفاده شود؛ به پیکربندی مقدار‌دهی اولیه پایتون مراجعه کنید.

پایتون را در حالت ایزوله اجرا کنید. در حالت ایزوله، sys.path نه پوشه‌ی اسکریپت و نه پوشه‌ی site-packages کاربر را در بر می‌گیرد.

توسط گزینه‌ی -I تنظیم می‌شود.

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

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_LegacyWindowsFSEncodingFlag

این API برای سازگاری با نسخه‌های قبلی حفظ شده است: به جای آن باید PyPreConfig.legacy_windows_fs_encoding را تنظیم کرد؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

اگر پرچم نا‌صفر باشد، به‌جای کدگذاری UTF-8 با هندلر خطای surrogatepass، از کدگذاری mbcs با هندلر خطای replace برای filesystem encoding and error handler استفاده می‌شود.

اگر متغیر محیطی PYTHONLEGACYWINDOWSFSENCODING به یک رشته غیرخالی تنظیم شده باشد، به 1 تنظیم می‌شود.

برای جزئیات بیشتر به PEP 529 مراجعه کنید.

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

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_LegacyWindowsStdioFlag

این API برای سازگاری با گذشته حفظ شده است: به جای آن باید PyConfig.legacy_windows_stdio تنظیم شود؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

اگر پرچم نا‌صفر باشد، برای جریان‌های استاندارد sys به‌جای io._WindowsConsoleIO از io.FileIO استفاده می‌شود.

اگر متغیر محیطی PYTHONLEGACYWINDOWSSTDIO روی یک رشته‌ی غیرخالی تنظیم شده باشد، روی 1 تنظیم می‌شود.

برای جزئیات بیشتر به PEP 528 مراجعه کنید.

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

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_NoSiteFlag

این API برای سازگاری به عقب نگه داشته شده است: به جای آن باید PyConfig.site_import را تنظیم کنید؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

ایمپورت ماژول site و دستکاری‌های وابسته به site در sys.path که این ایمپورت به همراه دارد را غیرفعال می‌کند. همچنین اگر site بعداً به‌طور صریح ایمپورت شود، این دستکاری‌ها را غیرفعال می‌کند (اگر می‌خواهید این دستکاری‌ها انجام شوند، site.main() را فراخوانی کنید).

توسط گزینه‌ی -S تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_NoUserSiteDirectory

این API برای سازگاری با نسخه‌های قبلی حفظ شده است: به جای آن باید PyConfig.user_site_directory را تنظیم کنید؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

پوشه‌ی site-packages کاربر را به sys.path اضافه نکنید.

با گزینه‌های -s و -I و متغیر محیطی PYTHONNOUSERSITE تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_OptimizeFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.optimization_level را تنظیم کرد؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

توسط گزینه‌ی -O و متغیر محیطی PYTHONOPTIMIZE تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_QuietFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.quiet را تنظیم کنید؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

پیام‌های حق نشر و نسخه را حتی در حالت تعاملی نمایش ندهید.

توسط گزینه‌ی -q تنظیم می‌شود.

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

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_UnbufferedStdioFlag

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.buffered_stdio را تنظیم کنید؛ به پیکربندی راه‌اندازی پایتون مراجعه کنید.

جریان‌های stdout و stderr را مجبور کنید که بدون بافر باشند.

با گزینه‌ی -u و متغیر محیطی PYTHONUNBUFFERED تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

int Py_VerboseFlag

این API برای سازگاری با نسخه‌های قبلی نگه داشته شده است: به جای آن باید PyConfig.verbose را تنظیم کنید؛ برای جزئیات به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

هر بار که یک ماژول مقداردهی اولیه می‌شود، پیامی چاپ می‌کند که نشان می‌دهد ماژول از کدام مکان (نام پرونده یا ماژول توکار) بارگذاری شده است. اگر بزرگ‌تر یا مساوی 2 باشد، برای هر پرونده‌ای که هنگام جستجوی یک ماژول بررسی می‌شود پیامی چاپ می‌کند. همچنین اطلاعاتی درباره پاک‌سازی ماژول‌ها هنگام خروج ارائه می‌دهد.

با گزینه‌ی -v و متغیر محیطی PYTHONVERBOSE تنظیم می‌شود.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.15 حذف شده است.

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

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 توضیح داده‌شده است.

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

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_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.

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

void Py_SetProgramName(const wchar_t *name)
قسمتی از ABI پایدار.

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.program_name را تنظیم کنید؛ به پیکربندی مقدار‌دهی اولیه پایتون مراجعه کنید.

این تابع باید پیش از فراخوانی Py_Initialize() برای نخستین بار (در صورت فراخوانی) فراخوانی شود. این تابع مقدار آرگومان argv[0] تابع main() برنامه را (که به نویسه‌های پهن تبدیل شده است) به مفسر اعلام می‌کند. این مقدار توسط برخی دیگر از توابع زیر برای یافتن کتابخانه‌های زمان اجرای پایتون نسبت به فایل اجرایی مفسر استفاده می‌شود. مقدار پیش‌فرض 'python' است. آرگومان باید به یک رشته‌ی نویسه پهنِ ختم‌شده به صفر در حافظه ایستا اشاره کند که محتویات آن در طول اجرای برنامه تغییر نخواهد کرد. هیچ کدی در مفسر پایتون محتویات این حافظه را تغییر نخواهد داد.

برای کدگشایی یک رشته بایتی و به‌دست آوردن یک رشته‌ی wchar_t* از Py_DecodeLocale() استفاده کنید.

منسوخ شده از نسخه‌ی 3.11، در نسخه‌ی 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 برای کد پایتون در دسترس است.

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

این API برای سازگاری با نسخه‌های پیشین نگه داشته شده است: به جای آن باید PyConfig.argv، PyConfig.parse_argv و PyConfig.safe_path تنظیم شوند؛ به پیکربندی راه‌اندازی پایتون مراجعه کنید.

مقدار sys.argv را بر اساس argc و argv تنظیم می‌کند. این پارامترها مشابه پارامترهایی هستند که به تابع main() برنامه پاس داده می‌شوند، با این تفاوت که نخستین ورودی باید به پرونده‌ی اسکریپتی که قرار است اجرا شود اشاره کند، نه به پرونده‌ی اجرایی میزبان مفسر پایتون. اگر اسکریپتی برای اجرا وجود نداشته باشد، نخستین ورودی در argv می‌تواند یک رشته‌ی خالی باشد. اگر این تابع نتواند sys.argv را مقداردهی اولیه کند، یک وضعیت مهلک با استفاده از Py_FatalError() اعلام می‌شود.

اگر updatepath صفر باشد، تمام کاری که تابع انجام می‌دهد همین است. اگر updatepath غیرصفر باشد، تابع همچنین sys.path را مطابق الگوریتم زیر تغییر می‌دهد:

  • اگر نام یک اسکریپت موجود در argv[0] ارسال شود، مسیر مطلق پوشه‌ای که اسکریپت در آن قرار دارد به ابتدای sys.path اضافه می‌شود.

  • در غیر این صورت (یعنی اگر argc برابر 0 باشد یا argv[0] به نام یک پرونده‌ی موجود اشاره نکند)، یک رشته‌ی خالی به ابتدای sys.path افزوده می‌شود، که معادل افزودن پوشه‌ی کاری جاری (".") به ابتدای آن است.

برای کدگشایی یک رشته بایتی و به‌دست آوردن یک رشته‌ی wchar_t* از Py_DecodeLocale() استفاده کنید.

همچنین اعضای PyConfig.orig_argv و PyConfig.argv از پیکربندی مقداردهی اولیه پایتون را ببینید.

نکته

توصیه می‌شود برنامه‌هایی که مفسر پایتون را برای اهدافی غیر از اجرای یک اسکریپت واحد درون‌سازی می‌کنند، مقدار 0 را به‌عنوان updatepath عبور دهند و در صورت تمایل، خودشان sys.path را به‌روزرسانی کنند. به CVE 2008-5983 مراجعه کنید.

در نسخه‌های پیش از 3.1.3، می‌توانید همان اثر را با حذف دستی نخستین عنصر sys.path پس از فراخوانی PySys_SetArgv() به دست آورید، برای مثال با استفاده از:

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

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

منسوخ شده از نسخه‌ی 3.11، در نسخه‌ی 3.15 حذف شده است.

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

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.argv و PyConfig.parse_argv را تنظیم کرد؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

این تابع مانند PySys_SetArgvEx() با updatepath برابر با 1 کار می‌کند، مگر آنکه مفسر python با گزینه‌ی -I راه‌اندازی شده باشد.

برای کدگشایی یک رشته بایتی و به‌دست آوردن یک رشته‌ی wchar_t* از Py_DecodeLocale() استفاده کنید.

همچنین اعضای PyConfig.orig_argv و PyConfig.argv از پیکربندی مقداردهی اولیه پایتون را ببینید.

تغییر یافته در نسخه‌ی 3.4: مقدار updatepath به -I بستگی دارد.

منسوخ شده از نسخه‌ی 3.11، در نسخه‌ی 3.15 حذف شده است.

void Py_SetPythonHome(const wchar_t *home)
قسمتی از ABI پایدار.

این API برای سازگاری با نسخه‌های پیشین حفظ شده است: به جای آن باید PyConfig.home را تنظیم کرد؛ به پیکربندی مقداردهی اولیه پایتون مراجعه کنید.

پوشه‌ی «home» پیش‌فرض را تنظیم می‌کند، یعنی مکان کتابخانه‌های استاندارد پایتون. برای معنای رشته‌ی آرگومان، PYTHONHOME را ببینید.

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

برای کدگشایی یک رشته بایتی و به‌دست آوردن یک رشته‌ی wchar_t* از Py_DecodeLocale() استفاده کنید.

منسوخ شده از نسخه‌ی 3.11، در نسخه‌ی 3.15 حذف شده است.