اشیاء ماژول¶

PyTypeObject PyModule_Type¶: قسمتی از ABI پایدار.
این نمونه از PyTypeObject معرف نوع ماژول پایتون است. این نوع به برنامه‌های پایتون به‌صورت types.ModuleType ارائه می‌شود.

int PyModule_Check(PyObject *p)¶: اگر p یک شیء ماژول یا زیرنوعی از یک شیء ماژول باشد، مقدار true برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyModule_CheckExact(PyObject *p)¶: اگر p یک شیء ماژول باشد، اما زیرنوعی از PyModule_Type نباشد، مقدار درست را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyObject *PyModule_NewObject(PyObject *name)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.7.

یک شیء ماژول جدید با module.__name__ تنظیم‌شده بر name برمی‌گرداند. ویژگی‌های __name__، __doc__، __package__ و __loader__ ماژول پر می‌شوند (همه به‌جز __name__ بر None تنظیم می‌شوند). تنظیم ویژگی __file__ بر عهده‌ی فراخواننده است.

در صورت خطا، NULL به همراه استثنای تنظیم‌شده برمی‌گرداند.

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

تغییر یافته در نسخه‌ی 3.4: __package__ و __loader__ اکنون به None تنظیم می‌شوند.

PyObject *PyModule_New(const char *name)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
مشابه PyModule_NewObject()، اما نام به جای یک شیء یونیکد، یک رشته کدگذاری‌شده با UTF-8 است.

PyObject *PyModule_GetDict(PyObject *module)¶

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار.

شیء دیکشنری‌ای را که فضای نام module را پیاده‌سازی می‌کند برمی‌گرداند؛ این شیء همان ویژگی __dict__ شیء ماژول است. اگر module یک شیء ماژول (یا زیرنوعی از شیء ماژول) نباشد، SystemError برخاسته می‌شود و NULL بازگردانده می‌شود.

توصیه می‌شود ماژول‌های توسعه‌ای به‌جای دست‌کاری مستقیم __dict__ یک ماژول، از سایر توابع PyModule_* و PyObject_* استفاده کنند.

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

PyObject *PyModule_GetNameObject(PyObject *module)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.7.
مقدار __name__ module را برمی‌گرداند. اگر ماژول آن را ارائه نکند یا اگر رشته نباشد، استثنای SystemError مطرح می‌شود و NULL برگردانده می‌شود.

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

const char *PyModule_GetName(PyObject *module)¶

قسمتی از ABI پایدار.

مشابه PyModule_GetNameObject() است، اما نام را با کدگذاری 'utf-8' برمی‌گرداند.

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

PyModuleDef *PyModule_GetDef(PyObject *module)¶

قسمتی از ABI پایدار.

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

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

PyObject *PyModule_GetFilenameObject(PyObject *module)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
نام پرونده‌ای را که module از آن بارگذاری شده است، با استفاده از ویژگی __file__ مربوط به module برمی‌گرداند. اگر این ویژگی تعریف نشده باشد یا رشته نباشد، استثنای SystemError را مطرح می‌کند و NULL برمی‌گرداند؛ در غیر این صورت، ارجاعی به یک شیء یونیکد برمی‌گرداند.

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

const char *PyModule_GetFilename(PyObject *module)¶

قسمتی از ABI پایدار.

مشابه PyModule_GetFilenameObject() است، اما نام پرونده را با کدگذاری 'utf-8' برمی‌گرداند.

بافر بازگشتی تنها تا زمانی معتبر است که ویژگی __file__ ماژول دوباره مقداردهی شود یا ماژول نابود شود.

منسوخ شده از نسخه‌ی 3.2: PyModule_GetFilename() برای نام‌های پرونده‌ی غیرقابل کدگذاری، استثنای UnicodeEncodeError را مطرح می‌کند؛ به‌جای آن از PyModule_GetFilenameObject() استفاده کنید.

تعریف ماژول¶

ماژول‌های ایجادشده با استفاده از API زبان C معمولاً با استفاده از آرایه‌ای از ساختارهای PySlot تعریف می‌شوند که «توضیحی» درباره‌ی نحوه‌ی ایجاد یک ماژول ارائه می‌دهد. برای اطلاعات بیشتر درباره‌ی جایگاه‌ها به‌طور کلی، به جایگاه‌های تعریف مراجعه کنید.

تغییر یافته در نسخه‌ی 3.15: پیش از این، برای تعریف ماژول‌ها ساختار PyModuleDef ضروری بود. روش قدیمی‌تر تعریف ماژول‌ها همچنان در دسترس است: اگر قصد دارید از نسخه‌های قبلی پایتون پشتیبانی کنید، به بخش ساختار تعریف ماژول یا نسخه‌های قبلی این مستندات مراجعه کنید.

آرایه‌ی جایگاه‌ها معمولاً برای تعریف شیء ماژول «اصلی» یک ماژول توسعه‌ای استفاده می‌شود (برای جزئیات به تعریف ماژول‌های توسعه‌ای مراجعه کنید). همچنین می‌توان از آن برای ایجاد پویای ماژول‌های توسعه‌ای استفاده کرد.

مگر اینکه جور دیگری مشخص شده باشد، ممکن است یک شناسه‌ی جایگاه در یک آرایه از جایگاه‌ها تکرار نشود.

جایگاه‌های فراداده¶

Py_mod_name¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

شناسه‌ی جایگاه برای نام ماژول جدید، به شکل یک const char * کدگذاری‌شده با UTF-8 و پایان‌یافته با NUL.

توجه داشته باشید که ماژول‌ها معمولاً با استفاده از یک ModuleSpec ایجاد می‌شوند و در این صورت، نام مشخصات به‌جای Py_mod_name استفاده خواهد شد. با این حال، همچنان توصیه می‌شود برای اهداف درون‌نگری و اشکال‌زدایی، این جایگاه را بگنجانید.

