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

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

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

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

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

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.

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

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 برای کد پایتون در دسترس است.