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، میتوان نهانگاه (یا بخشی از آن) را بهصورت دستی پاک کرد.
- pkgutil.iter_importers(fullname='')¶
اشیای finder را برای نام ماژول دادهشده تولید میکند.
اگر fullname شامل
'.'باشد، یابندهها مربوط به بستهی حاوی fullname خواهند بود، در غیر این صورت آنها همهی یابندههای سطح بالای ثبتشده خواهند بود (یعنی آنهایی که در هر دوsys.meta_pathوsys.path_hooksهستند).اگر ماژول نامبردهشده در یک بسته قرار داشته باشد، آن بسته بهعنوان یک اثر جانبی فراخوانی این تابع ایمپورت میشود.
اگر هیچ نام ماژولی مشخص نشده باشد، همهی یابندههای سطح بالا تولید میشوند.
- pkgutil.iter_modules(path=None, prefix='')¶
ModuleInfoرا برای تمام زیرماژولهای موجود در path، یا اگر path برابرNoneباشد، برای تمام ماژولهای سطحبالا درsys.pathبرمیگرداند.path باید
Noneیا فهرستی از مسیرها برای جستجوی ماژولها در آنها باشد.prefix رشتهای است که در خروجی، در ابتدای نام هر ماژول چاپ میشود.
توجه
فقط برای یک finder که متد
iter_modules()را تعریف کرده باشد، کار میکند. این رابط غیراستاندارد است، بنابراین این ماژول همچنین پیادهسازیهایی را برایimportlib.machinery.FileFinderوzipimport.zipimporterارائه میدهد.
- pkgutil.walk_packages(path=None, prefix='', onerror=None)¶
ModuleInfoرا برای تمام ماژولها بهصورت بازگشتی در path، یا اگر pathNoneباشد، برای تمام ماژولهای قابل دسترس برمیگرداند.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ارائه میدهد.
- 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)¶
نام را به یک شیء حل میکند.
این قابلیت در جاهای متعددی در کتابخانه استاندارد استفاده میشود (به bpo-12915 مراجعه کنید) - و قابلیت معادل آن نیز در بستههای شخص ثالث پرکاربرد مانند setuptools، Django و Pyramid وجود دارد.
انتظار میرود name رشتهای در یکی از قالبهای زیر باشد، که در آن W مخفف یک شناسه معتبر پایتون است و نقطه در این شبهعبارتهای باقاعده به معنای یک نویسه نقطه واقعی است:
W(.W)*W(.W)*:(W(.W)*)?
شکل اول فقط برای سازگاری با نسخههای پیشین در نظر گرفته شده است. این شکل فرض میکند که بخشی از نام نقطهدار یک بسته است و باقیمانده، شیءای در جایی درون آن بسته است که ممکن است درون اشیاء دیگر تودرتو شده باشد. از آنجا که نمیتوان با بازرسی استنتاج کرد که بسته کجا تمام میشود و سلسلهمراتب اشیاء آغاز میگردد، تلاشهای مکرر برای ایمپورت باید با این شکل انجام شوند.
در شکل دوم، فراخواننده با قرار دادن یک دونقطه، نقطه جداسازی را مشخص میکند: نام نقطهدار سمت چپ دونقطه، بستهای است که باید ایمپورت شود، و نام نقطهدار سمت راست، سلسلهمراتب شیء درون آن بسته است. در این شکل فقط به یک ایمپورت نیاز است. اگر با دونقطه پایان یابد، یک شیء ماژول برگردانده میشود.
این تابع یک شیء را برمیگرداند (که ممکن است یک ماژول باشد)، یا یکی از استثناهای زیر را پرتاب میکند:
ValueError-- اگر name در قالبی شناختهشده نباشد.ImportError-- اگر ایمپورتی زمانی که نباید شکست میخورد، شکست خورد.AttributeError-- اگر خطایی هنگام پیمایش سلسلهمراتب اشیاء درون بستهی ایمپورتشده برای رسیدن به شیء مورد نظر رخ داد.اضافه شده در نسخهی 3.9.