اضافه شده در نسخه‌ی 3.15: برای پشتیبانی از نسخه‌های قبلی، به‌جای آن از PyModuleDef.m_name استفاده کنید.

Py_mod_doc¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

شناسه‌ی شکاف برای رشته مستند ماژول جدید، به شکل یک const char * با انتهای تهی و کدگذاری‌شده با UTF-8.

معمولاً این مقدار روی متغیری تنظیم می‌شود که با PyDoc_STRVAR ایجاد شده است.

اضافه شده در نسخه‌ی 3.15: برای پشتیبانی از نسخه‌های قبلی، به‌جای آن از PyModuleDef.m_doc استفاده کنید.

جایگاه‌های ویژگی¶

Py_mod_abi¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

شناسه‌ی جایگاه که مقدار آن به ساختار PyABIInfo اشاره می‌کند و توصیف‌کننده‌ی ABI است که افزونه از آن استفاده می‌کند.

یک متغیر مناسب PyABIInfo را می‌توان با استفاده از ماکروی PyABIInfo_VAR تعریف کرد، مانند:

PyABIInfo_VAR(abi_info);

static PySlot mymodule_slots[] = {
   PySlot_DATA(Py_mod_abi, &abi_info),
   ...
};

هنگام ایجاد یک ماژول، پایتون مقدار این جایگاه را با استفاده از PyABIInfo_Check() بررسی می‌کند.

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

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

Py_mod_multiple_interpreters¶

قسمتی از ABI پایدار از نسخه‌ی 3.12.

