importlib.resources -- خواندن، باز کردن و دسترسی به منابع بسته

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

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

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

«منابع» منابع شبه‌پرونده مرتبط با یک ماژول یا بسته در پایتون هستند. این منابع ممکن است مستقیماً در یک بسته، درون یک زیرپوشه‌ی موجود در آن بسته، یا مجاور ماژول‌هایی خارج از یک بسته قرار داشته باشند. منابع ممکن است متنی یا دودویی باشند. در نتیجه، کدهای منبع ماژول‌های پایتونِ یک بسته (.py)، مصنوعات کامپایل (pycache)، و مصنوعات نصب (مانند reserved filenames در پوشه‌ها) از نظر فنی، عملاً منابع آن بسته محسوب می‌شوند. با این حال، در عمل، منابع عمدتاً آن دسته از مصنوعات غیرپایتونی هستند که به‌طور مشخص توسط نویسنده‌ی بسته در دسترس قرار داده شده‌اند.

منابع را می‌توان در حالت دودویی یا متنی باز کرد یا خواند.

منابع تقریباً شبیه پرونده‌های درون پوشه‌ها هستند، هرچند مهم است به خاطر داشته باشید که این صرفاً یک استعاره است. منابع و بسته‌ها لازم نیست به‌صورت پرونده‌ها و پوشه‌های فیزیکی در سامانه فایل‌بندی وجود داشته باشند: برای مثال، می‌توان یک بسته و منابع آن را از یک پرونده zip با استفاده از zipimport ایمپورت کرد.

هشدار

importlib.resources از همان مدل امنیتی تابع توکار open() پیروی می‌کند. ارسال ورودی‌های غیرقابل‌اعتماد به توابع این ماژول ناامن است.

توجه

نسخه‌ی مستقل بک‌پورت‌شده این ماژول، اطلاعات بیشتری درباره‌ی استفاده از importlib.resources و مهاجرت از pkg_resources به importlib.resources ارائه می‌دهد.

بارگذارها که می‌خواهند از خواندن منابع پشتیبانی کنند، باید یک متد get_resource_reader(fullname) را همان‌طور که توسط importlib.resources.abc.ResourceReader مشخص شده است پیاده‌سازی کنند.

class importlib.resources.Anchor

نشان‌دهنده‌ی یک لنگر برای منابع است، خواه یک شیء ماژول باشد خواه نام یک ماژول به‌صورت یک رشته. به‌صورت Union[str, ModuleType] تعریف شده است.

importlib.resources.files(anchor: Anchor | None = None)

یک شیء Traversable را برمی‌گرداند که نمایانگر ظرف منبع (مانند پوشه) و منابع آن (مانند پرونده‌ها) است. یک Traversable ممکن است حاوی ظرف‌های دیگری (مانند زیرپوشه‌ها) باشد.

anchor یک Anchor اختیاری است. اگر anchor یک بسته باشد، منابع از آن بسته یافت می‌شوند. اگر anchor یک ماژول باشد، منابع در مجاورت آن ماژول یافت می‌شوند (در همان بسته یا ریشه‌ی بسته). اگر anchor حذف شود، از ماژول فراخواننده استفاده می‌شود.

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

تغییر یافته در نسخه‌ی 3.12: پارامتر package به anchor تغییر نام داده شده است. anchor اکنون می‌تواند یک ماژول غیربسته باشد و در صورت حذف، به‌طور پیش‌فرض ماژول فراخوان خواهد بود. package همچنان برای سازگاری پذیرفته می‌شود، اما یک DeprecationWarning پرتاب می‌کند. در نظر داشته باشید که anchor را به‌صورت جایگاهی ارسال کنید یا از importlib_resources >= 5.10 برای یک رابط سازگار در پایتون‌های قدیمی‌تر استفاده کنید.

importlib.resources.as_file(traversable)

با داشتن یک شیء Traversable که نشان‌دهنده یک پرونده یا پوشه است و معمولاً از importlib.resources.files() به‌دست می‌آید، یک مدیر زمینه برای استفاده در دستور with برمی‌گرداند. این مدیر زمینه یک شیء pathlib.Path را فراهم می‌کند.

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

هرگاه متدهای Traversable (read_text و غیره) ناکافی باشند و به یک پرونده یا پوشه واقعی در سامانه فایل‌بندی نیاز باشد، از as_file استفاده کنید.

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

تغییر یافته در نسخه‌ی 3.12: پشتیبانی از traversable برای نمایش یک پوشه افزوده شد.

API تابعی

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

برای همه‌ی توابع زیر:

  • anchor یک Anchor است، همان‌طور که در files() آمده. برخلاف files، نمی‌توان آن را حذف کرد.

  • path_names کامپوننت‌های نام مسیر یک منبع، نسبت به لنگر هستند. برای مثال، برای دریافت متن منبعی به نام info.txt، استفاده کنید:

    importlib.resources.read_text(my_module, "info.txt")

    مانند Traversable.joinpath، کامپوننت‌های منفرد باید از اسلش‌های رو به جلو (/) به‌عنوان جداکننده‌های مسیر استفاده کنند. برای مثال، موارد زیر معادل هستند:

    importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")

    به دلایل سازگاری با نسخه‌های پیشین، توابعی که متن می‌خوانند، در صورتی که چندین path_names داده شوند، به یک آرگومان صریح encoding نیاز دارند. برای مثال، برای دریافت متن info/chapter1.txt، از دستور زیر استفاده کنید:

    importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
