# `pkgutil` — Package extension utility

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

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

class pkgutil.ModuleInfo(module_finder, name, ispkg)

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

  Нове в версії 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 checking for duplicates, 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()`).

class pkgutil.ImpImporter(dirname=None)

  PEP 302 Finder that wraps Python’s «classic» import algorithm.

  If dirname is a string, a PEP 302 finder is created that searches that directory. If dirname is `None`, a PEP 302 finder is created that searches the current `sys.path`, plus any modules that are frozen or built-in.

  Note that `ImpImporter` does not currently support being used by placement on `sys.meta_path`.

  Застаріло починаючи з версії 3.3: This emulation is no longer needed, as the standard import mechanism is now fully PEP 302 compliant and available in `importlib`.

class pkgutil.ImpLoader(fullname, file, filename, etc)

  Loader that wraps Python’s «classic» import algorithm.

  Застаріло починаючи з версії 3.3: This emulation is no longer needed, as the standard import mechanism is now fully PEP 302 compliant and available in `importlib`.

pkgutil.find_loader(fullname)

  Отримати модуль loader для вказаного повного імені.

  This is a backwards compatibility wrapper around `importlib.util.find_spec()` that converts most failures to `ImportError` and only returns the loader rather than the full `importlib.machinery.ModuleSpec`.

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

  Змінено в версії 3.4: Оновлено на основі PEP 451

pkgutil.get_importer(path_item)

  Отримати finder для заданого path_item.

  Повернений засіб пошуку зберігається в `sys.path_importer_cache`, якщо він був щойно створений за допомогою перехоплювача шляху.

  Кеш (або його частину) можна очистити вручну, якщо потрібно повторне сканування `sys.path_hooks`.

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

pkgutil.get_loader(module_or_name)

  Отримайте об’єкт loader для module_or_name.

  Якщо модуль або пакет доступні через звичайний механізм імпорту, повертається обгортка навколо відповідної частини цього механізму. Повертає `None`, якщо модуль неможливо знайти або імпортувати. Якщо вказаний модуль ще не імпортовано, його пакет (якщо є) імпортується, щоб створити пакет `__path__`.

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

  Змінено в версії 3.4: Оновлено на основі PEP 451

pkgutil.iter_importers(fullname='')

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

  Якщо повне ім’я містить `'.'`, 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)

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

  Це оболонка для API loader `get_data`. Аргумент package має бути назвою пакета в стандартному форматі модуля (`foo.bar`). Аргумент resource має бути у формі відносного імені файлу, використовуючи `/` як роздільник шляху. Ім’я батьківського каталогу `..` не допускається, а також коренева назва (починається з `/`).

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

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

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

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

pkgutil.resolve_name(name)

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

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

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

  - `W(.W)*`

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

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

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

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

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

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

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

  Нове в версії 3.9.