Slot ID که مقدار آن یکی از موارد زیر است:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶: این ماژول از ایمپورت شدن در زیرمفسرها (subinterpreters) پشتیبانی نمی‌کند.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED¶: این ماژول از ایمپورت شدن در زیرمفسرها پشتیبانی می‌کند، اما تنها زمانی که آن‌ها قفل مفسر سراسری (GIL) مفسر اصلی را به اشتراک بگذارند. (به جداسازی ماژول‌های توسعه مراجعه کنید.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED¶: این ماژول از ایمپورت شدن در زیرمفسرها پشتیبانی می‌کند، حتی زمانی که آن‌ها قفل مفسر سراسری خود را دارند. (به جداسازی ماژول‌های توسعه مراجعه کنید.)

این جایگاه تعیین می‌کند که آیا ایمپورت کردن این ماژول در یک زیرمفسر شکست می‌خورد یا خیر.

اگر Py_mod_multiple_interpreters مشخص نشده باشد، سازوکار ایمپورت به‌صورت پیش‌فرض از Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED استفاده می‌کند.

به دلایل تاریخی، مقادیر به عنوان اشاره‌گر (void *) اعلام می‌شوند. هنگام استفاده از آرایه‌های PySlot، از PySlot_DATA برای Py_mod_multiple_interpreters استفاده کنید:

PySlot_DATA(Py_mod_multiple_interpreters,
            Py_MOD_PER_INTERPRETER_GIL_SUPPORTED)

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

Py_mod_gil¶

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

Slot ID که مقدار آن یکی از موارد زیر است:

Py_MOD_GIL_USED¶: این ماژول به وجود قفل مفسر سراسری (GIL) وابسته است و ممکن است بدون همگام‌سازی به وضعیت سراسری دسترسی داشته باشد.

Py_MOD_GIL_NOT_USED¶: اجرای این ماژول بدون قفل مفسر سراسریِ فعال، ایمن است.

این جایگاه توسط ساخت‌های پایتون که با --disable-gil پیکربندی نشده‌اند نادیده گرفته می‌شود. در غیر این صورت، تعیین می‌کند که آیا ایمپورت کردن این ماژول باعث می‌شود قفل مفسر سراسری (GIL) به‌طور خودکار فعال شود یا خیر. برای جزئیات بیشتر به سی‌پایتون نخ‌آزاد مراجعه کنید.

اگر Py_mod_gil مشخص نشده باشد، سازوکار ایمپورت به‌طور پیش‌فرض از Py_MOD_GIL_USED استفاده می‌کند.

به دلایل تاریخی، مقادیر به عنوان اشاره‌گر (void *) اعلام می‌شوند. هنگام استفاده از آرایه‌های PySlot، از PySlot_DATA برای Py_mod_gil استفاده کنید:

PySlot_DATA(Py_mod_gil, Py_MOD_GIL_NOT_USED)

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

جایگاه‌های ایجاد و راه‌اندازی اولیه¶

Py_mod_create¶

قسمتی از ABI پایدار از نسخه‌ی 3.5.

Slot ID برای تابعی که خود شیء ماژول را ایجاد می‌کند. این تابع باید امضای زیر را داشته باشد:

PyObject *create_module(PyObject *spec, PyModuleDef *def)¶

این تابع با موارد زیر فراخوانی خواهد شد:

spec: یک شیء شبیه به ModuleSpec، به این معنا که هر ویژگی تعریف‌شده برای importlib.machinery.ModuleSpec دارای معناشناسی منطبق است. با این حال، ممکن است هر یک از ویژگی‌ها وجود نداشته باشند.
def: مقدار NULL، یا تعریف ماژول در صورتی که ماژول از یکی از آن‌ها ایجاد شده باشد.

این تابع باید یک شیء ماژول جدید برگرداند، یا یک خطا را تنظیم کرده و NULL را برگرداند.

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

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

هیچ الزامی وجود ندارد که شیء برگردانده‌شده نمونه‌ای از PyModule_Type باشد. با این حال، برخی از جایگاه‌ها ممکن است فقط با نمونه‌های PyModule_Type استفاده شوند؛ به ویژه:

Py_mod_exec،
جایگاه‌های حالت ماژول (Py_mod_state_*)،
Py_mod_token.

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

تغییر یافته در نسخه‌ی 3.15: آرگومان slots ممکن است یک شیء شبیه به ModuleSpec باشد، نه یک نمونه‌ی واقعی ModuleSpec. توجه داشته باشید که نسخه‌های قبلی سی‌پایتون این موضوع را اعمال نمی‌کردند.

آرگومان def اکنون ممکن است NULL باشد، زیرا ماژول‌ها لزوماً از تعاریف ساخته نمی‌شوند.

Py_mod_exec¶

قسمتی از ABI پایدار از نسخه‌ی 3.5.

Slot ID برای تابعی که ماژول را execute (اجرا) یا مقداردهی اولیه می‌کند. این تابع معادل اجرای کد یک ماژول پایتون عمل می‌کند: معمولاً کلاس‌ها و ثابت‌ها را به ماژول اضافه می‌کند. امضای تابع به صورت زیر است:

int exec_module(PyObject *module)¶

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

به منظور سازگاری با نسخه‌های قبل، آرایه‌ی PyModuleDef.m_slots ممکن است حاوی چندین جایگاه Py_mod_exec باشد؛ این موارد به ترتیبی که در آرایه ظاهر می‌شوند پردازش خواهند شد. جاهای دیگر (یعنی در آرگومان‌های PyModule_FromSlotsAndSpec() و مقادیر بازگشتی PyModExport_<name>)، تکرار جایگاه مجاز نیست.

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

تغییر یافته در نسخه‌ی 3.15: جایگاه‌های تکراری Py_mod_exec مجاز نیستند، مگر در PyModuleDef.m_slots.

Py_mod_methods¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID برای جدولی از توابع در سطح ماژول، به صورت آرایه‌ای از مقادیر PyMethodDef که به عنوان آرگومان functions برای PyModule_AddFunctions() مناسب است.

مانند سایر شناسه‌های جایگاه، یک آرایه‌ی جایگاه ممکن است فقط حاوی یک ورودی Py_mod_methods باشد. برای افزودن توابع از چندین آرایه‌ی PyMethodDef، تابع PyModule_AddFunctions() را در تابع Py_mod_exec فراخوانی کنید.

این جدول باید به صورت ایستا تخصیص داده شود (یا به نحوی تضمین شود که عمر آن بیشتر از شیء ماژول است).

اضافه شده در نسخه‌ی 3.15: برای پشتیبانی از نسخه‌های قبلی، به‌جای آن از PyModuleDef.m_methods استفاده کنید.

وضعیت ماژول¶

ماژول‌های توسعه‌ای می‌توانند وضعیت ماژول داشته باشند؛ تکه‌ای از حافظه که هنگام ایجاد ماژول تخصیص داده می‌شود و زمانی که شیء ماژول زدوده‌سازی می‌شود، آزاد می‌گردد. وضعیت ماژول با استفاده از جایگاه‌های اختصاصی مشخص می‌شود.

یک کاربرد رایج وضعیت ماژول، ذخیره‌سازی یک نوع استثنا -- یا در واقع هر شیء نوع تعریف‌شده توسط ماژول -- است.

بر خلاف ویژگی‌های پایتونی ماژول، کد پایتون نمی‌تواند داده‌های ذخیره‌شده در وضعیت ماژول را جایگزین یا حذف کند.

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

اکستنشن‌هایی که ارجاع به اشیاء پایتون را به عنوان بخشی از وضعیت ماژول نگه می‌دارند، باید توابع Py_mod_state_traverse و Py_mod_state_clear را پیاده‌سازی کنند تا از نشت ارجاعات جلوگیری شود.

برای بازیابی وضعیت از یک ماژول مشخص، از توابع زیر استفاده کنید:

void *PyModule_GetState(PyObject *module)¶

قسمتی از ABI پایدار.

برگرداندن «وضعیت» ماژول؛ یعنی یک اشاره‌گر به بلوک حافظه‌ای که در زمان ایجاد ماژول تخصیص داده شده است، یا NULL. به Py_mod_state_size مراجعه کنید.

در صورت بروز خطا، مقدار NULL را همراه با تنظیم یک استثنا برگردانید. از PyErr_Occurred() استفاده کنید تا این حالت را از وضعیت مفقود ماژول متمایز کنید.

int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

مقدار *result را برابر با اندازه‌ی وضعیت module، همان‌طور که با استفاده از Py_mod_state_size (یا PyModuleDef.m_size) مشخص شده است، قرار دهید و مقدار 0 را برگردانید.

در صورت بروز خطا، *result را روی 1- تنظیم کنید و با تنظیم یک استثنا، 1- را برگردانید.

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

جایگاه‌ها برای تعریف وضعیت ماژول¶

شناسه‌های جایگاه slot IDs زیر برای تعریف وضعیت ماژول در دسترس هستند.

Py_mod_state_size¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

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

تنظیم مقدار به یک مقدار غیرمنفی به این معنا است که ماژول می‌تواند دوباره مقداردهی اولیه شود و مقدار حافظه اضافی مورد نیاز برای وضعیت خود را مشخص می‌کند.

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

برای بازیابی اندازه‌ی یک ماژول مشخص، از PyModule_GetStateSize() استفاده کنید.

اضافه شده در نسخه‌ی 3.15: برای پشتیبانی از نسخه‌های قبلی، به‌جای آن از PyModuleDef.m_size استفاده کنید.

Py_mod_state_traverse¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID برای یک تابع پیمایش که در طول پیمایش GC برای شیء ماژول فراخوانی می‌شود.

امضای تابع و معانی آرگومان‌ها مشابه PyTypeObject.tp_traverse است:

int traverse_module_state(PyObject *module, visitproc visit, void *arg)¶

اگر وضعیت ماژول درخواست شده باشد اما هنوز تخصیص نیافته باشد، این تابع فراخوانی نمی‌شود. این حالت بلافاصله پس از ایجاد ماژول و قبل از اجرای ماژول (تابع Py_mod_exec) رخ می‌دهد. به عبارت دقیق‌تر، اگر اندازه‌ی وضعیت (Py_mod_state_size) بزرگ‌تر از 0 باشد و وضعیت ماژول (که توسط PyModule_GetState() برگردانده می‌شود) برابر با NULL باشد، این تابع فراخوانی نمی‌شود.

اضافه شده در نسخه‌ی 3.15: برای پشتیبانی از نسخه‌های قبلی، به‌جای آن از PyModuleDef.m_traverse استفاده کنید.

Py_mod_state_clear¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID برای یک تابع پاک‌سازی که در طول پاک‌سازی GC شیء ماژول فراخوانی می‌شود.

امضای تابع به صورت زیر است:

int clear_module_state(PyObject *module)¶

اگر وضعیت ماژول درخواست شده باشد اما هنوز تخصیص نیافته باشد، این تابع فراخوانی نمی‌شود. این حالت بلافاصله پس از ایجاد ماژول و قبل از اجرای ماژول (تابع Py_mod_exec) رخ می‌دهد. به عبارت دقیق‌تر، اگر اندازه‌ی وضعیت (Py_mod_state_size) بزرگ‌تر از 0 باشد و وضعیت ماژول (که توسط PyModule_GetState() برگردانده می‌شود) برابر با NULL باشد، این تابع فراخوانی نمی‌شود.

مانند PyTypeObject.tp_clear، این تابع همیشه قبل از واگذاری حافظه (deallocation) یک ماژول فراخوانی نمی‌شود. برای مثال، زمانی که شمارش ارقام برای تشخیص اینکه آیا یک شیء دیگر استفاده نمی‌شود کافی است، جمع‌آور زباله‌ی چرخه‌ای درگیر نمی‌شود و تابع Py_mod_state_free مستقیماً فراخوانی می‌شود.

اضافه شده در نسخه‌ی 3.15: برای پشتیبانی از نسخه‌های قبلی، به‌جای آن از PyModuleDef.m_clear استفاده کنید.

Py_mod_state_free¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID برای تابعی که در طول واگذاری حافظه (deallocation) شیء ماژول فراخوانی می‌شود.

امضای تابع به صورت زیر است:

int free_module_state(PyObject *module)¶

اگر وضعیت ماژول درخواست شده باشد اما هنوز تخصیص نیافته باشد، این تابع فراخوانی نمی‌شود. این حالت بلافاصله پس از ایجاد ماژول و قبل از اجرای ماژول (تابع Py_mod_exec) رخ می‌دهد. به عبارت دقیق‌تر، اگر اندازه‌ی وضعیت (Py_mod_state_size) بزرگ‌تر از 0 باشد و وضعیت ماژول (که توسط PyModule_GetState() برگردانده می‌شود) برابر با NULL باشد، این تابع فراخوانی نمی‌شود.

اضافه شده در نسخه‌ی 3.15: برای پشتیبانی از نسخه‌های قبلی، به‌جای آن از PyModuleDef.m_free استفاده کنید.

توکن ماژول¶

هر ماژول ممکن است یک توکن (token) مرتبط داشته باشد: مقداری به اندازه‌ی اشاره‌گر که برای شناسایی چیدمان حافظه‌ی وضعیت ماژول در نظر گرفته شده است. این یعنی اگر شیء ماژولی دارید، اما مطمئن نیستید که آیا به افزونه‌ی شما «تعلق» دارد یا خیر، می‌توانید با استفاده از کدی شبیه به این آن را بررسی کنید:

PyObject *module = <the module in question>

void *module_token;
if (PyModule_GetToken(module, &module_token) < 0) {
    return NULL;
}
if (module_token != your_token) {
    PyErr_SetString(PyExc_ValueError, "unexpected module")
    return NULL;
}

// This module's state has the expected memory layout; it's safe to cast
struct my_state state = (struct my_state*)PyModule_GetState(module)

توکن یک ماژول — و مقداری از your_token که باید در کد بالا استفاده شود — به این صورت است:

برای ماژول‌های ایجادشده با PyModuleDef: آدرس همان PyModuleDef؛
برای ماژول‌های تعریف‌شده با جایگاه Py_mod_token: مقدار آن جایگاه؛
برای ماژول‌های ایجادشده از یک قلاب اکسپورت به نام PyModExport_*: آرایه‌ی جایگاه‌هایی که قلاب اکسپورت برگردانده است (مگر اینکه با Py_mod_token بازنشانی شود).

Py_mod_token¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

مورد Slot ID برای توکن ماژول.

اگر از این جایگاه برای تنظیم توکن ماژول استفاده می‌کنید (به‌جای اینکه به مقدار پیش‌فرض اتکا کنید)، باید مطمئن شوید که:

اشاره‌گر بیشتر از کلاس عمر می‌کند، بنابراین تا زمانی که کلاس وجود دارد، برای کار دیگری دوباره استفاده نمی‌شود.
به ماژول توسعه‌ای که کلاس در آن قرار دارد «تعلق» دارد، بنابراین با سایر افزونه‌ها تداخل نخواهد داشت.
اگر توکن به یک struct از نوع PyModuleDef اشاره کند، ماژول باید طوری رفتار کند که گویی از همان PyModuleDef ایجاد شده است. به‌ویژه، وضعیت ماژول باید دارای چیدمان و معناشناسی منطبق باشد.

ماژول‌های ایجادشده از PyModuleDef همیشه از آدرس PyModuleDef به عنوان توکن استفاده می‌کنند. این یعنی Py_mod_token را نمی‌توان در PyModuleDef.m_slots استفاده کرد.

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

int PyModule_GetToken(PyObject *module, void **result)¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

مقدار *result را روی توکن ماژول برای module تنظیم کنید و مقدار 0 را برگردانید.

در صورت بروز خطا، *result را روی NULL تنظیم کنید و با تنظیم یک استثنا، مقدار 1- را برگردانید.

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

همچنین نگاه کنید به PyType_GetModuleByToken().

ایجاد ماژول‌های توسعه‌ای به‌صورت پویا¶

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

PyObject *PyModule_FromSlotsAndSpec(const PySlot *slots, PyObject *spec)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.15.

یک شیء ماژول جدید ایجاد کنید، با توجه به آرایه‌ای از جایگاه‌ها و مشخصات ModuleSpec به نام spec.

آرگومان slots باید به آرایه‌ای از ساختارهای PySlot اشاره کند که با یک درایه با شناسه‌ی جایگاه 0 (که معمولاً به صورت PySlot_END نوشته می‌شود) خاتمه می‌یابد. آرایه باید شامل یک درایه‌ی Py_mod_abi باشد.

آرگومان spec ممکن است هر شیء شبیه به ModuleSpec باشد، همان‌طور که در مستندات Py_mod_create توصیف شده است. در حال حاضر، spec باید دارای ویژگی name باشد.

در صورت موفقیت، ماژول جدید را برگردانید. در صورت بروز خطا، مقدار NULL را همراه با تنظیم یک استثنا برگردانید.

توجه داشته باشید که این کار جایگاه اجرای ماژول (Py_mod_exec) را پردازش نمی‌کند. برای مقداردهی اولیه کامل یک ماژول، باید هر دو تابع PyModule_FromSlotsAndSpec() و PyModule_Exec() فراخوانی شوند. (همچنین به مقداردهی اولیه چندمرحله‌ای مراجعه کنید.)

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

int PyModule_Exec(PyObject *module)¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

جایگاه(های) Py_mod_exec مربوط به module را اجرا کنید.

در صورت موفقیت، 0 را برگردانید. در صورت بروز خطا، -1 را همراه با تنظیم یک استثنا برگردانید.

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

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

ساختار تعریف ماژول¶

به‌طور سنتی، ماژول‌های توسعه‌ای با استفاده از یک تعریف ماژول به عنوان «توصیفی» از نحوه‌ی ایجاد یک ماژول تعریف می‌شدند. به جای استفاده‌ی مستقیم از آرایه‌ای از جایگاه‌ها، این تعریف اعضای اختصاصی برای بیشتر قابلیت‌های رایج دارد و جایگاه‌های اضافی را به عنوان مکانیزم توسعه‌ای مجاز می‌داند.

این روش تعریف ماژول‌ها همچنان در دسترس است و هیچ برنامه‌ای برای حذف آن وجود ندارد.

type PyModuleDef¶

قسمتی از ABI پایدار (see below).

ساختار تعریف ماژول (struct) که اطلاعات لازم برای ایجاد یک شیء ماژول را در خود نگه می‌دارد.

این ساختار باید به صورت ایستا تخصیص داده شود (یا به نحوی تضمین شود که تا زمانی که هر ماژولی که از آن ایجاد شده است وجود دارد، معتبر باقی می‌ماند). معمولاً برای هر ماژول توسعه‌ای که به این روش تعریف می‌شود، فقط یک متغیر از این نوع وجود دارد.

این ساختار، از جمله تمامی اعضا، بخشی از ABI پایدار برای نسخه‌های غیر نخ‌آزاد (abi3) است. در ABI پایدار برای نسخه‌های ساخت نخ‌آزاد (abi3t)، این ساختار کدر است و در عمل قابل استفاده نیست؛ برای جایگزین، به تعریف ماژول مراجعه کنید.

PyModuleDef_Base m_base¶

همیشه این عضو را مقداردهی اولیه کنید به PyModuleDef_HEAD_INIT:

type PyModuleDef_Base¶

قسمتی از ABI پایدار (see below).

نوع داده‌ی PyModuleDef.m_base.

این ساختار بخشی از ABI پایدار برای نسخه‌های غیر نخ‌آزاد (abi3) است. در ABI پایدار برای نسخه‌های ساخت نخ‌آزاد (abi3t)، این ساختار کدر است و در عمل قابل استفاده نیست.

PyModuleDef_HEAD_INIT¶: مقدار اولیهی مورد نیاز برای PyModuleDef.m_base.

const char *m_name¶: متناظر با جایگاه Py_mod_name.

const char *m_doc¶: این اعضا متناظر با جایگاه Py_mod_doc هستند. تنظیم کردن این مورد روی NULL معادل چشم‌پوشی کردن از آن جایگاه است.

Py_ssize_t m_size¶

متناظر با جایگاه Py_mod_state_size است. تنظیم کردن این مورد روی صفر معادل چشم‌پوشی کردن از آن جایگاه است.

هنگام استفاده از مقدهی اولیه‌ی تک‌فاز قدیمی یا هنگام ایجاد پویای ماژول‌ها با استفاده از PyModule_Create() یا PyModule_Create2()، ممکن است m_size روی -1 تنظیم شود. این نشان می‌دهد که ماژول از زیرمفسرها پشتیبانی نمی‌کند، زیرا دارای وضعیت سراسری است.

PyMethodDef *m_methods¶: متناظر با جایگاه Py_mod_methods است. تنظیم کردن این مورد روی NULL معادل چشم‌پوشی کردن از آن جایگاه است.

PyModuleDef_Slot *m_slots¶

آرایه‌ای از جایگاه‌های اضافی که با یک درایهی {0, NULL} خاتمه می‌یابد. توجه داشته باشید که درایه‌ها به جای PySlot، از ساختار قدیمی‌تر PyModuleDef_Slot استفاده می‌کنند.

اگر آرایه حاوی جایگاه‌های متناظر با اعضای PyModuleDef باشد، مقادیر باید مطابقت داشته باشند. برای نمونه، اگر از Py_mod_name در m_slots استفاده می‌کنید، PyModuleDef.m_name باید روی همان اشاره‌گر (و نه صرفاً یک رشته‌ی برابر) تنظیم شود.

تغییر یافته در نسخه‌ی 3.5: پیش از نسخه 3.5، این عضو همیشه روی NULL تنظیم می‌شد و به این صورت تعریف می‌شد:

inquiry m_reload¶

type PyModuleDef_Slot¶

قسمتی از ABI پایدار شامل تمام اعضا از نسخه‌ی 3.5.

ساختار قدیمی‌تری که جایگاه‌های اضافی یک ماژول را تعریف می‌کند.

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

هر ساختار PyModuleDef_Slot یعنی modslot به عنوان ساختار PySlot زیر تفسیر می‌شود:

(PySlot){
   .sl_id=modslot.slot,
   .sl_flags=PySlot_INTPTR | sub_static,
   .sl_ptr=modslot.value
}

که در آن sub_static برابر با PySlot_STATIC است اگر جایگاه به پرچم نیاز داشته باشد (مانند Py_mod_methods)، یا اگر این پرچم روی جایگاه «والد» Py_mod_slots (در صورت وجود) حضور داشته باشد.

int slot¶: متناظر با PySlot.sl_id است.

void *value¶: متناظر با PySlot.sl_ptr.

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

traverseproc m_traverse¶

inquiry m_clear¶

freefunc m_free¶

این اعضا به ترتیب با جایگاه‌های Py_mod_state_traverse، Py_mod_state_clear و Py_mod_state_free مطابقت دارند.

مقداردهی این اعضا به NULL معادل حذف جایگاه‌های مربوطه است.

تغییر یافته در نسخه‌ی 3.9: توابع m_traverse، m_clear و m_free دیگر قبل از تخصیص یافتن وضعیت ماژول فراخوانی نمی‌شوند.

PyTypeObject PyModuleDef_Type¶: قسمتی از ABI پایدار از نسخه‌ی 3.5.
نوع اشیاء PyModuleDef.

Py_mod_slots¶: قسمتی از ABI پایدار از نسخه‌ی 3.15.
Slot ID که مانند Py_slot_subslots کار می‌کند، با این تفاوت که آرایه‌ای از ساختارهای PyModuleDef_Slot را مشخص می‌کند.

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

برای ایجاد ماژول‌ها از یک struct نوع PyModuleDef می‌توانید از API زیر استفاده کنید:

PyObject *PyModule_Create(PyModuleDef *def)¶: مقدار بازگشتی: مرجع جدید.
بر اساس تعریف داده‌شده در def، یک شیء ماژول جدید ایجاد می‌کند. این یک ماکرو است که PyModule_Create2() را با module_api_version برابر با PYTHON_API_VERSION، یا در صورت استفاده از API محدود برابر با PYTHON_ABI_VERSION، فراخوانی می‌کند.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء ماژول جدید، بر اساس تعریف موجود در def و با فرض نسخه API module_api_version، ایجاد می‌کند. اگر این نسخه با نسخه مفسر در حال اجرا مطابقت نداشته باشد، یک RuntimeWarning نشان داده می‌شود.

در صورت خطا، NULL به همراه استثنای تنظیم‌شده برمی‌گرداند.

این تابع از جایگاه‌ها پشتیبانی نمی‌کند. عضو m_slots از def باید NULL باشد.

نکته

در بیشتر موارد، به جای این تابع باید از PyModule_Create() استفاده شود؛ تنها زمانی از آن استفاده کنید که مطمئن باشید به آن نیاز دارید.

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)¶: مقدار بازگشتی: مرجع جدید.
این ماکرو PyModule_FromDefAndSpec2() را با module_api_version تنظیم‌شده روی PYTHON_API_VERSION، یا روی PYTHON_ABI_VERSION در صورت استفاده از API محدود فراخوانی می‌کند.

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

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: در کدهای جدید، PyModule_FromSlotsAndSpec() را ترجیح دهید.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.7.

