`importlib` --- پیاده‌سازی `import`¶

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

مقدمه¶

هدف بسته‌ی importlib سه‌گانه است.

یکی فراهم کردن پیاده‌سازی دستور import (و بنابراین، به‌تبع آن، تابع __import__()) در کد منبع پایتون است. این کار پیاده‌سازی‌ای از import را فراهم می‌کند که در هر مفسر پایتون قابل‌حمل است. همچنین پیاده‌سازی‌ای فراهم می‌کند که درک آن نسبت به پیاده‌سازی‌ای که در زبان برنامه‌نویسی دیگری غیر از پایتون پیاده‌سازی شده است، آسان‌تر است.

دوم، کامپوننت‌های مورد نیاز برای پیاده‌سازی import در این بسته در دسترس قرار گرفته‌اند تا ایجاد اشیای سفارشی خود کاربران (که به‌طور کلی با نام importer شناخته می‌شوند) برای مشارکت در فرایند ایمپورت آسان‌تر شود.

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

importlib.metadata امکان دسترسی به فراداده‌ی توزیع‌های شخص ثالث را فراهم می‌کند.
importlib.resources روال‌هایی برای دسترسی به «منابع» غیرکدی از بسته‌های پایتون فراهم می‌کند.

همچنین ملاحظه نمائید

ایمپورت: مرجع زبان برای دستور import.
مشخصات بسته‌ها: مشخصات اصلی بسته‌ها. برخی معناشناسی‌ها از زمان نگارش این سند تغییر کرده‌اند (برای مثال، هدایت مجدد بر اساس None در sys.modules).
تابع __import__(): دستور import قند نحوی برای این تابع است.
مقداردهی اولیه‌ی مسیر جستجوی ماژول sys.path: مقداردهی اولیه‌ی sys.path.
PEP 235: ایمپورت در پلتفرم‌های غیرحساس به بزرگی و کوچکی حروف
PEP 263: تعریف کدگذاری‌های کد منبع پایتون
PEP 302: قلاب‌های ایمپورت جدید
PEP 328: ایمپورت‌ها: چندخطی و مطلق/نسبی
PEP 366: ایمپورت‌های نسبی صریح در ماژول اصلی
PEP 420: بسته‌های فضای نام ضمنی
PEP 451: یک نوع ModuleSpec برای سیستم ایمپورت
PEP 488: حذف پرونده‌های PYO
PEP 489: مقداردهی اولیه ماژول توسعه به‌صورت چندمرحله‌ای
PEP 552: پرونده‌های pyc قطعی
PEP 3120: استفاده از UTF-8 به‌عنوان کدگذاری پیش‌فرض منبع
PEP 3147: پوشه‌های مخزن PYC

توابع¶

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)¶: پیاده‌سازی‌ای از تابع توکار __import__().

توجه

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

importlib.import_module(name, package=None)¶

ماژولی را ایمپورت می‌کند. آرگومان name مشخص می‌کند که کدام ماژول باید به‌صورت مطلق یا نسبی ایمپورت شود (برای مثال یا pkg.mod یا ..mod). اگر نام به‌صورت نسبی مشخص شده باشد، آرگومان package باید برابر با نام بسته‌ای تنظیم شود که باید به‌عنوان مبنا برای حل نام بسته عمل کند (برای مثال import_module('..mod', 'pkg.subpkg')، pkg.mod را ایمپورت می‌کند).

تابع import_module() به‌عنوان پوششی ساده‌کننده برای importlib.__import__() عمل می‌کند. این بدان معناست که تمام معناشناسی این تابع از importlib.__import__() مشتق شده است. مهم‌ترین تفاوت بین این دو تابع این است که import_module() بسته یا ماژول مشخص‌شده (مثلاً pkg.mod) را برمی‌گرداند، در حالی که __import__() بسته یا ماژول سطح بالا (مثلاً pkg) را برمی‌گرداند.

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

تغییر یافته در نسخه‌ی 3.3: بسته‌های والد به‌طور خودکار ایمپورت می‌شوند.

importlib.invalidate_caches()¶: نهانگاه‌های داخلی یابنده‌های ذخیره‌شده در sys.meta_path را بی‌اعتبار می‌کند. اگر یک یابنده invalidate_caches() را پیاده‌سازی کرده باشد، برای انجام بی‌اعتبارسازی فراخوانی می‌شود. اگر در حین اجرای برنامه شما ماژول‌هایی ایجاد/نصب شوند، باید این تابع فراخوانی شود تا تضمین شود همه یابنده‌ها از وجود ماژول جدید آگاه شوند.

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

تغییر یافته در نسخه‌ی 3.10: بسته‌های فضای نامی که پس از آنکه همان فضای نام از قبل ایمپورت شده است، در مکان متفاوتی از sys.path ایجاد/نصب می‌شوند، شناسایی می‌شوند.

importlib.reload(module)¶

یک ماژول را که قبلاً ایمپورت‌شده است مجدداً بارگذاری کنید. آرگومان باید یک شیء ماژول باشد، بنابراین باید قبلاً با موفقیت ایمپورت‌شده باشد. این زمانی مفید است که پرونده منبع ماژول را با استفاده از یک ویرایشگر خارجی ویرایش کرده باشید و بخواهید نسخه‌ی جدید را بدون خروج از مفسر پایتون امتحان کنید. مقدار بازگشتی، شیء ماژول است (که می‌تواند متفاوت باشد اگر ایمپورت مجدد باعث شود شیء دیگری در sys.modules قرار گیرد).

هنگامی که reload() اجرا می‌شود:

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

تعدادی هشدار دیگر نیز وجود دارد:

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

try:
    cache
except NameError:
    cache = {}

به‌طور کلی، بارگذاری مجدد ماژول‌های توکار یا ماژول‌هایی که به‌صورت پویا بارگذاری می‌شوند، چندان مفید نیست. بارگذاری مجدد sys، __main__، builtins و سایر ماژول‌های کلیدی توصیه نمی‌شود. در بسیاری از موارد، ماژول‌های توسعه‌ای برای مقداردهی اولیه بیش از یک بار طراحی نشده‌اند و ممکن است هنگام بارگذاری مجدد به روش‌های نامشخصی با شکست مواجه شوند.

اگر ماژولی اشیایی را از ماژول دیگری با استفاده از from ... import ... ایمپورت کند، فراخوانی reload() برای ماژول دیگر، اشیای ایمپورت‌شده از آن را بازتعریف نمی‌کند — یکی از راه‌های رفع این مسئله اجرای دوباره‌ی دستور from است؛ راه دیگر استفاده از import و نام‌های کامل (module.name) به‌جای آن است.

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

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

تغییر یافته در نسخه‌ی 3.7: ModuleNotFoundError هنگامی پرتاب می‌شود که ماژولِ در حال بارگذاری مجدد، فاقد یک ModuleSpec باشد.

هشدار

این تابع نخ‌ایمن نیست. فراخوانی آن از چندین نخ می‌تواند منجر به رفتار غیرمنتظره شود. توصیه می‌شود برای بارگذاری مجدد ماژول به‌صورت نخ‌ایمن، از threading.Lock یا سایر اولیه‌های همگام‌سازی استفاده کنید.

`importlib.abc` -- کلاس‌های پایه انتزاعی مرتبط با ایمپورت¶

کد منبع: Lib/importlib/abc.py

ماژول importlib.abc شامل تمام کلاس‌های پایه انتزاعی اصلی است که import از آن‌ها استفاده می‌کند. همچنین برخی از زیرکلاس‌های این کلاس‌های پایه انتزاعی اصلی نیز برای کمک به پیاده‌سازی آن‌ها ارائه شده‌اند.

