pkgutil --- ابزار گسترش بسته¶

کد منبع: Lib/pkgutil.py

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

class pkgutil.ModuleInfo(module_finder, name, ispkg)¶

یک تاپل نام‌دار (namedtuple) که خلاصه‌ای مختصر از اطلاعات یک ماژول را نگه می‌دارد.

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

pkgutil.extend_path(path, name)¶

مسیر جست‌وجو را برای ماژول‌هایی که یک بسته را تشکیل می‌دهند، گسترش دهید. کاربرد مورد نظر این است که کد زیر در __init__.py یک بسته قرار گیرد:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

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

همچنین به دنبال پرونده‌های *.pkg می‌گردد که در ابتدای آن‌ها * با آرگومان name مطابقت دارد. این قابلیت شبیه پرونده‌های *.pth است (برای اطلاعات بیشتر، ماژول site را ببینید)، با این تفاوت که سطرهایی را که با import شروع می‌شوند، به‌صورت ویژه مدیریت نمی‌کند. محتوای یک پرونده *.pkg به‌همان‌صورت که هست پذیرفته می‌شود: به‌جز رد شدن از سطرهای خالی و نادیده گرفتن کامنت‌ها، تمام آیتم‌های یافته‌شده در یک پرونده *.pkg به مسیر اضافه می‌شوند، فارغ از اینکه در سامانه فایل‌بندی وجود دارند یا نه (این یک قابلیت است).

اگر مسیر ورودی یک فهرست نباشد (همان‌طور که در مورد بسته‌های فریزشده (frozen packages) صدق می‌کند)، بدون تغییر بازگردانده می‌شود. مسیر ورودی تغییر داده نمی‌شود؛ یک رونوشت گسترش‌یافته بازگردانده می‌شود. آیتم‌ها فقط به انتهای رونوشت افزوده می‌شوند.

فرض می‌شود که sys.path یک دنباله است. آیتم‌های sys.path که رشته‌های اشاره‌کننده به پوشه‌های موجود نیستند، نادیده گرفته می‌شوند. آیتم‌های یونیکدی در sys.path که هنگام استفاده به‌عنوان نام پرونده باعث بروز خطا می‌شوند، ممکن است موجب پرتاب یک استثنا توسط این تابع شوند (مطابق با رفتار os.path.isdir()).

pkgutil.get_importer(path_item)¶

یک finder را برای path_item داده‌شده بازیابی کنید.

یابنده‌ی برگردانده‌شده، اگر به‌تازگی به‌وسیله‌ی یک قلاب مسیرایجاد شده باشد، در sys.path_importer_cache نهان‌سازی می‌شود.

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

تغییر یافته در نسخه‌ی 3.3: به‌روزرسانی شد تا به‌جای اتکا به شبیه‌سازی ایمپورت PEP 302 داخلی بسته، مستقیماً بر پایه‌ی importlib باشد.

pkgutil.iter_importers(fullname='')¶

اشیای finder را برای نام ماژول داده‌شده تولید می‌کند.

اگر fullname شامل '.' باشد، یابنده‌ها مربوط به بسته‌ی حاوی fullname خواهند بود، در غیر این صورت آن‌ها همه‌ی یابنده‌های سطح بالای ثبت‌شده خواهند بود (یعنی آن‌هایی که در هر دو sys.meta_path و sys.path_hooks هستند).

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

اگر هیچ نام ماژولی مشخص نشده باشد، همه‌ی یابنده‌های سطح بالا تولید می‌شوند.

تغییر یافته در نسخه‌ی 3.3: به‌روزرسانی شد تا به‌جای اتکا به شبیه‌سازی ایمپورت PEP 302 داخلی بسته، مستقیماً بر پایه‌ی importlib باشد.

pkgutil.iter_modules(path=None, prefix='')¶

ModuleInfo را برای تمام زیرماژول‌های موجود در path، یا اگر path برابر None باشد، برای تمام ماژول‌های سطح‌بالا در sys.path برمی‌گرداند.

path باید None یا فهرستی از مسیرها برای جستجوی ماژول‌ها در آن‌ها باشد.

prefix رشته‌ای است که در خروجی، در ابتدای نام هر ماژول چاپ می‌شود.

نکته

فقط برای یک finder که متد iter_modules() را تعریف کرده باشد، کار می‌کند. این رابط غیراستاندارد است، بنابراین این ماژول همچنین پیاده‌سازی‌هایی را برای importlib.machinery.FileFinder و zipimport.zipimporter ارائه می‌دهد.

تغییر یافته در نسخه‌ی 3.3: به‌روزرسانی شد تا به‌جای اتکا به شبیه‌سازی ایمپورت PEP 302 داخلی بسته، مستقیماً بر پایه‌ی importlib باشد.

pkgutil.walk_packages(path=None, prefix='', onerror=None)¶

ModuleInfo را برای تمام ماژول‌ها به‌صورت بازگشتی در path، یا اگر path None باشد، برای تمام ماژول‌های قابل دسترس برمی‌گرداند.

path باید None یا فهرستی از مسیرها برای جستجوی ماژول‌ها در آن‌ها باشد.

prefix رشته‌ای است که در خروجی، در ابتدای نام هر ماژول چاپ می‌شود.

