ایمپورت کردن ماژول‌ها¶

PyObject *PyImport_ImportModule(const char *name)¶

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

این یک دربرگیرنده در اطراف PyImport_Import() است که به‌جای PyObject*، آرگومانی از نوع const char* می‌گیرد.

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)¶

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

ایمپورت کردن یک ماژول. این کار را به بهترین شکل می‌توان با ارجاع به تابع توکار پایتون __import__() توصیف کرد.

مقدار بازگشتی، ارجاعی جدید به ماژول یا بسته‌ی سطح‌بالا که ایمپورت شده است، یا در صورت شکست NULL به همراه استثنایی تنظیم‌شده است. مانند __import__()، مقدار بازگشتی هنگامی که زیرماژولی از یک بسته درخواست شده باشد، معمولاً بسته‌ی سطح‌بالا است، مگر آنکه fromlist غیرخالی داده شده باشد.

ایمپورت‌های ناموفق، اشیاء ماژول ناقص را حذف می‌کنند، مانند PyImport_ImportModule().

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶

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

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

مقدار بازگشتی، ارجاعی جدید به ماژول یا بسته‌ی سطح‌بالا که ایمپورت شده است، یا در صورت شکست NULL به همراه استثنایی تنظیم‌شده است. مانند __import__()، مقدار بازگشتی هنگامی که زیرماژولی از یک بسته درخواست شده باشد، معمولاً بسته‌ی سطح‌بالا است، مگر آنکه fromlist غیرخالی داده شده باشد.

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

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶

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

مشابه PyImport_ImportModuleLevelObject()، اما نام به جای شیء یونیکد، یک رشته کدگذاری‌شده با UTF-8 است.

تغییر یافته در نسخه‌ی 3.3: مقادیر منفی برای level دیگر پذیرفته نمی‌شوند.

PyObject *PyImport_Import(PyObject *name)¶

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

این یک رابط سطح بالاتر است که «تابع قلاب ایمپورت» فعلی را فراخوانی می‌کند (با مقدار صریح ۰ برای level، به معنای ایمپورت مطلق). این رابط، تابع __import__() را از __builtins__ موجود در سراسری‌های فعلی فراخوانی می‌کند. این بدان معناست که ایمپورت با استفاده از هر قلاب ایمپورتی که در محیط فعلی نصب شده باشد انجام می‌شود.

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

PyObject *PyImport_ReloadModule(PyObject *m)¶

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

یک ماژول را بارگذاری مجدد می‌کند. ارجاعی جدید به ماژولِ بارگذاری‌مجدد‌شده برمی‌گرداند، یا در صورت شکست NULL همراه با تنظیم یک استثنا برمی‌گرداند (در این حالت ماژول همچنان وجود دارد).

PyObject *PyImport_AddModuleRef(const char *name)¶

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

شیء ماژول متناظر با نام یک ماژول را برمی‌گرداند.

آرگومان name ممکن است به شکل package.module باشد. ابتدا بررسی کنید که آیا ماژولی در دیکشنری ماژول‌ها وجود دارد یا نه، و اگر وجود ندارد، یک ماژول جدید ایجاد کرده و آن را در دیکشنری ماژول‌ها درج کنید.

در صورت موفقیت، یک strong reference به ماژول برمی‌گرداند. در صورت شکست، NULL را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

نام ماژول name از UTF-8 کدگشایی می‌شود.

این تابع ماژول را بارگذاری یا ایمپورت نمی‌کند؛ اگر ماژول از قبل بارگذاری نشده باشد، یک شیء ماژول خالی دریافت خواهید کرد. برای ایمپورت کردن یک ماژول، از PyImport_ImportModule() یا یکی از انواع آن استفاده کنید. ساختارهای بسته‌ای که نام نقطه‌دارِ name بر آن‌ها دلالت می‌کند، اگر از قبل وجود نداشته باشند ایجاد نمی‌شوند.

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

PyObject *PyImport_AddModuleObject(PyObject *name)¶

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

