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

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

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

در برنامه‌ای که پایتون را تعبیه می‌کند، تابع 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 برمی‌گرداند.

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 را برمی‌گردانند. در این نقطه، تنها نخ نهایی‌سازی که نهایی‌سازی را آغاز کرده است (معمولاً نخ اصلی) مجاز است قفل مفسر سراسری (GIL) را به دست آورد.

اگر نخی غیر از نخ نهایی‌سازی، در حین نهایی‌سازی، چه به‌طور صریح و چه به‌طور ضمنی، تلاش کند یک thread state را متصل کند، آن نخ وارد وضعیت مسدود دائمی می‌شود و تا زمان خروج برنامه در همان وضعیت باقی می‌ماند. در بیشتر موارد این بی‌ضرر است، اما اگر مرحله‌ای بعدی از نهایی‌سازی تلاش کند قفلی را که در اختیار نخ مسدود است به دست آورد یا به نحوی دیگر منتظر نخ مسدود بماند، این می‌تواند منجر به بن‌بست شود.

زشت است؟ بله. این کار از فروپاشی‌های تصادفی و/یا رد شدن غیرمنتظره‌ی نهایی‌سازی‌های C++ در بخش‌های بالاتر پشته فراخوانی جلوگیری می‌کند؛ همان مشکلاتی که در سی‌پایتون 3.13 و نسخه‌های پیشین، هنگامی که چنین نخ‌هایی در اینجا به‌اجبار خارج می‌شدند، پیش می‌آمدند. APIهای C مربوط به وضعیت نخ در ران‌تایم سی‌پایتون هیچ‌گاه در زمان اتصال وضعیت نخ هیچ‌گونه انتظاری برای گزارش یا مدیریت خطا نداشته‌اند که خروج منظم از این وضعیت را ممکن می‌ساخت. تغییر این امر نیازمند ایجاد APIهای C پایدار جدید و بازنویسی بخش عمده‌ی کدهای C در اکوسیستم سی‌پایتون برای استفاده از آن‌ها همراه با مدیریت خطا خواهد بود.

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

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

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

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

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

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

wchar_t *Py_GetProgramName()
قسمتی از ABI پایدار.

نام برنامه‌ی تنظیم‌شده با PyConfig.program_name یا مقدار پیش‌فرض را برمی‌گرداند. رشته‌ی بازگردانده‌شده به فضای ذخیره‌سازی ایستا اشاره می‌کند؛ فراخواننده نباید مقدار آن را تغییر دهد.

این تابع نباید پیش از Py_Initialize() فراخوانی شود، در غیر این صورت NULL را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: اکنون اگر پیش از Py_Initialize() فراخوانی شود، NULL را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به جای آن از PyConfig_Get("executable") (sys.executable) استفاده کنید.

wchar_t *Py_GetPrefix()
قسمتی از ABI پایدار.

پیشوند پرونده‌های نصب‌شده‌ی مستقل از پلتفرم را برمی‌گرداند. این پیشوند بر اساس تعدادی قاعده‌ی پیچیده، از نام برنامه‌ای که با PyConfig.program_name تنظیم‌شده است و برخی متغیرهای محیطی به دست می‌آید؛ برای نمونه، اگر نام برنامه '/usr/local/bin/python' باشد، پیشوند '/usr/local' است. رشته‌ی بازگردانده‌شده به حافظه‌ی ایستا اشاره می‌کند؛ فراخواننده نباید مقدار آن را تغییر دهد. این مقدار با متغیر prefix در Makefile سطح بالا و آرگومان --prefix اسکریپت configure در زمان ساخت مطابقت دارد. این مقدار برای کد پایتون به‌صورت sys.base_prefix در دسترس است. فقط روی یونیکس کاربرد دارد. همچنین تابع بعدی را ببینید.

این تابع نباید پیش از Py_Initialize() فراخوانی شود، در غیر این صورت NULL را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: اکنون اگر پیش از Py_Initialize() فراخوانی شود، NULL را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از PyConfig_Get("base_prefix") (sys.base_prefix) استفاده کنید. اگر لازم است محیط‌های مجازی مدیریت شوند، از PyConfig_Get("prefix") (sys.prefix) استفاده کنید.

wchar_t *Py_GetExecPrefix()
قسمتی از ABI پایدار.

پیشوند اجرا (exec-prefix) را برای پرونده‌های نصب‌شده‌ی وابسته به پلتفرم برمی‌گرداند. این مقدار بر اساس تعدادی قاعده‌ی پیچیده از نام برنامه‌ی تنظیم‌شده با PyConfig.program_name و برخی متغیرهای محیطی به دست می‌آید؛ برای مثال، اگر نام برنامه '/usr/local/bin/python' باشد، پیشوند اجرا '/usr/local' است. رشته‌ی بازگردانده‌شده به حافظه‌ی ایستا اشاره می‌کند؛ فراخواننده نباید مقدار آن را تغییر دهد. این مقدار با متغیر exec_prefix در Makefile سطح بالا و آرگومان --exec-prefix اسکریپت configure در زمان ساخت مطابقت دارد. این مقدار در کد پایتون به‌صورت sys.base_exec_prefix در دسترس است. این مقدار فقط در یونیکس کاربرد دارد.

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

