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

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 تنظیم خواهد شد.

The module's __file__ attribute will be set to the code object's co_filename.

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

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

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

تغییر یافته در نسخه‌ی 3.12: The setting of __cached__ and __loader__ is deprecated. See ModuleSpec for alternatives.

تغییر یافته در نسخه‌ی 3.15: The __cached__ attribute is no longer set.

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.
Like PyImport_ExecCodeModuleEx(), but the path to any compiled file via cpathname is used appropriately when non-NULL. Of the three functions, this is the preferred one to use.

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

تغییر یافته در نسخه‌ی 3.12: Setting __cached__ is deprecated. See ModuleSpec for alternatives.

تغییر یافته در نسخه‌ی 3.15: The __cached__ attribute no longer set.

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;
    const unsigned char *code;
    int size;
    bool 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)¶

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

Note that the inittab uses "PyInit" initialization functions; there is currently no way to include "PyModExport_" export hooks.

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()¶: Gets the current lazy imports mode.

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

PyObject *PyImport_GetLazyImportsFilter()¶: Return a strong reference to the current lazy imports filter, or NULL if none exists. This function always succeeds.

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

int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)¶

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

This function always returns 0.

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

int PyImport_SetLazyImportsFilter(PyObject *filter)¶

Sets the current lazy imports filter. The filter should be a callable that will receive (importing_module_name, imported_module_name, [fromlist]) when an import can potentially be lazy. The imported_module_name value is the resolved module name, so lazy from .spam import eggs passes package.spam. The callable must return True if the import should be lazy and False otherwise.

Return 0 on success and -1 with an exception set otherwise.

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

type PyImport_LazyImportsMode¶

Enumeration of possible lazy import modes.

enumerator PyImport_LAZY_NORMAL¶: Respect the lazy keyword in source code. This is the default mode.

enumerator PyImport_LAZY_ALL¶: Make all imports lazy by default.

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

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

This function is a building block that enables embedders to implement the create_module() step of custom static extension importers (e.g. of statically-linked extensions).

spec must be a ModuleSpec object.

initfunc must be an initialization function, the same as for PyImport_AppendInittab().

On success, create and return a module object. This module will not be initialized; call PyModule_Exec() to initialize it. (Custom importers should do this in their exec_module() method.)

On error, return NULL with an exception set.

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

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

موضوع قبلی

موضوع بعدی

این صفحه