مشابه PyImport_AddModuleRef()، اما یک borrowed reference برمی‌گرداند و name یک شیء str پایتون است.

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

PyObject *PyImport_AddModule(const char *name)¶

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

مشابه PyImport_AddModuleRef() است، اما یک borrowed reference برمی‌گرداند.

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)¶

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

با دریافت نام یک ماژول (احتمالاً به شکل package.module) و یک شیء کد که از یک پرونده بایت‌کد پایتون خوانده شده یا از تابع توکار compile() به دست آمده است، ماژول را بارگذاری می‌کند. یک ارجاع جدید به شیء ماژول برمی‌گرداند، یا در صورت وقوع خطا، NULL را همراه با یک استثنای تنظیم‌شده برمی‌گرداند. name در موارد خطا از sys.modules حذف می‌شود، حتی اگر name هنگام ورود به PyImport_ExecCodeModule() از قبل در sys.modules موجود بوده باشد. باقی گذاشتن ماژول‌هایی که مقداردهی اولیه‌شان کامل نشده است در sys.modules خطرناک است، زیرا ایمپورت‌های چنین ماژول‌هایی هیچ راهی برای دانستن این موضوع ندارند که شیء ماژول در وضعیتی ناشناخته (و احتمالاً نسبت به مقاصد نویسنده‌ی ماژول آسیب‌دیده) قرار دارد.

__spec__ و __loader__ ماژول، در صورتی که از قبل تنظیم‌نشده باشند، با مقادیر مناسب تنظیم خواهند شد. بارگذار مشخصه به __loader__ ماژول (در صورت تنظیم بودن) و در غیر این صورت به نمونه‌ای از SourceFileLoader تنظیم خواهد شد.

ویژگی __file__ ماژول روی شیء کد co_filename تنظیم خواهد شد.

این تابع در صورتی که ماژول قبلاً ایمپورت شده باشد، آن را بازبارگذاری می‌کند. برای روش موردنظرِ بازبارگذاری یک ماژول، PyImport_ReloadModule() را ببینید.

اگر name به نامی نقطه‌گذاری‌شده به شکل package.module اشاره کند، هر ساختار بسته‌ای که از قبل ایجاد نشده باشد، همچنان ایجاد نخواهد شد.

همچنین ببینید PyImport_ExecCodeModuleEx() و PyImport_ExecCodeModuleWithPathnames().

تغییر یافته در نسخه‌ی 3.12: تنظیم کردن __cached__ و __loader__ منسوخ شده است. برای راه‌های جایگزین، ModuleSpec را ببینید.

تغییر یافته در نسخه‌ی 3.15: ویژگی __cached__ دیگر تنظیم نمی‌شود.

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)¶

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

مانند PyImport_ExecCodeModule()، اما اگر مسیرنام غیر NULL باشد، ویژگی __file__ شیء ماژول به مسیرنام تنظیم می‌شود.

همچنین PyImport_ExecCodeModuleWithPathnames() را ببینید.

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)¶

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

مشابه PyImport_ExecCodeModuleEx()، اما مسیر هر پرونده‌ی کامپایل‌شده از طریق cpathname در صورت غیر از NULL بودن به‌درستی استفاده می‌شود. از میان این سه تابع، این تابع ترجیح داده می‌شود که استفاده شود.

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

تغییر یافته در نسخه‌ی 3.12: تنظیم __cached__ منسوخ شده است. برای راه‌های جایگزین، ModuleSpec را ببینید.

تغییر یافته در نسخه‌ی 3.15: ویژگی __cached__ دیگر تنظیم نمی‌شود.

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)¶

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

مانند PyImport_ExecCodeModuleObject()، اما name، pathname و cpathname رشته‌های کدگذاری‌شده با UTF-8 هستند. اگر pathname برابر NULL قرار داده شده باشد، تلاش‌هایی نیز برای تعیین مقدار pathname از روی cpathname صورت می‌گیرد.

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