سلسله‌مراتب ABC:

object
 +-- MetaPathFinder
 +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader

class importlib.abc.MetaPathFinder¶

یک کلاس پایه انتزاعی که نشان‌دهنده‌ی یک meta path finder است.

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

تغییر یافته در نسخه‌ی 3.10: دیگر زیرکلاسی از Finder نیست.

find_spec(fullname, path, target=None)¶: یک متد انتزاعی برای یافتن یک مشخصه برای ماژول مشخص‌شده. اگر این یک ایمپورت سطح بالا باشد، path برابر None خواهد بود. در غیر این صورت، این یک جست‌وجو برای یک زیربسته یا ماژول است و path برابر مقدار __path__ از بسته والد خواهد بود. اگر مشخصه‌ای یافت نشود، None برگردانده می‌شود. در صورت ارسال، target یک شیء ماژول است که یابنده می‌تواند از آن استفاده کند تا حدس آگاهانه‌تری درباره مشخصه‌ای که باید برگردانده شود، بزند. importlib.util.spec_from_loader() ممکن است برای پیاده‌سازی MetaPathFinders عینی مفید باشد.

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

invalidate_caches()¶: یک متد اختیاری که هرگاه فراخوانی شود، باید هر نهانگاه داخلی استفاده‌شده توسط یابنده را بی‌اعتبار کند. توسط importlib.invalidate_caches() هنگام بی‌اعتبار کردن نهانگاه‌های همه‌ی یابنده‌ها در sys.meta_path استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.4: هنگام فراخوانی، به جای NotImplemented، None را بازمی‌گرداند.

class importlib.abc.PathEntryFinder¶

یک کلاس پایه انتزاعی که نشان‌دهنده‌ی یک path entry finder است. اگرچه این کلاس شباهت‌هایی به MetaPathFinder دارد، اما PathEntryFinder تنها برای استفاده در زیرسیستم ایمپورت مبتنی بر مسیر که توسط importlib.machinery.PathFinder ارائه می‌شود، در نظر گرفته شده است.

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

تغییر یافته در نسخه‌ی 3.10: دیگر زیرکلاسی از Finder نیست.

find_spec(fullname, target=None)¶: یک متد انتزاعی برای یافتن یک spec برای ماژول مشخص‌شده. یابنده فقط در path entry ای که به آن اختصاص داده شده است، ماژول را جست‌وجو می‌کند. اگر spec یافت نشود، None بازگردانده می‌شود. هنگامی که target ارائه شود، یک شیء ماژول است که یابنده می‌تواند از آن برای حدس آگاهانه‌تر درباره‌ی اینکه کدام spec باید بازگردانده شود استفاده کند. importlib.util.spec_from_loader() ممکن است برای پیاده‌سازی PathEntryFinders عینی مفید باشد.

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

invalidate_caches()¶: یک متد اختیاری که هرگاه فراخوانی شود، باید هر نهانگاه داخلی به‌کاررفته توسط یابنده را نامعتبر کند. این متد توسط importlib.machinery.PathFinder.invalidate_caches() هنگام نامعتبر کردن نهانگاه‌های همه‌ی یابنده‌های موجود در نهانگاه استفاده می‌شود.

class importlib.abc.Loader¶

یک کلاس پایه انتزاعی برای بارگذار. برای تعریف دقیق بارگذار، PEP 302 را ببینید.

Loaders that wish to support resource reading should implement a get_resource_reader() method as specified by importlib.resources.abc.ResourceReader.

تغییر یافته در نسخه‌ی 3.7: Introduced the optional get_resource_reader() method.

create_module(spec)¶: متدی که شیء ماژول را برای استفاده هنگام ایمپورت یک ماژول برمی‌گرداند. این متد ممکن است None را برگرداند، که نشان می‌دهد باید معناشناسی پیش‌فرض ایجاد ماژول صورت گیرد.

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

تغییر یافته در نسخه‌ی 3.6: این متد دیگر زمانی که exec_module() تعریف شده باشد، اختیاری نیست.

exec_module(module)¶: یک متد انتزاعی که ماژول را در فضای نام خودش اجرا می‌کند، هنگامی که یک ماژول ایمپورت یا بارگذاری مجدد می‌شود. ماژول باید هنگام فراخوانی exec_module() از قبل مقداردهی اولیه شده باشد. هنگامی که این متد وجود دارد، create_module() باید تعریف شده باشد.

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

تغییر یافته در نسخه‌ی 3.6: create_module() نیز باید تعریف شود.

load_module(fullname)¶

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

اگر ماژول درخواست‌شده از قبل در sys.modules وجود داشته باشد، باید از همان ماژول استفاده شود و آن ماژول دوباره بارگذاری شود. در غیر این صورت، بارگذار باید یک ماژول جدید ایجاد کند و آن را پیش از آغاز هرگونه بارگذاری در sys.modules درج کند تا از بازگشت ناشی از ایمپورت جلوگیری شود. اگر بارگذار ماژولی را درج کرد و بارگذاری شکست خورد، بارگذار باید آن را از sys.modules حذف کند؛ ماژول‌هایی که پیش از آغاز اجرای بارگذار از قبل در sys.modules وجود داشته‌اند، باید دست‌نخورده باقی بمانند.

بارگذار باید چندین ویژگی را روی ماژول تنظیم کند (توجه داشته باشید که برخی از این ویژگی‌ها ممکن است هنگام بارگذاری مجدد یک ماژول تغییر کنند):

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

تغییر یافته در نسخه‌ی 3.4: هنگام فراخوانی، به‌جای NotImplementedError، ImportError پرتاب می‌کند. قابلیت ارائه‌شده زمانی در دسترس است که exec_module() موجود باشد.

منسوخ شده از نسخه‌ی 3.4, در نسخه‌ی 3.15 حذف خواهد شد: API توصیه‌شده برای بارگذاری یک ماژول، exec_module() (و create_module()) است. بارگذارها باید به جای load_module() آن را پیاده‌سازی کنند. سازوکار ایمپورت تمام مسئولیت‌های دیگر load_module() را هنگامی که exec_module() پیاده‌سازی شود، بر عهده می‌گیرد.

class importlib.abc.ResourceLoader¶

جایگزین‌شده با TraversableResources

یک کلاس پایه انتزاعی برای یک بارگذار که پروتکل اختیاری PEP 302 را برای بارگذاری منابع دلخواه از بک‌اند ذخیره‌سازی پیاده‌سازی می‌کند.

منسوخ شده از نسخه‌ی 3.7: این ABC منسوخ شده است و به‌جای آن پشتیبانی از بارگذاری منابع از طریق importlib.resources.abc.TraversableResources توصیه می‌شود. این کلاس تنها برای سازگاری رو به عقب با سایر ABCهای این ماژول وجود دارد.

abstractmethod get_data(path)¶

یک متد انتزاعی برای برگرداندن بایت‌های داده واقع در path. بارگذارهایی که پشتیبان ذخیره‌سازی شبه‌پرونده با قابلیت ذخیره داده دلخواه دارند، می‌توانند این متد انتزاعی را پیاده‌سازی کنند تا دسترسی مستقیم به داده‌های ذخیره‌شده فراهم شود. اگر path یافت نشد، باید OSError پرتاب شود. انتظار می‌رود path با استفاده از ویژگی __file__ یک ماژول یا یکی از آیتم‌های __path__ یک بسته ساخته شود.

تغییر یافته در نسخه‌ی 3.4: OSError را به‌جای NotImplementedError پرتاب می‌کند.

class importlib.abc.InspectLoader¶

