تعریف ماژول¶

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

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

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

وضعیت ماژول¶

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

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

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

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

اکستنشن‌هایی که ارجاع به اشیاء پایتون را به عنوان بخشی از وضعیت ماژول نگه می‌دارند، باید توابع 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.

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)

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

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

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.