توجه داشته باشید که این تابع باید تمام بسته‌ها (نه تمام ماژول‌ها!) را در path داده‌شده ایمپورت کند، تا به ویژگی __path__ برای یافتن زیرماژول‌ها دسترسی پیدا کند.

onerror تابعی است که در صورت بروز هر استثنایی هنگام تلاش برای ایمپورت یک بسته، با یک آرگومان (نام بسته‌ای که در حال ایمپورت شدن بود) فراخوانی می‌شود. اگر تابع onerror ارائه نشده باشد، ImportErrors گرفته می‌شوند و نادیده گرفته می‌شوند، در حالی که تمام استثناهای دیگر انتشار می‌یابند و جستجو را خاتمه می‌دهند.

مثال‌ها:

# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

نکته

فقط برای یک finder که متد iter_modules() را تعریف کرده باشد، کار می‌کند. این رابط غیراستاندارد است، بنابراین این ماژول همچنین پیاده‌سازی‌هایی را برای importlib.machinery.FileFinder و zipimport.zipimporter ارائه می‌دهد.

تغییر یافته در نسخه‌ی 3.3: به‌روزرسانی شد تا به‌جای اتکا به شبیه‌سازی ایمپورت PEP 302 داخلی بسته، مستقیماً بر پایه‌ی importlib باشد.

pkgutil.get_data(package, resource)¶

دریافت یک منبع از یک بسته.

این یک دربرگیرنده برای API بارگذار get_data است. آرگومان package باید نام یک بسته، در قالب استاندارد ماژول باشد (foo.bar). آرگومان resource باید به شکل یک نام پرونده نسبی باشد و از / به‌عنوان جداکننده مسیر استفاده کند.

این تابع یک رشته دودویی برمی‌گرداند که محتوای منبع مشخص‌شده است.

این تابع از متد بارگذار یعنی get_data() برای پشتیبانی از ماژول‌های نصب‌شده در سامانه فایل‌بندی، و همچنین در پرونده‌های zip، پایگاه‌های داده، یا جاهای دیگر استفاده می‌کند.

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

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

مانند تابع open()، تابع get_data() می‌تواند پوشه‌های والد (../) و مسیرهای مطلق (برای نمونه، مسیرهایی که با / یا C:/ شروع می‌شوند) را دنبال کند. این تابع می‌تواند فراورده‌های کامپایل/نصب مانند پرونده‌های .py و .pyc یا پرونده‌هایی با نام‌های پرونده رزروشده را باز کند. برای سازگاری با بارگذارهای غیرمبتنی بر سامانه فایل‌بندی، از استفاده از این قابلیت‌ها خودداری کنید.

هشدار

این تابع برای ورودی قابل‌اعتماد در نظر گرفته شده است. این تابع تأیید نمی‌کند که resource به package «تعلق» داشته باشد.

اگر از یک مسیر resource ارائه‌شده توسط کاربر استفاده می‌کنید، صحت آن را بررسی کنید. برای مثال، نام پرونده‌ای الفبایی‌عددی با پسوند شناخته‌شده را الزامی کنید، یا فهرستی از منابع شناخته‌شده را نصب و بررسی کنید.

اگر بسته پیدا نشود یا بارگذاری نشود، یا از یک بارگذار استفاده کند که از get_data پشتیبانی نکند، None برگردانده می‌شود. به‌ویژه، بارگذار برای بسته‌های فضای نام از get_data پشتیبانی نمی‌کند.

همچنین ببینید

ماژول importlib.resources دسترسی ساختاریافته به منابع ماژول را فراهم می‌کند.

pkgutil.resolve_name(name, *, strict=False)¶

نام را به یک شیء حل می‌کند.

این قابلیت در جاهای متعددی در کتابخانه استاندارد استفاده می‌شود (به bpo-12915 مراجعه کنید) - و قابلیت معادل آن نیز در بسته‌های شخص ثالث پرکاربرد مانند setuptools، Django و Pyramid وجود دارد.

انتظار می‌رود name رشته‌ای در یکی از قالب‌های زیر باشد، که در آن W مخفف یک شناسه معتبر پایتون است و نقطه در این شبه‌عبارت‌های باقاعده به معنای یک نویسه نقطه واقعی است:

• W(.W)*

• W(.W)*:(W(.W)*)?

• W(.W)*:(W(.W)*)

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

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

دو فرم اول زمانی پذیرفته می‌شوند که strict=False باشد (حالت پیش‌فرض).

فرم سوم نیازمند نام ماژول و شیء فراخوانی‌پذیر است که با یک علامت دو‌نقطه (colon) از هم جدا شده‌اند. فقط این فرم است که وقتی strict=True باشد پذیرفته می‌شود.

این تابع یک شیء را برمی‌گرداند (که ممکن است یک ماژول باشد)، یا یکی از استثناهای زیر را پرتاب می‌کند:

ValueError -- اگر name در قالبی شناخته‌شده نباشد.

ImportError -- اگر ایمپورتی زمانی که نباید شکست می‌خورد، شکست خورد.

AttributeError -- اگر خطایی هنگام پیمایش سلسله‌مراتب اشیاء درون بسته‌ی ایمپورت‌شده برای رسیدن به شیء مورد نظر رخ داد.

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

تغییر یافته در نسخه‌ی 3.15: پرچم اختیاری و فقط-کلیدواژه‌ی strict اضافه شد.