با توجه به تعریف موجود در def و ModuleSpec spec، و با فرض نسخه API module_api_version، یک شیء ماژول جدید ایجاد می‌کند. اگر آن نسخه با نسخه مفسر در حال اجرا مطابقت نداشته باشد، یک RuntimeWarning منتشر می‌شود.

در صورت خطا، NULL به همراه استثنای تنظیم‌شده برمی‌گرداند.

توجه داشته باشید که این، جایگاه‌های اجرا (Py_mod_exec) را پردازش نمی‌کند. برای مقداردهی اولیه‌ی کامل یک ماژول، باید هر دو PyModule_FromDefAndSpec و PyModule_ExecDef فراخوانی شوند.

نکته

در بیشتر موارد، به‌جای این تابع باید از PyModule_FromDefAndSpec() استفاده کرد؛ تنها در صورتی از این تابع استفاده کنید که مطمئن باشید به آن نیاز دارید.

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

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: در کدهای جدید، PyModule_FromSlotsAndSpec() را ترجیح دهید.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶: قسمتی از ABI پایدار از نسخه‌ی 3.7.
پردازش هر جایگاه اجرا (Py_mod_exec) که در def داده شده است.

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

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: برای اجرای جایگاه‌های اجرایی خودِ ماژول، PyModule_Exec() را ترجیح دهید که روی ماژول‌هایی که با ساختار PyModuleDef ایجاد نشده‌اند، کار می‌کند.