یک کلاس پایه انتزاعی برای یک بارگذار که پروتکل اختیاری PEP 302 را برای بارگذارهایی که ماژول‌ها را بازرسی می‌کنند، پیاده‌سازی می‌کند.

get_code(fullname)¶: شیء کد یک ماژول را برمی‌گرداند، یا اگر ماژول شیء کد نداشته باشد، None را برمی‌گرداند (همان‌طور که برای مثال برای یک ماژول توکار این‌گونه است). اگر بارگذار نتواند ماژول درخواست‌شده را پیدا کند، استثنای ImportError را پرتاب می‌کند.

توجه

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

تغییر یافته در نسخه‌ی 3.4: دیگر انتزاعی نیست و یک پیاده‌سازی عینی ارائه شده است.

abstractmethod get_source(fullname)¶: یک متد انتزاعی برای برگرداندن کد منبع یک ماژول. این کد منبع به‌صورت یک رشته‌ی متنی و با استفاده از سطرهای جدید همگانی (universal newlines) برگردانده می‌شود، به‌طوری‌که همه‌ی جداکننده‌های خطِ شناخته‌شده به نویسه‌های '\n' تبدیل می‌شوند. اگر هیچ کد منبعی در دسترس نباشد (برای نمونه، یک ماژول توکار)، None را برمی‌گرداند. اگر بارگذار نتواند ماژول مشخص‌شده را پیدا کند، ImportError را پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.4: ImportError را به‌جای NotImplementedError پرتاب می‌کند.

is_package(fullname)¶: یک متد اختیاری برای برگرداندن مقداری درست اگر ماژول یک بسته باشد، و مقداری نادرست در غیر این صورت. اگر بارگذار نتواند ماژول را بیابد، استثنای ImportError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.4: ImportError را به‌جای NotImplementedError پرتاب می‌کند.

static source_to_code(data, path='<string>')¶

یک شیء کد از کد منبع پایتون ایجاد کنید.

آرگومان data می‌تواند هر چیزی باشد که تابع compile() از آن پشتیبانی می‌کند (یعنی رشته یا بایت). آرگومان path باید «مسیر» به جایی باشد که کد منبع از آن منشأ گرفته است، که می‌تواند مفهومی انتزاعی باشد (مثلاً موقعیت در یک پرونده zip).

با استفاده از شیء کد متعاقب، می‌توان آن را در یک ماژول با اجرای exec(code, module.__dict__) اجرا کرد.

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

تغییر یافته در نسخه‌ی 3.5: متد را ایستا کرد.

exec_module(module)¶: پیاده‌سازی Loader.exec_module().

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

load_module(fullname)¶: پیاده‌سازی Loader.load_module().

منسوخ شده از نسخه‌ی 3.4, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از exec_module() استفاده کنید.

class importlib.abc.ExecutionLoader¶

یک کلاس پایه انتزاعی که از InspectLoader ارث می‌برد و هنگامی که پیاده‌سازی شود، به اجرای یک ماژول به‌عنوان اسکریپت کمک می‌کند. این کلاس پایه انتزاعی (ABC) نشان‌دهنده‌ی یک پروتکل اختیاری PEP 302 است.

abstractmethod get_filename(fullname)¶: یک متد انتزاعی که باید مقدار __file__ را برای ماژول مشخص‌شده برگرداند. اگر مسیری در دسترس نباشد، ImportError پرتاب می‌شود.

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

تغییر یافته در نسخه‌ی 3.4: ImportError را به‌جای NotImplementedError پرتاب می‌کند.

class importlib.abc.FileLoader(fullname, path)¶

یک کلاس پایه انتزاعی که از ResourceLoader و ExecutionLoader ارث می‌برد و پیاده‌سازی‌های عینی ResourceLoader.get_data() و ExecutionLoader.get_filename() را ارائه می‌کند.

آرگومان fullname، نام کاملاً حل‌شده‌ی ماژولی است که بارگذار باید آن را مدیریت کند. آرگومان path، مسیر پرونده ماژول است.

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

name¶: نام ماژولی که بارگذار می‌تواند آن را مدیریت کند.

path¶: مسیر پرونده ماژول.

load_module(fullname)¶: متد load_module() ابرکلاس را فراخوانی می‌کند.

منسوخ شده از نسخه‌ی 3.4, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از Loader.exec_module() استفاده کنید.

abstractmethod get_filename(fullname)¶: path را برمی‌گرداند.

abstractmethod get_data(path)¶: path را به‌عنوان یک پرونده دودویی می‌خواند و بایت‌های آن را برمی‌گرداند.

class importlib.abc.SourceLoader¶

یک کلاس پایه انتزاعی برای پیاده‌سازی بارگذاری پرونده منبع (و به‌صورت اختیاری بایت‌کد). این کلاس از هر دو ResourceLoader و ExecutionLoader ارث می‌برد و پیاده‌سازی موارد زیر را الزامی می‌کند:

ResourceLoader.get_data()
ExecutionLoader.get_filename()
باید فقط مسیر پرونده منبع را برگرداند؛ بارگذاری بدون منبع پشتیبانی نمی‌شود.

هدف از متدهای انتزاعی تعریف‌شده در این کلاس، افزودن پشتیبانی اختیاری از پرونده‌های بایت‌کد است. پیاده‌سازی نکردن این متدهای اختیاری (یا باعث پرتاب NotImplementedError شدن آن‌ها) موجب می‌شود بارگذار تنها با کد منبع کار کند. پیاده‌سازی این متدها به بارگذار اجازه می‌دهد با پرونده‌های منبع و پرونده‌های بایت‌کد کار کند؛ این کار امکان بارگذاری بدون منبع را که در آن فقط بایت‌کد ارائه می‌شود، فراهم نمی‌کند. پرونده‌های بایت‌کد یک بهینه‌سازی برای افزایش سرعت بارگذاری از طریق حذف مرحله‌ی تجزیه‌ی کامپایلر پایتون هستند، و بنابراین هیچ API مختص بایت‌کدی در دسترس قرار نمی‌گیرد.

path_stats(path)¶

متد انتزاعی اختیاری که یک dict حاوی فراداده درباره‌ی مسیر مشخص‌شده را برمی‌گرداند. کلیدهای پشتیبانی‌شده‌ی دیکشنری عبارتند از:

'mtime' (الزامی): یک عدد صحیح یا عدد ممیز شناور که نشان‌دهنده‌ی زمان تغییر کد منبع است؛
'size' (اختیاری): اندازه‌ی کد منبع بر حسب بایت.

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

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

تغییر یافته در نسخه‌ی 3.4: OSError را به‌جای NotImplementedError پرتاب می‌کند.

path_mtime(path)¶: متد انتزاعی اختیاری که زمان تغییر مسیر مشخص‌شده را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.3: این متد منسوخ شده است و استفاده از path_stats() به جای آن توصیه می‌شود. شما لازم نیست آن را پیاده‌سازی کنید، اما همچنان برای اهداف سازگاری در دسترس است. اگر مسیر قابل مدیریت نباشد، OSError را پرتاب کنید.

تغییر یافته در نسخه‌ی 3.4: OSError را به‌جای NotImplementedError پرتاب می‌کند.

set_data(path, data)¶

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

هنگامی که نوشتن در مسیر به دلیل فقط‌خواندنی بودن مسیر ناموفق باشد (errno.EACCES/PermissionError)، استثنا را منتشر نکنید.

تغییر یافته در نسخه‌ی 3.4: دیگر هنگام فراخوانی، NotImplementedError را پرتاب نمی‌کند.