تغییر یافته در نسخه‌ی 3.3: اگر تنها مسیر بایت‌کد ارائه‌شده باشد، از imp.source_from_cache() برای محاسبه‌ی مسیر منبع استفاده می‌کند.

تغییر یافته در نسخه‌ی 3.12: دیگر از ماژول حذف‌شده imp استفاده نمی‌کند.

long PyImport_GetMagicNumber()¶

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

عدد جادویی پرونده‌های بایت‌کد پایتون (که با نام پرونده‌ی .pyc نیز شناخته می‌شود) را برمی‌گرداند. عدد جادویی باید در چهار بایت نخست پرونده‌ی بایت‌کد، با ترتیب بایت کوچک‌اندیان، موجود باشد. در صورت خطا -1 را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.3: بازگشت مقدار -1 در صورت شکست.

const char *PyImport_GetMagicTag()¶

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

رشته برچسب جادویی (magic tag) را برای نام پرونده‌های بایت‌کد پایتون با قالب PEP 3147 برمی‌گرداند. به خاطر داشته باشید که مقدار sys.implementation.cache_tag معتبر است و باید به‌جای این تابع از آن استفاده شود.

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

PyObject *PyImport_GetModuleDict()¶

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

دیکشنری مورد استفاده برای مدیریت ماژول‌ها را برمی‌گرداند (که با نام sys.modules نیز شناخته می‌شود). توجه داشته باشید که این یک متغیر به‌ازای هر مفسر است.

PyObject *PyImport_GetModule(PyObject *name)¶

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

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

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

PyObject *PyImport_GetImporter(PyObject *path)¶

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

یک شیء یابنده برای ورودی path از sys.path/pkg.__path__ برمی‌گرداند، که ممکن است آن را از دیکشنری sys.path_importer_cache واکشی کند. اگر هنوز نهان‌سازی نشده باشد، sys.path_hooks را پیمایش می‌کند تا قلابی پیدا شود که بتواند ورودی مسیر را مدیریت کند. اگر هیچ قلابی نتواند، None برمی‌گرداند؛ این به فراخوان‌کننده‌ی ما می‌گوید که path based finder نتوانسته است یابنده‌ای برای این ورودی مسیر پیدا کند. نتیجه را در sys.path_importer_cache نهان‌سازی می‌کند. یک ارجاع جدید به شیء یابنده برمی‌گرداند.

int PyImport_ImportFrozenModuleObject(PyObject *name)¶

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

یک ماژول فریزشده با نام name را بارگذاری می‌کند. در صورت موفقیت مقدار 1، اگر ماژول یافت نشود مقدار 0 و اگر مقداردهی اولیه شکست بخورد مقدار -1 به همراه استثنای تنظیم‌شده برمی‌گرداند. برای دسترسی به ماژول ایمپورت‌شده پس از بارگذاری موفق، از PyImport_ImportModule() استفاده کنید. (توجه داشته باشید که این نام‌گذاری نادرست است --- این تابع در صورتی که ماژول قبلاً ایمپورت‌شده باشد، آن را مجدداً بارگذاری می‌کند.)

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

تغییر یافته در نسخه‌ی 3.4: ویژگی __file__ دیگر بر روی ماژول تنظیم نمی‌شود.

int PyImport_ImportFrozenModule(const char *name)¶

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

مشابه PyImport_ImportFrozenModuleObject() است، اما نام به جای شیء یونیکد، یک رشته کدگذاری‌شده با UTF-8 است.

struct _frozen¶

این تعریف نوع ساختار برای توصیف‌گرهای ماژول فریزشده است که توسط ابزار freeze تولید می‌شود (نگاه کنید به Tools/freeze/ در توزیع سورس پایتون). تعریف آن، که در Include/import.h یافت می‌شود، به شرح زیر است:

struct _frozen {
    const char *name;                 /* ASCII encoded string */
    const unsigned char *code;
    int size;
    int is_package;
};