PYTHON_API_VERSION¶

PYTHON_API_STRING¶

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

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

PYTHON_ABI_VERSION¶

PYTHON_ABI_STRING¶

برای سازگاری با نسخه‌های پیشین، به ترتیب به عنوان 3 و "3" تعریف شده است.

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

توابع پشتیبانی¶

توابع زیر برای کمک به مقداردهی اولیه یک شیء ماژول ارائه شده‌اند. آن‌ها برای جایگاه اجرای یک ماژول (Py_mod_exec)، تابع مقداردهی اولیه برای مقداردهی اولیه‌ی تک‌مرحله‌ای قدیمی (single-phase initialization)، یا کدی که ماژول‌ها را به صورت پویا ایجاد می‌کند، در نظر گرفته شده‌اند.

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)¶

قسمتی از ABI پایدار از نسخه‌ی 3.10.

یک شیء را با نام name به module اضافه می‌کند. این تابع برای راحتی کار فراهم شده و می‌توان از آن در تابع مقداردهی اولیه‌ی ماژول استفاده کرد.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا ایجاد می‌کند (raise) و -1 را برمی‌گرداند.

نمونه استفاده:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    return res;
 }

برای سهولت، تابع مقدار NULL را همراه با استثنای تنظیم‌شده می‌پذیرد. در این حالت، -1 را برگردانید و استثنای ایجادشده را دست‌نخورده بگذارید.

