اشیاء ماژول¶

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__ آن تغییر دهد.

void *PyModule_GetState(PyObject *module)¶: قسمتی از ABI پایدار.
«وضعیت» ماژول را برمی‌گرداند، یعنی اشاره‌گری به بلوک حافظه‌ای که در زمان ایجاد ماژول تخصیص یافته است، یا NULL. PyModuleDef.m_size را ببینید.

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() استفاده کنید.

تعریف‌های ماژول¶

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

ماژول‌هایی که با استفاده از C API تعریف می‌شوند، معمولاً از یک تعریف ماژول، PyModuleDef، استفاده می‌کنند -- یک «توصیف» ثابت و تخصیص‌یافته به‌صورت ایستا از چگونگی ایجاد یک ماژول.

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

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

type PyModuleDef¶

قسمتی از ABI پایدار شامل تمام اعضا.

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

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

const char *m_name¶: نام ماژول جدید.

const char *m_doc¶: رشته مستند ماژول؛ معمولاً از متغیر رشته مستند ایجاد‌شده با PyDoc_STRVAR استفاده می‌شود.

Py_ssize_t m_size¶

وضعیت ماژول می‌تواند به‌جای متغیرهای سراسری ایستا، در ناحیه حافظه‌ی مخصوص هر ماژول نگهداری شود که می‌توان آن را با PyModule_GetState() بازیابی کرد. این کار باعث می‌شود ماژول‌ها برای استفاده در چندین زیرمفسر ایمن باشند.

این ناحیه حافظه هنگام ایجاد ماژول بر اساس m_size تخصیص داده می‌شود و هنگام تخصیص‌زدایی شیء ماژول، پس از فراخوانی تابع m_free (در صورت وجود)، آزاد می‌شود.

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

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

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

PyMethodDef *m_methods¶: اشاره‌گری به جدولی از توابع در سطح ماژول که توسط مقادیر PyMethodDef توصیف می‌شوند. اگر هیچ تابعی وجود نداشته باشد، می‌تواند NULL باشد.

PyModuleDef_Slot *m_slots¶

آرایه‌ای از تعریف‌های جایگاه برای مقداردهی اولیه چندمرحله‌ای که با ورودی {0, NULL} پایان می‌یابد. هنگام استفاده از مقداردهی اولیه تک‌مرحله‌ای قدیمی، m_slots باید NULL باشد.

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

inquiry m_reload¶

traverseproc m_traverse¶

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

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

تغییر یافته در نسخه‌ی 3.9: دیگر پیش از تخصیص وضعیت ماژول فراخوانی نمی‌شود.

inquiry m_clear¶

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

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

مانند PyTypeObject.tp_clear، این تابع همیشه پیش از آزادسازی یک ماژول فراخوانی نمی‌شود. برای مثال، وقتی شمارش ارجاع برای تعیین اینکه یک شیء دیگر استفاده نمی‌شود کافی باشد، زباله‌روب چرخه‌ای دخالتی ندارد و m_free مستقیماً فراخوانی می‌شود.

تغییر یافته در نسخه‌ی 3.9: دیگر پیش از تخصیص وضعیت ماژول فراخوانی نمی‌شود.

freefunc m_free¶

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

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

تغییر یافته در نسخه‌ی 3.9: دیگر پیش از تخصیص وضعیت ماژول فراخوانی نمی‌شود.

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

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

type PyModuleDef_Slot¶

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

int slot¶: شناسه‌ی جایگاه، که از میان مقادیر موجود توضیح‌داده‌شده در ادامه انتخاب می‌شود.

void *value¶: مقدار جایگاه، که معنای آن به شناسه جایگاه بستگی دارد.

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

انواع جایگاه‌های موجود عبارت‌اند از:

Py_mod_create¶

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

تابعی را مشخص می‌کند که برای ایجاد خودِ شیء ماژول فراخوانی می‌شود. اشاره‌گر value این جایگاه باید به تابعی با امضای زیر اشاره کند:

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

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

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

نمی‌توان چند جایگاه Py_mod_create را در یک تعریف ماژول مشخص کرد.

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

هیچ الزامی وجود ندارد که شیء بازگردانده‌شده نمونه‌ای از PyModule_Type باشد. می‌توان از هر نوعی استفاده کرد، به شرط آنکه از تنظیم و دریافت ویژگی‌های مرتبط با ایمپورت پشتیبانی کند. با این حال، تنها نمونه‌های PyModule_Type را می‌توان بازگرداند اگر PyModuleDef دارای m_traverse، m_clear و m_free غیر NULL؛ m_size غیرصفر؛ یا جایگاه‌هایی غیر از Py_mod_create باشد.

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

Py_mod_exec¶

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

تابعی را مشخص می‌کند که برای اجرا کردن ماژول فراخوانی می‌شود. این معادل اجرای کد یک ماژول پایتون است: به‌طور معمول، این تابع کلاس‌ها و ثابت‌ها را به ماژول اضافه می‌کند. امضای تابع به این صورت است:

int exec_module(PyObject *module)¶

اگر چندین جایگاه Py_mod_exec مشخص شده باشند، به ترتیبی که در آرایه m_slots ظاهر شده‌اند پردازش می‌شوند.

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

Py_mod_multiple_interpreters¶

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

یکی از مقادیر زیر را مشخص می‌کند:

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

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

Py_mod_gil¶

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

یکی از مقادیر زیر را مشخص می‌کند:

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

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

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

تعیین چند جایگاه Py_mod_gil در یک تعریف ماژول مجاز نیست.

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

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

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

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

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.

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.

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

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

PYTHON_API_VERSION¶

نسخه‌ی C API. برای سازگاری با نسخه‌های پیشین تعریف‌شده است.

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

PYTHON_ABI_VERSION¶

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

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

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

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

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.

اشیاء ماژول¶

تعریف‌های ماژول¶

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

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

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

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

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه