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

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

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

در برنامه‌ای که پایتون را تعبیه می‌کند، تابع 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.16 حذف شده است.

int Py_DebugFlag

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

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

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

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

int Py_DontWriteBytecodeFlag

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

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

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

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

int Py_FrozenFlag

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

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

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

int Py_HashRandomizationFlag

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

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

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

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

int Py_IgnoreEnvironmentFlag

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

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

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

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

int Py_InspectFlag

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

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

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

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

int Py_InteractiveFlag

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

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

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

int Py_IsolatedFlag

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

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

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

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

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

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.16 حذف شده است.

int Py_LegacyWindowsStdioFlag

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

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

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

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

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

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

int Py_NoSiteFlag

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

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

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

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

int Py_NoUserSiteDirectory

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

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

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

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

int Py_OptimizeFlag

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

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

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

int Py_QuietFlag

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

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

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

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

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

int Py_UnbufferedStdioFlag

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

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

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

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

int Py_VerboseFlag

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

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

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

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

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

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: This function no longer returns true until initialization has fully completed, including import of the site module. Previously it could return true while Py_Initialize() was still running.

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.

Cautions regarding interpreter finalization

In the late stage of interpreter shutdown, after attempting to wait for non-daemon threads to exit (though this can be interrupted by KeyboardInterrupt) and running the atexit functions, the runtime is marked as finalizing, meaning that Py_IsFinalizing() and sys.is_finalizing() return true. At this point, only the finalization thread (the thread that initiated finalization; this is typically the main thread) is allowed to attach a thread state.

Other threads that attempt to attach during finalization, either explicitly (such as via PyThreadState_Ensure() or Py_END_ALLOW_THREADS) or implicitly (such as in-between bytecode instructions), will enter a permanently blocked state. Generally, this is harmless, but this can result in deadlocks. For example, a thread may be permanently blocked while holding a lock, meaning that the finalization thread can never acquire that lock.

Prior to CPython 3.13, the thread would exit instead of hanging, which led to other issues (see the warning note at PyThread_exit_thread()).

Gross? Yes. Starting in Python 3.15, there are a number of C APIs that make it possible to avoid these issues by temporarily preventing finalization:

همچنین ملاحظه نمائید

PEP 788 explains the design, motivation and rationale for these APIs.

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

An opaque interpreter guard structure.

By holding an interpreter guard, the caller can ensure that the interpreter will not finalize until the guard is closed (through PyInterpreterGuard_Close()).

When a guard is held, a thread attempting to finalize the interpreter will block until the guard is closed before starting finalization. After finalization has started, threads are forever unable to acquire guards for that interpreter. This means that if you forget to close an interpreter guard, the process will permanently hang during finalization!

Holding a guard for an interpreter is similar to holding a strong reference to a Python object, except finalization does not happen automatically after all guards are released: it requires an explicit Py_EndInterpreter() call.

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

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

Create a finalization guard for the current interpreter. This will prevent finalization until the guard is closed.

For example:

// 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);

On success, this function returns a guard for the current interpreter; on failure, it returns NULL with an exception set.

This function will fail only if the current interpreter has already started finalizing, or if the process is out of memory.

The guard pointer returned by this function must be eventually closed with PyInterpreterGuard_Close(); failing to do so will result in the Python process infinitely hanging.

The caller must hold an attached thread state.

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

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

Create a finalization guard for an interpreter through a view.

On success, this function returns a guard to the interpreter represented by view. The view is still valid after calling this function. The guard must eventually be closed with PyInterpreterGuard_Close().

If the interpreter no longer exists, is already finalizing, or out of memory, then this function returns NULL without setting an exception.

The caller does not need to hold an attached thread state.

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

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

Close an interpreter guard, allowing the interpreter to start finalization if no other guards remain. If an interpreter guard is never closed, the interpreter will infinitely wait when trying to enter finalization!

After an interpreter guard is closed, it may not be used in PyThreadState_Ensure(). Doing so will result in undefined behavior.

This function cannot fail, and the caller doesn't need to hold an attached thread state.

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

Interpreter views

In some cases, it may be necessary to access an interpreter that may have been deleted. This can be done using interpreter views.

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

An opaque view of an interpreter.

This is a thread-safe way to access an interpreter that may have be finalizing or already destroyed.

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

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

Create a view to the current interpreter.

This function is generally meant to be used alongside PyInterpreterGuard_FromView() or PyThreadState_EnsureFromView().

On success, this function returns a view to the current interpreter; on failure, it returns NULL with an exception set.

The caller must hold an attached thread state.

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

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

Close an interpreter view.

If an interpreter view is never closed, the view's memory will never be freed, but there are no other consequences. (In contrast, forgetting to close a guard will infinitely hang the main thread during finalization.)

This function cannot fail, and the caller doesn't need to hold an attached thread state.

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

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

Create a view for the main interpreter (the first and default interpreter in a Python process; see PyInterpreterState_Main()).

On success, this function returns a view to the main interpreter; on failure, it returns NULL without an exception set. Failure indicates that the process is out of memory.

Use this function when an interpreter pointer or view cannot be supplied by the caller, such as when a native threading library does not provide a void *arg parameter that could carry a PyInterpreterGuard or PyInterpreterView. In code that supports subinterpreters, prefer PyInterpreterView_FromCurrent() so the guard tracks the calling interpreter rather than the main one.

The caller does not need to hold an attached thread state.

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

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

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

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

This function should be called before Py_Initialize() is called for the first time, if it is called at all. It tells the interpreter the value of the argv[0] argument to the main() function of the program (converted to wide characters). This is used by some other functions below to find the Python run-time libraries relative to the interpreter executable. The default value is 'python'. The argument should point to a zero-terminated wide character string in static storage whose contents will not change for the duration of the program's execution. No code in the Python interpreter will change the contents of this storage.

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

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

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.16 حذف شده است.

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.16 حذف شده است.

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

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

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

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

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

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