این مثال را می‌توان بدون بررسی صریح اینکه آیا obj برابر NULL است یا نه نیز نوشت:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    return res;
 }

توجه داشته باشید که در این مورد باید از Py_XDECREF() به جای Py_DECREF() استفاده شود، زیرا obj می‌تواند NULL باشد.

تعداد رشته‌های name متفاوتی که به این تابع پاس داده می‌شوند باید کم نگه داشته شود؛ این کار معمولاً با استفاده فقط از رشته‌های با تخصیص ایستا به‌عنوان name انجام می‌شود. برای نام‌هایی که در زمان کامپایل معلوم نیستند، ترجیح دهید PyUnicode_FromString() و PyObject_SetAttr() را مستقیماً فراخوانی کنید. برای جزئیات بیشتر، PyUnicode_InternFromString() را ببینید که ممکن است به‌طور داخلی برای ایجاد یک شیء کلید استفاده شود.

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

int PyModule_Add(PyObject *module, const char *name, PyObject *value)¶

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

مشابه PyModule_AddObjectRef()، اما ارجاعی به value را "می‌دزدد" (حتی در صورت خطا). می‌توان آن را با نتیجه‌ی تابعی که ارجاع جدیدی برمی‌گرداند فراخوانی کرد، بدون نیاز به بررسی نتیجه‌ی آن یا حتی ذخیره‌ی آن در متغیری.