get_code(fullname)¶: پیاده‌سازی مشخص برای InspectLoader.get_code().

exec_module(module)¶: پیاده‌سازی عینی Loader.exec_module().

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

load_module(fullname)¶: پیاده‌سازی عینی Loader.load_module().

منسوخ شده از نسخه‌ی 3.4, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از exec_module() استفاده کنید.

get_source(fullname)¶: پیاده‌سازی عینی برای InspectLoader.get_source().

is_package(fullname)¶: پیاده‌سازی عینی InspectLoader.is_package(). یک ماژول در صورتی به‌عنوان یک بسته تشخیص داده می‌شود که مسیر پرونده آن (همان‌طور که توسط ExecutionLoader.get_filename() ارائه می‌شود) پس از حذف پسوند پرونده، پرونده‌ای به نام __init__ باشد و نام خود ماژول به __init__ ختم نشود.

`importlib.machinery` -- ایمپورت‌کننده‌ها و قلاب‌های مسیر (path hooks)¶

کد منبع: Lib/importlib/machinery.py

این ماژول شامل اشیاء مختلفی است که به import در یافتن و بارگذاری ماژول‌ها کمک می‌کنند.

importlib.machinery.SOURCE_SUFFIXES¶: فهرستی از رشته‌ها که پسوندهای پرونده شناسایی‌شده برای ماژول‌های منبع را نشان می‌دهد.

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

importlib.machinery.DEBUG_BYTECODE_SUFFIXES¶: فهرستی از رشته‌ها که پسوندهای پرونده برای ماژول‌های بایت‌کد بهینه‌نشده را نشان می‌دهند.

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

منسوخ شده از نسخه‌ی 3.5: به‌جای آن از BYTECODE_SUFFIXES استفاده کنید.

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES¶: فهرستی از رشته‌ها که نشان‌دهنده‌ی پسوندهای پرونده برای ماژول‌های بایت‌کد بهینه‌شده هستند.

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

منسوخ شده از نسخه‌ی 3.5: به‌جای آن از BYTECODE_SUFFIXES استفاده کنید.

importlib.machinery.BYTECODE_SUFFIXES¶: فهرستی از رشته‌ها که نشان‌دهنده‌ی پسوندهای پرونده شناسایی‌شده برای ماژول‌های بایت‌کد هستند (شامل نقطه‌ی پیشرو).

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

تغییر یافته در نسخه‌ی 3.5: این مقدار دیگر وابسته به __debug__ نیست.

importlib.machinery.EXTENSION_SUFFIXES¶: فهرستی از رشته‌ها که پسوندهای پرونده به‌رسمیت شناخته‌شده برای ماژول‌های افزونه را نشان می‌دهند.

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

importlib.machinery.all_suffixes()¶: فهرست ترکیبی از رشته‌ها را برمی‌گرداند که نشان‌دهنده‌ی تمام پسوندهای پرونده برای ماژول‌های شناخته‌شده توسط سازوکار ایمپورت استاندارد است. این یک تابع کمکی برای کدی است که صرفاً نیاز دارد بداند آیا یک مسیر سامانه فایل‌بندی به‌طور بالقوه به یک ماژول اشاره می‌کند یا خیر، بدون این‌که به هیچ جزئیاتی درباره‌ی نوع ماژول نیاز داشته باشد (برای مثال، inspect.getmodulename()).

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

class importlib.machinery.BuiltinImporter¶

یک importer برای ماژول‌های توکار. همه‌ی ماژول‌های توکار شناخته‌شده در sys.builtin_module_names فهرست شده‌اند. این کلاس، ABCهای importlib.abc.MetaPathFinder و importlib.abc.InspectLoader را پیاده‌سازی می‌کند.

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

تغییر یافته در نسخه‌ی 3.5: As part of PEP 489, the builtin importer now implements Loader.create_module and Loader.exec_module

class importlib.machinery.FrozenImporter¶

یک ایمپورت‌کننده (importer) برای ماژول‌های فریز. این کلاس، کلاس‌های پایه انتزاعی (ABCs) importlib.abc.MetaPathFinder و importlib.abc.InspectLoader را پیاده‌سازی می‌کند.

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

تغییر یافته در نسخه‌ی 3.4: Gained create_module() and exec_module() methods.

class importlib.machinery.WindowsRegistryFinder¶

یابنده برای ماژول‌های اعلام‌شده در رجیستری ویندوز. این کلاس ABC importlib.abc.MetaPathFinder را پیاده‌سازی می‌کند.

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

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

منسوخ شده از نسخه‌ی 3.6: به‌جای آن از پیکربندی site استفاده کنید. ممکن است نسخه‌های آینده پایتون این یابنده را به‌طور پیش‌فرض فعال نکنند.

class importlib.machinery.PathFinder¶

یک یابنده برای sys.path و ویژگی‌های __path__ بسته. این کلاس، ABC importlib.abc.MetaPathFinder را پیاده‌سازی می‌کند.

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

classmethod find_spec(fullname, path=None, target=None)¶: متد کلاسی که تلاش می‌کند یک spec برای ماژول مشخص‌شده با fullname در sys.path یا، اگر تعریف شده باشد، در path پیدا کند. برای هر آیتم مسیری که جستجو می‌شود، sys.path_importer_cache بررسی می‌شود. اگر یک شیء غیرکاذب پیدا شود، از آن به‌عنوان path entry finder برای جستجوی ماژول مورد نظر استفاده می‌شود. اگر هیچ آیتمی در sys.path_importer_cache پیدا نشود، آنگاه در sys.path_hooks به دنبال یک یابنده برای آن آیتم مسیر گشته می‌شود و در صورت پیدا شدن، در sys.path_importer_cache ذخیره می‌شود و همچنین در مورد ماژول از آن پرس‌وجو می‌شود. اگر هیچ یابنده‌ای هرگز پیدا نشود، آنگاه None هم در نهانگاه ذخیره می‌شود و هم بازگردانده می‌شود.

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

تغییر یافته در نسخه‌ی 3.5: اگر پوشه کاری جاری — که با یک رشته خالی نمایش داده می‌شود — دیگر معتبر نباشد، None برگردانده می‌شود، اما هیچ مقداری در نهانگاه sys.path_importer_cache ذخیره نمی‌شود.

classmethod invalidate_caches()¶: importlib.abc.PathEntryFinder.invalidate_caches() را روی تمام یابنده‌های ذخیره‌شده در sys.path_importer_cache که این متد را تعریف می‌کنند، فراخوانی می‌کند. در غیر این صورت، ورودی‌های موجود در sys.path_importer_cache که روی None تنظیم شده‌اند، حذف می‌شوند.

تغییر یافته در نسخه‌ی 3.7: ورودی‌های None در sys.path_importer_cache حذف می‌شوند.

تغییر یافته در نسخه‌ی 3.4: اشیاء موجود در sys.path_hooks را با پوشه کاری فعلی برای '' (یعنی رشته خالی) فراخوانی می‌کند.

class importlib.machinery.FileFinder(path, *loader_details)¶

یک پیاده‌سازی عینی از importlib.abc.PathEntryFinder که نتایج حاصل از سامانه فایل‌بندی را در نهانگاه ذخیره می‌کند.

آرگومان path، پوشه‌ای است که یابنده مسئول جست‌وجوی آن است.

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

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

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

path¶: مسیری که یابنده در آن جستجو خواهد کرد.

find_spec(fullname, target=None)¶: تلاش می‌کند تا مشخصات را برای رسیدگی به fullname در path بیابد.

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

invalidate_caches()¶: نهانگاه داخلی را پاک کنید.

classmethod path_hook(*loader_details)¶

