# `pkgutil` — Package extension utility

Вихідний код: Lib/pkgutil.py

Цей модуль надає утиліти для системи імпорту, зокрема підтримку пакетів.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

  Іменований кортеж, який містить короткий опис інформації про модуль.

  Added in version 3.6.

pkgutil.extend_path(path, name)

  Розширте шлях пошуку для модулів, які складають пакет. Цільове використання – розмістити наступний код у `__init__.py`:

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

  For each directory on `sys.path` that has a subdirectory that matches the package name, add the subdirectory to the package’s `__path__`. This is useful if one wants to distribute different parts of a single logical package as multiple directories.

  It also looks for `*.pkg` files beginning where `*` matches the name argument. This feature is similar to `*.pth` files (see the `site` module for more information), except that it doesn’t special-case lines starting with `import`. A `*.pkg` file is trusted at face value: apart from skipping blank lines and ignoring comments, all entries found in a `*.pkg` file are added to the path, regardless of whether they exist on the filesystem (this is a feature).

  Якщо шлях введення не є списком (як у випадку заморожених пакунків), він повертається без змін. Вхідний шлях не змінено; повертається розширена копія. Елементи додаються до копії лише в кінці.

  Передбачається, що `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: Оновлено, щоб базуватися безпосередньо на `importlib`, а не на внутрішній емуляції імпорту PEP 302 пакета.

pkgutil.iter_importers(fullname='')

  Видає об’єкти finder для вказаного імені модуля.

  If fullname contains a `'.'`, the finders will be for the package containing fullname, otherwise they will be all registered top level finders (i.e. those on both `sys.meta_path` and `sys.path_hooks`).

  Якщо вказаний модуль міститься в пакеті, цей пакет імпортується як побічний ефект виклику цієї функції.

  Якщо ім’я модуля не вказано, створюються всі шукачі верхнього рівня.

  Змінено в версії 3.3: Оновлено, щоб базуватися безпосередньо на `importlib`, а не на внутрішній емуляції імпорту PEP 302 пакета.

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

  Видає `ModuleInfo` для всіх підмодулів на path або, якщо path має значення `None`, усі модулі верхнього рівня на `sys.path`.

  path має бути або `None`, або список шляхів для пошуку модулів.

  префікс — це рядок, який виводиться на початку кожного імені модуля при виведенні.

  Примітка

  Працює лише для finder, який визначає метод `iter_modules()`. Цей інтерфейс є нестандартним, тому модуль також забезпечує реалізації для `importlib.machinery.FileFinder` і `zipimport.zipimporter`.

  Змінено в версії 3.3: Оновлено, щоб базуватися безпосередньо на `importlib`, а не на внутрішній емуляції імпорту PEP 302 пакета.

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

  Видає `ModuleInfo` для всіх модулів рекурсивно за шляхом або, якщо шлях має значення `None`, усі доступні модулі.

  path має бути або `None`, або список шляхів для пошуку модулів.

  префікс — це рядок, який виводиться на початку кожного імені модуля при виведенні.

  Зауважте, що ця функція має імпортувати всі пакети (не всі модулі!) за вказаним шляхом, щоб отримати доступ до атрибута `__path__` для пошуку підмодулів.

  onerror — це функція, яка викликається з одним аргументом (назва пакета, який імпортувався), якщо під час спроби імпортувати пакет виникає будь-яка виняткова ситуація. Якщо функція onerror не надається, `ImportError`s перехоплюються та ігноруються, тоді як усі інші винятки поширюються, припиняючи пошук.

  Приклади:

      # 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: Оновлено, щоб базуватися безпосередньо на `importlib`, а не на внутрішній емуляції імпорту PEP 302 пакета.

pkgutil.get_data(package, resource)

  Отримати ресурс із пакету.

  This is a wrapper for the loader `get_data` API. The package argument should be the name of a package, in standard module format (`foo.bar`). The resource argument should be in the form of a relative filename, using `/` as the path separator.

  Функція повертає двійковий рядок, який є вмістом зазначеного ресурсу.

  This function uses the loader method `get_data()` to support modules installed in the filesystem, but also in zip files, databases, or elsewhere.

  Для пакетів, розташованих у файловій системі, які вже були імпортовані, це приблизний еквівалент:

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

  Like the `open()` function, `get_data()` can follow parent directories (`../`) and absolute paths (starting with `/` or `C:/`, for example). It can open compilation/installation artifacts like `.py` and `.pyc` files or files with `reserved filenames`. To be compatible with non-filesystem loaders, avoid using these features.

  Попередження

  This function is intended for trusted input. It does not verify that resource «belongs» to package.

  If you use a user-provided resource path, consider verifying it. For example, require an alphanumeric filename with a known extension, or install and check a list of known resources.

  Якщо пакет не вдається знайти або завантажити, або він використовує loader, який не підтримує `get_data`, повертається `None`. Зокрема, loader для пакетів простору імен не підтримує `get_data`.

  Дивись також

  The `importlib.resources` module provides structured access to module resources.

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

  Розв’яжіть ім’я з об’єктом.

  Ця функціональність використовується в багатьох місцях у стандартній бібліотеці (див. bpo-12915), а еквівалентна функціональність також є в широко використовуваних пакетах сторонніх розробників, таких як setuptools, Django та Pyramid.

  Очікується, що ім’я буде рядком в одному з таких форматів, де W є скороченням дійсного ідентифікатора Python, а крапка означає крапку в цих псевдорегулярних виразах:

  - `W(.W)*`

  - `W(.W)*:(W(.W)*)?`

  - `W(.W)*:(W(.W)*)`

  Перша форма призначена лише для зворотної сумісності. Припускається, що деяка частина назви з крапками є пакетом, а решта є об’єктом десь у цьому пакеті, можливо, вкладеним в інші об’єкти. Оскільки місце, де зупиняється пакет і починається ієрархія об’єктів, не може бути встановлено шляхом перевірки, повторні спроби імпорту потрібно робити за допомогою цієї форми.

  У другій формі абонент чітко пояснює точку розділення за допомогою однієї двокрапки: назва з крапками ліворуч від двокрапки означає пакет, який потрібно імпортувати, а назва з крапками праворуч — це ієрархія об’єктів у цьому пакеті. . У цій формі потрібен лише один імпорт. Якщо він закінчується двокрапкою, повертається об’єкт модуля.

  The first two forms are accepted when `strict=False` (the default).

  The third form requires both the module name and callable, separated by a colon. Only this form is accepted when `strict=True`.

  Функція поверне об’єкт (який може бути модулем) або викличе одне з таких винятків:

  `ValueError` – якщо ім’я не в розпізнаному форматі.

  `ImportError` – якщо імпорт не вдався, а не мав бути.

  `AttributeError` – Якщо сталася помилка під час проходження ієрархії об’єктів в імпортованому пакеті, щоб дістатися до потрібного об’єкта.

  Added in version 3.9.

  Змінено в версії 3.15: The optional keyword-only `strict` flag was added.