تغییر یافته در نسخه‌ی 3.11: فیلد جدید is_package نشان می‌دهد که ماژول یک بسته است یا خیر. این کار جایگزین تنظیم فیلد size به مقدار منفی می‌شود.

const struct _frozen *PyImport_FrozenModules¶

این اشاره‌گر برای اشاره به آرایه‌ای از رکوردهای _frozen مقداردهی اولیه می‌شود که با رکوردی پایان می‌یابد که تمام اعضای آن NULL یا صفر هستند. هنگامی که یک ماژول فریزشده ایمپورت می‌شود، در این جدول جستجو می‌شود. کد شخص ثالث می‌تواند با این اشاره‌گر ترفندهایی بزند تا مجموعه‌ای از ماژول‌های فریزشده که به‌صورت پویا ایجاد شده‌اند فراهم کند.

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))¶

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

یک ماژول تکی را به جدول موجود ماژول‌های توکار اضافه می‌کند. این تابع یک پوشش کمکی حول PyImport_ExtendInittab() است که در صورتی که نتوان جدول را گسترش داد، مقدار -1 را برمی‌گرداند. ماژول جدید را می‌توان با نام name ایمپورت کرد و از تابع initfunc به عنوان تابع مقداردهی اولیه‌ای که در نخستین تلاش برای ایمپورت فراخوانی می‌شود، استفاده می‌کند. این تابع باید پیش از Py_Initialize() فراخوانی شود.

struct _inittab¶

ساختاری که یک ورودی واحد در فهرست ماژول‌های توکار را توصیف می‌کند. برنامه‌هایی که پایتون را تعبیه می‌کنند می‌توانند از آرایه‌ای از این ساختار‌ها همراه با PyImport_ExtendInittab() برای فراهم کردن ماژول‌های توکار اضافی استفاده کنند. این ساختار از دو عضو تشکیل شده است:

const char *name¶

نام ماژول، به‌صورت یک رشته کدگذاری‌شده با اسکی.

PyObject *(*initfunc)(void)¶

تابع مقداردهی اولیه برای ماژولی که به‌صورت توکار در مفسر ساخته‌شده است.

توجه داشته باشید که inittab از توابع راه‌اندازی «PyInit» استفاده می‌کند؛ در حال حاضر هیچ راهی برای گنجاندن هوک‌های صادراتی «PyModExport_» وجود ندارد.

int PyImport_ExtendInittab(struct _inittab *newtab)¶

مجموعه‌ای از ماژول‌ها را به جدول ماژول‌های توکار اضافه می‌کند. آرایه newtab باید با یک ورودی نشانگر پایان یابد که برای فیلد name مقدار NULL را در بر دارد؛ ارائه‌نکردن مقدار نشانگر می‌تواند به خطای حافظه منجر شود. در صورت موفقیت 0 و در صورتی که حافظه کافی برای گسترش جدول داخلی تخصیص داده نشود، -1 برمی‌گرداند. در صورت شکست، هیچ ماژولی به جدول داخلی اضافه نمی‌شود. این باید پیش از Py_Initialize() فراخوانی شود.

اگر پایتون چندین بار مقداردهی اولیه شود، PyImport_AppendInittab() یا PyImport_ExtendInittab() باید پیش از هر مقداردهی اولیه پایتون فراخوانی شوند.

struct _inittab *PyImport_Inittab¶

جدول ماژول‌های توکار مورد استفاده در راه‌اندازی پایتون. آن را مستقیماً به کار نبرید؛ به‌جای آن از PyImport_AppendInittab() و PyImport_ExtendInittab() استفاده کنید.

PyObject *PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)¶

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

ماژول mod_name را ایمپورت کنید و ویژگی attr_name آن را دریافت کنید.

نام‌ها باید شیءهای str پایتون باشند.

تابع کمکی که PyImport_Import() و PyObject_GetAttr() را با هم ترکیب می‌کند. برای مثال، اگر ماژول یافت نشود می‌تواند ImportError و اگر ویژگی وجود نداشته باشد می‌تواند AttributeError را پرتاب کند.

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