به‌طور کلی، یک پلتفرم ترکیبی از خانواده‌های سخت‌افزاری و نرم‌افزاری است؛ برای مثال، ماشین‌های Sparc که سیستم‌عامل Solaris 2.x را اجرا می‌کنند، یک پلتفرم واحد محسوب می‌شوند، اما ماشین‌های Intel که Solaris 2.x را اجرا می‌کنند، پلتفرم دیگری هستند و ماشین‌های Intel که لینوکس را اجرا می‌کنند، پلتفرمی دیگر. نسخه‌های اصلی مختلف یک سیستم‌عامل واحد نیز به‌طور کلی پلتفرم‌های متفاوتی را تشکیل می‌دهند. سیستم‌عامل‌های غیر یونیکسی داستان دیگری دارند؛ راهبردهای نصب در این سیستم‌ها چنان متفاوت است که پیشوند و پیشوند اجرا بی‌معنا هستند و روی رشته خالی تنظیم می‌شوند. توجه داشته باشید که پرونده‌های بایت‌کد کامپایل‌شده پایتون مستقل از پلتفرم هستند (اما از نسخه پایتونی که آن‌ها را کامپایل کرده است، مستقل نیستند!).

مدیران سیستم می‌دانند چگونه برنامه‌های mount یا automount را پیکربندی کنند تا /usr/local میان پلتفرم‌ها به اشتراک گذاشته شود، در حالی که /usr/local/plat برای هر پلتفرم یک سامانه فایل‌بندی متفاوت باشد.

این تابع نباید پیش از Py_Initialize() فراخوانی شود، در غیر این صورت NULL را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: اکنون اگر پیش از Py_Initialize() فراخوانی شود، NULL را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از PyConfig_Get("base_exec_prefix") (sys.base_exec_prefix) استفاده کنید. اگر لازم باشد محیط‌های مجازی مدیریت شوند، از PyConfig_Get("exec_prefix") (sys.exec_prefix) استفاده کنید.

wchar_t *Py_GetProgramFullPath()
قسمتی از ABI پایدار.

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

این تابع نباید پیش از Py_Initialize() فراخوانی شود، در غیر این صورت NULL را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: اکنون اگر پیش از Py_Initialize() فراخوانی شود، NULL را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به جای آن از PyConfig_Get("executable") (sys.executable) استفاده کنید.

wchar_t *Py_GetPath()
قسمتی از ABI پایدار.

مسیر جستجوی پیش‌فرض ماژول را برمی‌گرداند؛ این مسیر از نام برنامه (که توسط PyConfig.program_name تنظیم می‌شود) و برخی متغیرهای محیطی محاسبه می‌شود. رشته‌ی بازگردانده‌شده از مجموعه‌ای از نام پوشه‌ها تشکیل شده است که با نویسه‌ی جداکننده‌ای وابسته به پلتفرم از هم جدا شده‌اند. نویسه‌ی جداکننده در یونیکس و مک‌اواس ':' و در ویندوز ';' است. رشته‌ی بازگردانده‌شده به داخل ذخیره‌گاه ایستا اشاره می‌کند؛ فراخوان‌کننده نباید مقدار آن را تغییر دهد. فهرست sys.path هنگام راه‌اندازی مفسر با این مقدار مقداردهی اولیه می‌شود؛ این فهرست می‌تواند (و معمولاً نیز چنین می‌شود) بعداً برای تغییر مسیر جستجو جهت بارگذاری ماژول‌ها تغییر کند.

این تابع نباید پیش از Py_Initialize() فراخوانی شود، در غیر این صورت NULL را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: اکنون اگر پیش از Py_Initialize() فراخوانی شود، NULL را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به جای آن از PyConfig_Get("module_search_paths") (sys.path) استفاده کنید.

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 حذف خواهد شد.

wchar_t *Py_GetPythonHome()
قسمتی از ABI پایدار.

بازگرداندن «home» پیش‌فرض، یعنی مقداری که توسط PyConfig.home تنظیم شده است، یا مقدار متغیر محیطی PYTHONHOME در صورتی که تنظیم شده باشد.

این تابع نباید پیش از Py_Initialize() فراخوانی شود، در غیر این صورت NULL را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: اکنون اگر پیش از Py_Initialize() فراخوانی شود، NULL را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از PyConfig_Get("home") یا متغیر محیطی PYTHONHOME استفاده کنید.