نمونه استفاده:

if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    goto error;
}

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

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)¶

قسمتی از ABI پایدار.

مشابه PyModule_AddObjectRef() است، اما در صورت موفقیت (اگر 0 را برگرداند) ارجاع به value را می‌دزدد.

استفاده از توابع جدید PyModule_Add() یا PyModule_AddObjectRef() توصیه می‌شود، زیرا استفاده نادرست از تابع PyModule_AddObject() به‌راحتی می‌تواند منجر به نشتی ارجاع شود.

نکته

برخلاف سایر توابعی که ارجاع‌ها را می‌دزدند، PyModule_AddObject() ارجاع به value را تنها در صورت موفقیت آزاد می‌کند.

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

نمونه استفاده:

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // If 'obj' is not NULL and PyModule_AddObject() failed,
    // 'obj' strong reference must be deleted with Py_XDECREF().
    // If 'obj' is NULL, Py_XDECREF() does nothing.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.13.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)¶

قسمتی از ABI پایدار.

یک ثابت عدد صحیح را با نام name به module اضافه می‌کند. می‌توان از این تابع کمکی در تابع مقداردهی اولیه‌ی ماژول استفاده کرد. در صورت خطا، -1 همراه با تنظیم یک استثنا و در صورت موفقیت 0 برمی‌گرداند.

این یک تابع کمکی است که PyLong_FromLong() و PyModule_AddObjectRef() را فراخوانی می‌کند؛ برای جزئیات به مستندات آن‌ها مراجعه کنید.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)¶

قسمتی از ABI پایدار.

یک ثابت رشته‌ای را با نام name به module اضافه می‌کند. از این تابع کمکی می‌توان در تابع مقداردهی اولیه‌ی ماژول استفاده کرد. رشته‌ی value باید با NULL پایان یابد. در صورت خطا -1 همراه با تنظیم یک استثنا، و در صورت موفقیت 0 برمی‌گرداند.

این یک تابع کمکی است که PyUnicode_InternFromString() و PyModule_AddObjectRef() را فراخوانی می‌کند؛ برای جزئیات به مستندات آن‌ها مراجعه کنید.

PyModule_AddIntMacro(module, macro)¶: یک ثابت صحیح به module اضافه می‌کند. نام و مقدار از macro گرفته می‌شوند. برای مثال، PyModule_AddIntMacro(module, AF_INET) ثابت صحیح AF_INET را با مقدار AF_INET به module اضافه می‌کند. در صورت خطا -1 همراه با تنظیم یک استثنا و در صورت موفقیت 0 را برمی‌گرداند.

PyModule_AddStringMacro(module, macro)¶: افزودن یک ثابت رشته‌ای به module.

int PyModule_AddType(PyObject *module, PyTypeObject *type)¶: قسمتی از ABI پایدار از نسخه‌ی 3.10.
یک شیء نوع به module اضافه می‌کند. شیء نوع با فراخوانی داخلی PyType_Ready() نهایی‌سازی می‌شود. نام شیء نوع از آخرین جزء tp_name پس از نقطه گرفته می‌شود. در صورت خطا -1 همراه با یک استثنای تنظیم‌شده و در صورت موفقیت 0 برمی‌گرداند.

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

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶

قسمتی از ABI پایدار از نسخه‌ی 3.7.

توابع را از آرایه‌ی functions که با NULL پایان می‌یابد به module اضافه می‌کند. برای جزئیات مربوط به ورودی‌های منفرد به مستندات PyMethodDef مراجعه کنید (به دلیل نبود فضای نام ماژول مشترک، «توابع» سطح ماژول که در C پیاده‌سازی می‌شوند معمولاً ماژول را به‌عنوان نخستین پارامتر خود دریافت می‌کنند که این امر آن‌ها را مشابه متدهای نمونه در کلاس‌های پایتون می‌سازد).