PyObject *PyImport_ImportModuleAttrString(const char *mod_name, const char *attr_name)¶

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

مشابه PyImport_ImportModuleAttr() است، اما نام‌ها به‌جای اشیاء str پایتون، رشته‌های کدگذاری‌شده با UTF-8 هستند.

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

PyImport_LazyImportsMode PyImport_GetLazyImportsMode()¶

حالت فعلی ایمپورت‌های تنبل را دریافت می‌کند.

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

PyObject *PyImport_GetLazyImportsFilter()¶

یک ارجاع قوی به صافی ایمپورت‌های تنبل فعلی، یا در صورت عدم وجود، NULL را برمی‌گرداند. این تابع همیشه موفق اجرا می‌شود.

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

int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)¶

حالت فعلی ایمپورت‌های تنبل را دریافت می‌کند.

این تابع همیشه 0 را برمی‌گرداند.

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

int PyImport_SetLazyImportsFilter(PyObject *filter)¶

فیلتر ایمپورت تنبل فعلی را تنظیم می‌کند. filter باید یک شیء قابل فراخوانی باشد که هنگامی که یک ایمپورت بالقوه می‌تواند تنبل باشد، (importing_module_name, imported_module_name, [fromlist]) را دریافت کند. مقدار imported_module_name نام ماژول حل‌شده است؛ بنابراین، lazy from .spam import eggs مقدار package.spam را ارسال می‌کند. شیء قابل فراخوانی باید در صورتی که ایمپورت باید تنبل باشد، True و در غیر این صورت False برگرداند.

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

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

type PyImport_LazyImportsMode¶

شمارش حالت‌های ممکن برای ایمپورت تنبل.

enumerator PyImport_LAZY_NORMAL¶

احترام به کلیدواژه‌ی lazy در کد منبع. این حالت پیش‌فرض است.

enumerator PyImport_LAZY_ALL¶

تنظیم تمام ایمپورت‌ها به حالت تنبل به صورت پیش‌فرض.

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

PyObject *PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject *(*initfunc)(void))¶

این تابع یک بلوک ساختاری است که به تعبیه‌کنندگان امکان می‌دهد مرحله‌ی create_module() مربوط به ایمپورت‌کننده‌های افزونه‌ی استاتیک سفارشی (مانند افزونه‌های پیوندیافته‌ی ایستا) را پیاده‌سازی کنند.

spec باید یک شیء ModuleSpec باشد.

initfunc باید یک تابع مقداردهی اولیه باشد، درست مانند PyImport_AppendInittab().

در صورت موفقیت، یک شیء ماژول ایجاد کرده و برمی‌گرداند. این ماژول مقداردهی اولیه نخواهد شد؛ برای مقداردهی اولیه آن، PyModule_Exec() را فراخوانی کنید. (ایمپورت‌کننده‌های سفارشی باید این کار را در متد exec_module() خود انجام دهند.)

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

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

• این ماژول به عنوان بخشی از مقداردهی اولیه، تحت name مشخصات (spec) به sys.modules اضافه می‌شود.

• اگر یک ماژول تک‌فاز پیش‌تر توسط این تابع یا به عنوان یک ماژول توکار (به عنوان مثال، ماژولی که با PyImport_AppendInittab() ثبت شده است) تحت همان name ایمپورت شده باشد، ممکن است پایتون به جای فراخوانی مجدد initfunc، محتویات ماژول قبلی را مجدداً استفاده کند.

• این ماژول توسط initfunc به طور کامل مقداردهی اولیه خواهد شد. فراخوانی PyModule_Exec() روی آن هیچ تأثیری نخواهد داشت، هرچند همچنان توصیه می‌شود، در صورتی که ماژول بعداً به مقداردهی اولیه‌ی چندفاز تغییر وضعیت دهد.

• همچنین، اگر name مشخصات (spec) شامل نقطه‌ها باشد، این نام برای اضافه‌کردن یک بسته‌ی والد به __name__ ماژول جدید استفاده می‌شود.

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