یک متد کلاس که یک بستار را برای استفاده در sys.path_hooks برمی‌گرداند. نمونه‌ای از FileFinder توسط این بستار برگردانده می‌شود؛ این بستار از آرگومان path داده‌شده به خود به‌صورت مستقیم و از loader_details به‌صورت غیرمستقیم استفاده می‌کند.

اگر آرگومانِ بسته یک پوشه‌ی موجود نباشد، ImportError پرتاب می‌شود.

class importlib.machinery.SourceFileLoader(fullname, path)¶

یک پیاده‌سازی عینی از importlib.abc.SourceLoader با زیرکلاس‌سازی از importlib.abc.FileLoader و ارائه پیاده‌سازی‌های عینی برای برخی متدهای دیگر.

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

name¶: نام ماژولی که این بارگذار آن را مدیریت خواهد کرد.

path¶: مسیر پرونده منبع.

is_package(fullname)¶: اگر به نظر برسد که path مربوط به یک بسته است، True را برمی‌گرداند.

path_stats(path)¶: پیاده‌سازی عینی importlib.abc.SourceLoader.path_stats().

set_data(path, data)¶: پیاده‌سازی عینی importlib.abc.SourceLoader.set_data().

load_module(name=None)¶: پیاده‌سازی عینی importlib.abc.Loader.load_module() که در آن مشخص کردن نام ماژول برای بارگذاری اختیاری است.

منسوخ شده از نسخه‌ی 3.6, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از importlib.abc.Loader.exec_module() استفاده کنید.

class importlib.machinery.SourcelessFileLoader(fullname, path)¶

یک پیاده‌سازی عینی از importlib.abc.FileLoader که می‌تواند پرونده‌های بایت‌کد را ایمپورت کند (یعنی هیچ پرونده کد منبعی وجود ندارد).

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

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

name¶: نام ماژولی که بارگذار آن را مدیریت خواهد کرد.

path¶: مسیر پرونده بایت‌کد .

is_package(fullname)¶: بر اساس path تعیین می‌کند که آیا ماژول یک بسته است یا خیر.

get_code(fullname)¶: شیء کد برای name را که از path ایجاد شده است، برمی‌گرداند.

get_source(fullname)¶: None را برمی‌گرداند، زیرا هنگام استفاده از این بارگذار، پرونده‌های بایت‌کد کد منبع ندارند.

load_module(name=None)¶

پیاده‌سازی عینی importlib.abc.Loader.load_module() که در آن مشخص کردن نام ماژول برای بارگذاری اختیاری است.

منسوخ شده از نسخه‌ی 3.6, در نسخه‌ی 3.15 حذف خواهد شد: به‌جای آن از importlib.abc.Loader.exec_module() استفاده کنید.

class importlib.machinery.ExtensionFileLoader(fullname, path)¶

یک پیاده‌سازی عینی از importlib.abc.ExecutionLoader برای ماژول‌های توسعه‌ای.

آرگومان fullname نام ماژولی را مشخص می‌کند که بارگذار باید از آن پشتیبانی کند. آرگومان path مسیر پرونده ماژول توسعه‌ای است.

توجه داشته باشید که به‌طور پیش‌فرض، ایمپورت یک ماژول توسعه‌ای در زیرمفسرها، اگر مقداردهی اولیه چندمرحله‌ای را پیاده‌سازی نکرده باشد (به PEP 489 مراجعه کنید)، با شکست مواجه خواهد شد؛ حتی اگر در غیر این صورت بتواند با موفقیت ایمپورت شود.

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

تغییر یافته در نسخه‌ی 3.12: مقداردهی اولیه چندمرحله‌ای اکنون برای استفاده در زیرمفسرها الزامی است.

name¶: نام ماژولی که بارگذار از آن پشتیبانی می‌کند.

path¶: مسیر ماژول توسعه‌ای.

create_module(spec)¶: شیء ماژول را مطابق PEP 489 از مشخصات داده‌شده ایجاد می‌کند.

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

exec_module(module)¶: شیء ماژول داده‌شده را مطابق PEP 489 مقداردهی اولیه می‌کند.

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

is_package(fullname)¶: اگر مسیر پرونده بر اساس EXTENSION_SUFFIXES به ماژول __init__ یک بسته اشاره داشته باشد، True برگردانده می‌شود.

get_code(fullname)¶: None را برمی‌گرداند، زیرا ماژول‌های توسعه‌ای فاقد شیء کد هستند.

get_source(fullname)¶: None را برمی‌گرداند، زیرا ماژول‌های توسعه‌ای کد منبع ندارند.

get_filename(fullname)¶: path را برمی‌گرداند.

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

class importlib.machinery.NamespaceLoader(name, path, path_finder)¶

یک پیاده‌سازی عینی از importlib.abc.InspectLoader برای بسته‌های فضای نام. این یک نام مستعار برای یک کلاس خصوصی است و تنها برای درون‌نگری ویژگی __loader__ در بسته‌های فضای نام عمومی شده است:

>>> from importlib.machinery import NamespaceLoader
>>> import my_namespace
>>> isinstance(my_namespace.__loader__, NamespaceLoader)
True
>>> import importlib.abc
>>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
True

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

class importlib.machinery.ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)¶

مشخصاتی برای وضعیت مرتبط با سامانه‌ی ایمپورت یک ماژول. این مشخصات معمولاً به‌عنوان ویژگی __spec__ ماژول در معرض دید قرار می‌گیرد. بسیاری از این ویژگی‌ها نیز به‌طور مستقیم روی یک ماژول در دسترس هستند: برای مثال، module.__spec__.origin == module.__file__. با این حال، توجه داشته باشید که اگرچه مقادیر معمولاً معادل‌اند، ممکن است متفاوت باشند، زیرا هیچ همگام‌سازی‌ای بین این دو شیء وجود ندارد. برای مثال، ممکن است ویژگی __file__ ماژول را در ران‌تایم به‌روزرسانی کنید و این به‌روزرسانی به‌طور خودکار در __spec__.origin ماژول منعکس نمی‌شود، و برعکس.

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

name¶: نام کاملاً مشخص ماژول (به module.__name__ مراجعه کنید). finder باید همیشه این ویژگی را روی یک رشته غیرخالی تنظیم کند.

loader¶: بارگذار مورد استفاده برای بارگذاری ماژول (ببینید module.__loader__). یابنده باید همیشه این ویژگی را تنظیم کند.

origin¶: محلی که بارگذار باید برای بارگذاری ماژول از آن استفاده کند (module.__file__ را ببینید). برای مثال، برای ماژول‌هایی که از یک پرونده .py بارگذاری شده‌اند، این مقدار نام پرونده است. finder باید همیشه این ویژگی را روی مقداری معنادار تنظیم کند تا بارگذار از آن استفاده کند. در حالت غیرمعمولی که چنین محلی وجود ندارد (مانند بسته‌های فضای نام)، باید روی None تنظیم شود.

submodule_search_locations¶

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

یابنده باید این ویژگی را روی یک دنباله، حتی یک دنباله خالی، تنظیم کند تا به سامانه‌ی ایمپورت نشان دهد که ماژول یک بسته است. این ویژگی باید برای ماژول‌هایی که بسته نیستند روی None تنظیم شود. این ویژگی برای بسته‌های فضای نام، بعداً به‌طور خودکار روی یک شیء خاص تنظیم می‌شود.

loader_state¶: یابنده ممکن است این ویژگی را روی شیءای حاوی داده‌های اضافی و مختص ماژول برای استفاده هنگام بارگذاری ماژول تنظیم کند. در غیر این صورت باید روی None تنظیم شود.

cached¶: نام پرونده‌ی یک نسخه‌ی کامپایل‌شده از کد ماژول (ببینید module.__cached__). finder باید همیشه این ویژگی را تنظیم کند، اما ممکن است برای ماژول‌هایی که نیازی به ذخیره‌ی کد کامپایل‌شده ندارند، None باشد.

parent¶: (فقط‌خواندنی) نام کامل بسته‌ای که ماژول در آن قرار دارد (یا رشته‌ی خالی برای یک ماژول سطح بالا). به module.__package__ مراجعه کنید. اگر ماژول یک بسته باشد، این با name یکسان است.

has_location¶: اگر origin متعلق به مشخصات به یک محل قابل بارگذاری اشاره کند، True است؛ در غیر این صورت False است. این مقدار بر چگونگی تفسیر origin و چگونگی مقداردهی __file__ ماژول تأثیر می‌گذارد.

class importlib.machinery.AppleFrameworkLoader(name, path)¶

نسخه‌ای تخصصی از importlib.machinery.ExtensionFileLoader که می‌تواند ماژول‌های توسعه‌ای را در قالب چارچوب بارگذاری کند.

برای سازگاری با iOS App Store، همه ماژول‌های دودویی در یک برنامه iOS باید کتابخانه‌های پویا باشند، در چارچوبی با فراداده مناسب قرار بگیرند و در پوشه Frameworks برنامه بسته‌بندی‌شده ذخیره شوند. به ازای هر چارچوب فقط یک دودویی می‌تواند وجود داشته باشد و هیچ محتوای دودویی اجرایی خارج از پوشه Frameworks نمی‌تواند وجود داشته باشد.

برای برآورده‌کردن این نیاز، هنگام اجرا در iOS، پرونده‌های دودویی ماژول‌های توسعه‌ای به‌صورت پرونده‌های .so در sys.path بسته‌بندی نمی‌شوند، بلکه به‌صورت چارچوب‌های مستقل و جداگانه بسته‌بندی می‌شوند. برای کشف این چارچوب‌ها، این بارگذار برای پسوند پرونده .fwork ثبت می‌شود، به‌طوری که یک پرونده .fwork به‌عنوان جای‌نگهدار در محل اصلی دودویی در sys.path عمل می‌کند. پرونده .fwork شامل مسیر دودویی واقعی در پوشه‌ی Frameworks، نسبت به بسته‌ی برنامه (app bundle) است. برای اینکه بتوان یک دودویی بسته‌بندی‌شده در چارچوب را به مکان اصلی بازگرداند، انتظار می‌رود چارچوب حاوی یک پرونده .origin باشد که مکان پرونده .fwork را، نسبت به بسته‌ی برنامه، شامل می‌شود.

برای مثال، حالت یک ایمپورت from foo.bar import _whiz را در نظر بگیرید، که در آن _whiz با ماژول دودویی sources/foo/bar/_whiz.abi3.so پیاده‌سازی شده است و sources مکانی ثبت‌شده در sys.path و نسبت به بسته‌ی اپلیکیشن نسبی است. این ماژول باید به‌صورت Frameworks/foo.bar._whiz.framework/foo.bar._whiz توزیع شود (نام چارچوب از مسیر کامل ایمپورت ماژول ساخته می‌شود)، به‌همراه یک پرونده Info.plist در پوشه‌ی .framework که پرونده دودویی را به‌عنوان یک چارچوب شناسایی می‌کند. ماژول foo.bar._whiz در مکان اصلی با یک پرونده نشانگر sources/foo/bar/_whiz.abi3.fwork نمایش داده خواهد شد که حاوی مسیر Frameworks/foo.bar._whiz/foo.bar._whiz است. چارچوب همچنین شامل Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin خواهد بود که حاوی مسیر پرونده .fwork است.

هنگامی که یک ماژول با این بارگذار بارگذاری می‌شود، __file__ آن ماژول به‌عنوان مکان پرونده .fwork گزارش می‌شود. این امر به کد اجازه می‌دهد از __file__ یک ماژول به‌عنوان لنگری برای پیمایش سامانه فایل‌بندی استفاده کند. با این حال، منشأ مشخصات (spec origin) به مکان دودویی واقعی در پوشه .framework ارجاع می‌دهد.

پروژه Xcode که اپلیکیشن را می‌سازد، مسئول تبدیل هر پرونده .so از هر محلی که در PYTHONPATH وجود داشته باشد به چارچوب‌هایی در پوشه Frameworks است (شامل حذف پسوندها از پرونده ماژول، افزودن فراداده چارچوب، و امضای چارچوب حاصل)، و ایجاد پرونده‌های .fwork و .origin. این کار معمولاً با یک مرحله‌ی ساخت در پروژه Xcode انجام می‌شود؛ برای جزئیات چگونگی ساخت این مرحله‌ی ساخت، مستندات iOS را ببینید.

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

دسترس‌پذیری: iOS.

name¶: نام ماژولی که بارگذار از آن پشتیبانی می‌کند.

path¶: مسیر پرونده .fwork برای ماژول توسعه‌ای.

`importlib.util` -- کد سودمند برای ایمپورت‌کننده‌ها¶

کد منبع: Lib/importlib/util.py

این ماژول شامل اشیاء مختلفی است که در ساخت یک importer کمک می‌کنند.

importlib.util.MAGIC_NUMBER¶: بایت‌هایی که شماره‌ی نسخه‌ی بایت‌کد را نشان می‌دهند. اگر برای بارگذاری/نوشتن بایت‌کد به کمک نیاز دارید، importlib.abc.SourceLoader را در نظر بگیرید.

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

importlib.util.cache_from_source(path, debug_override=None, *, optimization=None)¶

Return the PEP 3147/PEP 488 path to the byte-compiled file associated with the source path. For example, if path is /foo/bar/baz.py the return value would be /foo/bar/__pycache__/baz.cpython-32.pyc for Python 3.2. The cpython-32 string comes from the current magic tag (see sys.implementation.cache_tag; if it is not defined then NotImplementedError will be raised).

پارامتر optimization برای مشخص کردن سطح بهینه‌سازی پرونده‌ی بایت‌کد استفاده می‌شود. یک رشته خالی نشان‌دهنده‌ی نبود بهینه‌سازی است، بنابراین /foo/bar/baz.py با optimization برابر '' به مسیر بایت‌کد /foo/bar/__pycache__/baz.cpython-32.pyc منجر می‌شود. None باعث می‌شود از سطح بهینه‌سازی مفسر استفاده شود. برای هر مقدار دیگری، از بازنمایی رشته‌ای آن استفاده می‌شود، بنابراین /foo/bar/baz.py با optimization برابر 2 به مسیر بایت‌کد /foo/bar/__pycache__/baz.cpython-32.opt-2.pyc منجر می‌شود. بازنمایی رشته‌ای optimization فقط می‌تواند شامل حروف و ارقام باشد، در غیر این صورت ValueError پرتاب می‌شود.

پارامتر debug_override منسوخ شده است و می‌تواند برای بازنویسی مقدار سیستم برای __debug__ استفاده شود. مقدار True معادل تنظیم optimization به رشته خالی است. مقدار False همانند تنظیم optimization به 1 است. اگر هر دو debug_override و optimization None نباشند، TypeError پرتاب می‌شود.

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

تغییر یافته در نسخه‌ی 3.5: پارامتر optimization افزوده شد و پارامتر debug_override منسوخ شد.

تغییر یافته در نسخه‌ی 3.6: یک شیء شبه‌مسیر را می‌پذیرد.

importlib.util.source_from_cache(path)¶: Given the path to a PEP 3147 file name, return the associated source code file path. For example, if path is /foo/bar/__pycache__/baz.cpython-32.pyc the returned path would be /foo/bar/baz.py. path need not exist, however if it does not conform to PEP 3147 or PEP 488 format, a ValueError is raised. If sys.implementation.cache_tag is not defined, NotImplementedError is raised.

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

تغییر یافته در نسخه‌ی 3.6: یک شیء شبه‌مسیر را می‌پذیرد.

importlib.util.decode_source(source_bytes)¶: بایت‌های داده‌شده را که نشان‌دهنده‌ی کد منبع هستند کدگشایی کنید و آن را به‌صورت رشته‌ای با سطرهای جدید همگانی (universal newlines) برگردانید (همان‌طور که importlib.abc.InspectLoader.get_source() نیاز دارد).

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

importlib.util.resolve_name(name, package)¶

یک نام نسبی ماژول را به یک نام مطلق تبدیل می‌کند.

اگر name هیچ نقطه‌ی آغازینی نداشته باشد، name صرفاً بازگردانده می‌شود. این امر امکان استفاده‌هایی مانند importlib.util.resolve_name('sys', __spec__.parent) را بدون آنکه بررسی شود آیا آرگومان package لازم است یا خیر، فراهم می‌کند.

ImportError پرتاب می‌شود اگر name یک نام نسبی ماژول باشد اما package یک مقدار نادرست باشد (برای مثال None یا رشته‌ی خالی). ImportError همچنین پرتاب می‌شود اگر یک نام نسبی بخواهد از بسته‌ی حاوی خود خارج شود (برای مثال درخواست ..bacon از درون بسته‌ی spam).

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

تغییر یافته در نسخه‌ی 3.9: برای سازگاری بیشتر با دستورهای ایمپورت، در صورت تلاش برای ایمپورت نسبی نامعتبر، به‌جای ValueError، ImportError پرتاب کنید.

importlib.util.find_spec(name, package=None)¶

مشخصات یک ماژول را بیابید، به‌صورت اختیاری نسبت به نام package مشخص‌شده. اگر ماژول در sys.modules باشد، sys.modules[name].__spec__ برگردانده می‌شود (مگر اینکه مشخصات None باشد یا تنظیم‌نشده باشد، که در این صورت ValueError پرتاب می‌شود). در غیر این صورت، جست‌وجویی با استفاده از sys.meta_path انجام می‌شود. اگر مشخصاتی یافت نشود، None برگردانده می‌شود.

اگر name مربوط به یک زیرماژول باشد (شامل نقطه باشد)، ماژول والد به‌طور خودکار ایمپورت می‌شود.

name and package work the same as for importlib.import_module().

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

تغییر یافته در نسخه‌ی 3.7: در صورتی که package در واقع یک بسته نباشد (یعنی فاقد ویژگی __path__ باشد)، ModuleNotFoundError را به‌جای AttributeError پرتاب می‌کند.

importlib.util.module_from_spec(spec)¶

یک ماژول جدید بر اساس spec و spec.loader.create_module ایجاد کنید.

اگر spec.loader.create_module مقدار None را برنگرداند، آنگاه هیچ‌یک از ویژگی‌های از پیش موجود بازنشانی نخواهند شد. همچنین، در صورت فعال شدن در حین دسترسی به spec یا تنظیم یک ویژگی روی ماژول، هیچ AttributeError پرتاب نخواهد شد.

این تابع به استفاده از types.ModuleType برای ایجاد یک ماژول جدید ترجیح داده می‌شود، زیرا از spec استفاده می‌شود تا هر تعداد ممکن از ویژگی‌های کنترل‌شده توسط ایمپورت بر روی ماژول تنظیم شود.

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

importlib.util.spec_from_loader(name, loader, *, origin=None, is_package=None)¶: A factory function for creating a ModuleSpec instance based on a loader. The parameters have the same meaning as they do for ModuleSpec. The function uses available loader APIs, such as InspectLoader.is_package, to fill in any missing information on the spec.

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

importlib.util.spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)¶: یک تابع کارخانه‌ای برای ایجاد یک نمونه از ModuleSpec بر اساس مسیر یک پرونده. اطلاعات گم‌شده در مشخصات با استفاده از APIهای بارگذار و با توجه به این فرض که ماژول مبتنی بر پرونده خواهد بود، پر می‌شود.

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

تغییر یافته در نسخه‌ی 3.6: یک شیء شبه‌مسیر را می‌پذیرد.

importlib.util.source_hash(source_bytes)¶: هش source_bytes را به‌صورت بایت برمی‌گرداند. یک پرونده .pyc مبتنی بر هش، source_hash() محتوای پرونده منبع مربوطه را در سرآیند خود تعبیه می‌کند.

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

importlib.util._incompatible_extension_module_restrictions(*, disable_check)¶

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

توجه داشته باشید که این تابع برای رسیدگی به یک حالت غیرمعمول در نظر گرفته شده است؛ حالتی که احتمالاً در نهایت از بین خواهد رفت. احتمال زیادی وجود دارد که این همان چیزی نباشد که به‌دنبال آن بودید.

می‌توانید همان اثر این تابع را با پیاده‌سازی رابط پایه‌ی init چندمرحله‌ای (PEP 489) و ادعای دروغین پشتیبانی از چند مفسر (یا GIL به‌ازای هر مفسر) به دست آورید.

هشدار

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

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

class importlib.util.LazyLoader(loader)¶

کلاسی که اجرای بارگذار یک ماژول را تا زمانی که به یکی از ویژگی‌های آن ماژول دسترسی صورت گیرد، به تعویق می‌اندازد.

این کلاس فقط با بارگذارهایی کار می‌کند که exec_module() را تعریف می‌کنند، زیرا کنترل بر اینکه چه نوع ماژولی برای ماژول استفاده شود، لازم است. به همان دلایل، متد create_module() بارگذار باید None یا نوعی را برگرداند که ویژگی __class__ آن قابل تغییر باشد و همزمان از slots استفاده نکند. در نهایت، ماژول‌هایی که شیء قرار داده‌شده در sys.modules را جایگزین می‌کنند کار نخواهند کرد، زیرا هیچ راهی برای جایگزینی صحیح و امن ارجاع‌های ماژول در سراسر مفسر وجود ندارد؛ در صورت تشخیص چنین جایگزینی، ValueError پرتاب می‌شود.

توجه

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

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

تغییر یافته در نسخه‌ی 3.6: فراخوانی create_module() آغاز شد و هشدار سازگاری برای importlib.machinery.BuiltinImporter و importlib.machinery.ExtensionFileLoader حذف شد.

classmethod factory(loader)¶

یک متد کلاس که یک شیء فراخوانی‌پذیر برای ایجاد یک بارگذار تنبل برمی‌گرداند. این متد برای استفاده در موقعیت‌هایی در نظر گرفته شده است که بارگذار به‌جای نمونه، به‌صورت کلاس ارسال می‌شود.

suffixes = importlib.machinery.SOURCE_SUFFIXES
loader = importlib.machinery.SourceFileLoader
lazy_loader = importlib.util.LazyLoader.factory(loader)
finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))

مثال‌ها¶

ایمپورت به‌صورت برنامه‌ای¶

برای ایمپورت یک ماژول به‌صورت برنامه‌ای، از importlib.import_module() استفاده کنید.

import importlib

itertools = importlib.import_module('itertools')

بررسی اینکه آیا یک ماژول می‌تواند ایمپورت شود¶

اگر بخواهید بدون انجام واقعی ایمپورت، تشخیص دهید که آیا یک ماژول قابل ایمپورت است یا خیر، باید از importlib.util.find_spec() استفاده کنید.

توجه داشته باشید که اگر name یک زیرماژول باشد (شامل یک نقطه)، importlib.util.find_spec() ماژول والد را ایمپورت می‌کند.

import importlib.util
import sys

# For illustrative purposes.
name = 'itertools'

if name in sys.modules:
    print(f"{name!r} already in sys.modules")
elif (spec := importlib.util.find_spec(name)) is not None:
    # If you chose to perform the actual import ...
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    spec.loader.exec_module(module)
    print(f"{name!r} has been imported")
else:
    print(f"can't find the {name!r} module")

ایمپورت مستقیم یک پرونده منبع¶

این راهکار باید با احتیاط استفاده شود: این تقریبی از یک دستور ایمپورت است که در آن مسیر پرونده به‌طور مستقیم مشخص می‌شود، به جای این‌که sys.path جستجو شود. ابتدا باید جایگزین‌ها در نظر گرفته شوند، مانند تغییر sys.path هنگامی که یک ماژول مناسب مورد نیاز است، یا استفاده از runpy.run_path() هنگامی که فضای نام سراسری حاصل از اجرای یک پرونده پایتون مناسب است.

برای ایمپورت مستقیم یک پرونده منبع پایتون از یک مسیر، از دستورالعمل زیر استفاده کنید:

import importlib.util
import sys


def import_from_path(module_name, file_path):
    spec = importlib.util.spec_from_file_location(module_name, file_path)
    module = importlib.util.module_from_spec(spec)
    sys.modules[module_name] = module
    spec.loader.exec_module(module)
    return module


# For illustrative purposes only (use of `json` is arbitrary).
import json
file_path = json.__file__
module_name = json.__name__

# Similar outcome as `import json`.
json = import_from_path(module_name, file_path)

پیاده‌سازی ایمپورت‌های تنبل¶

مثال زیر نشان می‌دهد که چگونه ایمپورت‌های تنبل را پیاده‌سازی کنید:

>>> import importlib.util
>>> import sys
>>> def lazy_import(name):
...     spec = importlib.util.find_spec(name)
...     loader = importlib.util.LazyLoader(spec.loader)
...     spec.loader = loader
...     module = importlib.util.module_from_spec(spec)
...     sys.modules[name] = module
...     loader.exec_module(module)
...     return module
...
>>> lazy_typing = lazy_import("typing")
>>> #lazy_typing is a real module object,
>>> #but it is not loaded in memory yet.
>>> lazy_typing.TYPE_CHECKING
False

راه‌اندازی یک ایمپورت‌کننده (importer)¶

برای سفارشی‌سازی‌های عمیق ایمپورت، معمولاً می‌خواهید یک importer را پیاده‌سازی کنید. این به معنای مدیریت هر دو جنبه‌ی finder و بارگذار است. بسته به نیاز شما، برای یابنده‌ها دو گونه برای انتخاب وجود دارد: یک meta path finder یا یک path entry finder. مورد اول چیزی است که شما آن را در sys.meta_path قرار می‌دهید، در حالی که مورد دوم چیزی است که با استفاده از یک path entry hook روی sys.path_hooks ایجاد می‌کنید و با ورودی‌های sys.path کار می‌کند تا به‌طور بالقوه یک یابنده ایجاد کند. این مثال به شما نشان می‌دهد که چگونه ایمپورت‌کننده‌های خود را ثبت کنید تا ایمپورت از آن‌ها استفاده کند (برای ایجاد یک ایمپورت‌کننده برای خودتان، مستندات کلاس‌های مناسب تعریف‌شده در این بسته را بخوانید):

import importlib.machinery
import sys

# For illustrative purposes only.
SpamMetaPathFinder = importlib.machinery.PathFinder
SpamPathEntryFinder = importlib.machinery.FileFinder
loader_details = (importlib.machinery.SourceFileLoader,
                  importlib.machinery.SOURCE_SUFFIXES)

# Setting up a meta path finder.
# Make sure to put the finder in the proper location in the list in terms of
# priority.
sys.meta_path.append(SpamMetaPathFinder)

# Setting up a path entry finder.
# Make sure to put the path hook in the proper location in the list in terms
# of priority.
sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))

شبیه‌سازی `importlib.import_module()`¶

خودِ ایمپورت در کد پایتون پیاده‌سازی شده است و همین امر امکان در معرض دید قرار گرفتن بیشترِ سازوکار ایمپورت از طریق importlib را فراهم می‌کند. آنچه در ادامه می‌آید با ارائه یک پیاده‌سازی تقریبی از importlib.import_module() به نشان دادن APIهای مختلفی که importlib در معرض دید قرار می‌دهد کمک می‌کند:

import importlib.util
import sys

def import_module(name, package=None):
    """An approximate implementation of import."""
    absolute_name = importlib.util.resolve_name(name, package)
    try:
        return sys.modules[absolute_name]
    except KeyError:
        pass

    path = None
    if '.' in absolute_name:
        parent_name, _, child_name = absolute_name.rpartition('.')
        parent_module = import_module(parent_name)
        path = parent_module.__spec__.submodule_search_locations
    for finder in sys.meta_path:
        spec = finder.find_spec(absolute_name, path)
        if spec is not None:
            break
    else:
        msg = f'No module named {absolute_name!r}'
        raise ModuleNotFoundError(msg, name=absolute_name)
    module = importlib.util.module_from_spec(spec)
    sys.modules[absolute_name] = module
    spec.loader.exec_module(module)
    if path is not None:
        setattr(parent_module, child_name, module)
    return module

`importlib` --- پیاده‌سازی `import`¶

مقدمه¶

توابع¶

`importlib.abc` -- کلاس‌های پایه انتزاعی مرتبط با ایمپورت¶

`importlib.machinery` -- ایمپورت‌کننده‌ها و قلاب‌های مسیر (path hooks)¶

`importlib.util` -- کد سودمند برای ایمپورت‌کننده‌ها¶

مثال‌ها¶

ایمپورت به‌صورت برنامه‌ای¶

بررسی اینکه آیا یک ماژول می‌تواند ایمپورت شود¶

ایمپورت مستقیم یک پرونده منبع¶

پیاده‌سازی ایمپورت‌های تنبل¶

راه‌اندازی یک ایمپورت‌کننده (importer)¶

شبیه‌سازی `importlib.import_module()`¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

importlib --- پیاده‌سازی import¶

مقدمه¶

توابع¶

importlib.abc -- کلاس‌های پایه انتزاعی مرتبط با ایمپورت¶

importlib.machinery -- ایمپورت‌کننده‌ها و قلاب‌های مسیر (path hooks)¶

importlib.util -- کد سودمند برای ایمپورت‌کننده‌ها¶

مثال‌ها¶

ایمپورت به‌صورت برنامه‌ای¶

بررسی اینکه آیا یک ماژول می‌تواند ایمپورت شود¶

ایمپورت مستقیم یک پرونده منبع¶

پیاده‌سازی ایمپورت‌های تنبل¶

راه‌اندازی یک ایمپورت‌کننده (importer)¶

شبیه‌سازی importlib.import_module()¶

`importlib` --- پیاده‌سازی `import`¶

`importlib.abc` -- کلاس‌های پایه انتزاعی مرتبط با ایمپورت¶

`importlib.machinery` -- ایمپورت‌کننده‌ها و قلاب‌های مسیر (path hooks)¶

`importlib.util` -- کد سودمند برای ایمپورت‌کننده‌ها¶

شبیه‌سازی `importlib.import_module()`¶