importlib.resources.open_binary(anchor, *path_names)

منبع نام‌گذاری‌شده را برای خواندن دودویی باز می‌کند.

برای جزئیات درباره anchor و path_names، مقدمه را ببینید.

این تابع یک شیء BinaryIO برمی‌گرداند، یعنی یک جریان دودویی باز برای خواندن.

این تابع تقریباً معادل این است:

files(anchor).joinpath(*path_names).open('rb')

تغییر یافته در نسخه‌ی 3.13: چندین path_names پذیرفته می‌شود.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

منبع نام‌گذاری‌شده را برای خواندن متنی باز می‌کند. به‌طور پیش‌فرض، محتوا به‌صورت UTF-8 سخت‌گیرانه خوانده می‌شود.

برای جزئیات درباره anchor و path_names، به مقدمه مراجعه کنید. encoding و errors همان معنایی را دارند که در تابع توکار open() دارند.

به دلایل سازگاری با نسخه‌های پیشین، در صورت وجود چندین path_names، آرگومان encoding باید به‌صراحت داده شود. این محدودیت قرار است در پایتون 3.15 حذف شود.

این تابع یک شیء TextIO برمی‌گرداند، یعنی یک جریان متنی باز برای خواندن.

این تابع تقریباً معادل این است:

files(anchor).joinpath(*path_names).open('r', encoding=encoding)

تغییر یافته در نسخه‌ی 3.13: چندین path_names پذیرفته می‌شود. encoding و errors باید به‌عنوان آرگومان‌های کلیدواژه‌ای داده شوند.

importlib.resources.read_binary(anchor, *path_names)

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

برای جزئیات درباره anchor و path_names، مقدمه را ببینید.

این تابع تقریباً معادل این است:

files(anchor).joinpath(*path_names).read_bytes()

تغییر یافته در نسخه‌ی 3.13: چندین path_names پذیرفته می‌شود.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

محتویات منبع نام‌برده را به‌عنوان str می‌خواند و برمی‌گرداند. به‌طور پیش‌فرض، محتویات به‌صورت UTF-8 سخت‌گیرانه خوانده می‌شود.

برای جزئیات درباره anchor و path_names، به مقدمه مراجعه کنید. encoding و errors همان معنایی را دارند که در تابع توکار open() دارند.

به دلایل سازگاری با نسخه‌های پیشین، در صورت وجود چندین path_names، آرگومان encoding باید به‌صراحت داده شود. این محدودیت قرار است در پایتون 3.15 حذف شود.

این تابع تقریباً معادل این است:

files(anchor).joinpath(*path_names).read_text(encoding=encoding)

تغییر یافته در نسخه‌ی 3.13: چندین path_names پذیرفته می‌شود. encoding و errors باید به‌عنوان آرگومان‌های کلیدواژه‌ای داده شوند.

importlib.resources.path(anchor, *path_names)

مسیر منبع را به‌عنوان یک مسیر واقعی در سامانه فایل‌بندی فراهم می‌کند. این تابع یک مدیر زمینه برای استفاده در دستور with برمی‌گرداند. مدیر زمینه یک شیء pathlib.Path را فراهم می‌کند.

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

برای مثال، متد stat() به یک مسیر واقعی در سامانه فایل‌بندی نیاز دارد؛ می‌توان از آن این‌گونه استفاده کرد:

with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()

برای جزئیات درباره anchor و path_names، مقدمه را ببینید.

این تابع تقریباً معادل این است:

as_file(files(anchor).joinpath(*path_names))

تغییر یافته در نسخه‌ی 3.13: چندین path_names پذیرفته می‌شود.

importlib.resources.is_resource(anchor, *path_names)

اگر منبع نام‌برده وجود داشته باشد، True و در غیر این صورت False برمی‌گرداند. این تابع پوشه‌ها را منبع در نظر نمی‌گیرد.

برای جزئیات درباره anchor و path_names، مقدمه را ببینید.

این تابع تقریباً معادل این است:

files(anchor).joinpath(*path_names).is_file()

تغییر یافته در نسخه‌ی 3.13: چندین path_names پذیرفته می‌شود.

importlib.resources.contents(anchor, *path_names)

یک پیمایش‌پذیر بر روی آیتم‌های نام‌دار درون بسته یا مسیر برمی‌گرداند. این پیمایش‌پذیر نام منابع (مانند پرونده‌ها) و غیرمنابع (مانند پوشه‌ها) را به‌صورت str برمی‌گرداند. این پیمایش‌پذیر به‌صورت بازگشتی وارد زیرپوشه‌ها نمی‌شود.

برای جزئیات درباره anchor و path_names، مقدمه را ببینید.

این تابع تقریباً معادل این است:

for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name

منسوخ شده از نسخه‌ی 3.11: ترجیحاً همان‌طور که در بالا آمد از iterdir() استفاده کنید، که کنترل بیشتری بر نتایج و کارکرد غنی‌تری ارائه می‌دهد.