این تابع هنگام ایجاد یک ماژول از PyModuleDef (مانند زمانی که از مقداردهی اولیه چندمرحله‌ای، PyModule_Create یا PyModule_FromDefAndSpec استفاده می‌شود) به‌طور خودکار فراخوانی می‌شود. برخی از نویسندگان ماژول ممکن است ترجیح دهند توابع را در چندین آرایه‌ی PyMethodDef تعریف کنند؛ در این صورت باید این تابع را مستقیماً فراخوانی کنند.

آرایه‌ی functions باید به‌صورت ایستا تخصیص داده شود (یا به نحوی دیگر تضمین شود که عمرش از شیء ماژول طولانی‌تر باشد).

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

int PyModule_SetDocString(PyObject *module, const char *docstring)¶

قسمتی از ABI پایدار از نسخه‌ی 3.7.

رشته مستند module را به docstring تنظیم می‌کند. این تابع هنگام ایجاد ماژول از روی PyModuleDef (مانند زمان استفاده از مقداردهی اولیه چندمرحله‌ای، PyModule_Create یا PyModule_FromDefAndSpec) به‌طور خودکار فراخوانی می‌شود.

در صورت موفقیت 0 را برمی‌گرداند. در صورت خطا -1 همراه با تنظیم یک استثنا برمی‌گرداند.

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

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)¶: این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

با استفاده از یکی از مقادیر Py_mod_gil نشان می‌دهد که module از اجرا بدون قفل مفسر سراسری (GIL) پشتیبانی می‌کند یا نمی‌کند. هنگام استفاده از مقداردهی اولیه تک‌مرحله‌ای قدیمی، این تابع باید در طول تابع مقدار‌دهی اولیه‌ی module فراخوانی شود. اگر این تابع در طول مقدار‌دهی اولیه ماژول فراخوانی نشود، سازوکار ایمپورت فرض می‌کند که ماژول از اجرا بدون GIL پشتیبانی نمی‌کند. این تابع فقط در ساخت‌های پایتون که با --disable-gil پیکربندی شده‌اند در دسترس است. در صورت خطا -1 را همراه با تنظیم یک استثنا و در صورت موفقیت 0 را برمی‌گرداند.

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

جستجوی ماژول (مقداردهی اولیه تک‌فازی)¶

طرح مقداردهی اولیه‌ی مقداردهی اولیه تک‌مرحله‌ای قدیمی، ماژول‌های تک‌نمونه ایجاد می‌کند که می‌توان آن‌ها را در زمینه‌ی مفسر جاری جستجو کرد. این امکان را فراهم می‌کند که شیء ماژول بعداً تنها با یک ارجاع به تعریف ماژول بازیابی شود.

این توابع روی ماژول‌هایی که با استفاده از مقداردهی اولیه چندمرحله‌ای (multi-phase initialization) ایجاد شده‌اند کار نخواهند کرد، زیرا می‌توان چندین ماژول از این نوع را از یک تعریف واحد ایجاد کرد.

PyObject *PyState_FindModule(PyModuleDef *def)¶: مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار.
شیء ماژولی که از def برای مفسر فعلی ایجاد شده است را برمی‌گرداند. این متد مستلزم آن است که شیء ماژول از قبل با PyState_AddModule() به وضعیت مفسر متصل شده باشد. در صورتی که شیء ماژول مربوطه یافت نشود یا هنوز به وضعیت مفسر متصل نشده باشد، NULL را برمی‌گرداند.

int PyState_AddModule(PyObject *module, PyModuleDef *def)¶

قسمتی از ABI پایدار از نسخه‌ی 3.3.

شیء ماژولِ پاس‌داده‌شده به تابع را به وضعیت مفسر متصل می‌کند. این کار امکان دسترسی به شیء ماژول از طریق PyState_FindModule() را فراهم می‌کند.

تنها بر ماژول‌هایی که با استفاده از مقداردهی اولیه تک‌مرحله‌ای ایجاد شده‌اند مؤثر است.

پایتون پس از ایمپورت کردن ماژولی که از راه‌اندازی تک‌فازی استفاده می‌کند، PyState_AddModule را به‌طور خودکار فراخوانی می‌کند؛ بنابراین فراخوانی آن از کد راه‌اندازی ماژول ضروری نیست (اما بی‌ضرر است). تنها در صورتی به فراخوانی صریح آن نیاز است که کد راه‌اندازی خودِ ماژول در ادامه PyState_FindModule را فراخوانی کند. این تابع عمدتاً برای پیاده‌سازی سازوکارهای ایمپورت جایگزین در نظر گرفته شده است (چه با فراخوانی مستقیم آن، چه با مراجعه به پیاده‌سازی آن برای جزئیات به‌روزرسانی‌های وضعیت موردنیاز).

اگر پیش‌تر ماژولی با استفاده از همان def پیوست شده باشد، با module جدید جایگزین می‌شود.

فراخوان‌کننده باید یک attached thread state داشته باشد.

در صورت خطا، -1 همراه با استثنای تنظیم‌شده و در صورت موفقیت 0 برمی‌گرداند.

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

int PyState_RemoveModule(PyModuleDef *def)¶

قسمتی از ABI پایدار از نسخه‌ی 3.3.

شیء ماژول ایجادشده از def را از وضعیت مفسر حذف می‌کند. در صورت خطا -1 همراه با استثنای تنظیم‌شده و در صورت موفقیت 0 برمی‌گرداند.

فراخوان‌کننده باید یک attached thread state داشته باشد.

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

اشیاء ماژول¶

تعریف ماژول¶

جایگاه‌های فراداده¶

جایگاه‌های ویژگی¶

جایگاه‌های ایجاد و راه‌اندازی اولیه¶

وضعیت ماژول¶

جایگاه‌ها برای تعریف وضعیت ماژول¶

توکن ماژول¶

ایجاد ماژول‌های توسعه‌ای به‌صورت پویا¶

ساختار تعریف ماژول¶

توابع پشتیبانی¶

جستجوی ماژول (مقداردهی اولیه تک‌فازی)¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه