pkgutil — Package extension utility

Official Documentation

Overview

pkgutil provides utilities for the import system, including functions for finding, loading, and iterating over Python packages and modules. It is commonly used for plugin systems, namespace packages, and dynamic module discovery.

---

Module Classification: Simple

• Reason: pkgutil contains primarily functions and a small number of classes (less than 3 user-facing classes).
• Documentation strategy: Single file (pkgutil.md) covering all functions, classes, and constants.

---

Attribute Inventory

Name	Type	Description
extend_path	function	Extend the search path for modules/packages.
find_loader	function	Find the loader for a module.
get_data	function	Get a resource from a package.
get_importer	function	Get the importer for a path.
iter_importers	function	Iterate over importers for a path.
iter_modules	function	Iterate over modules in a package.
walk_packages	function	Recursively walk packages and yield module info.
ModuleInfo	class	Named tuple for module info.
ImpImporter	class	Deprecated: Importer for the import machinery.
ImpLoader	class	Deprecated: Loader for the import machinery.

---

Quick Reference Table

Function/Class	Signature	Description
extend_path	extend_path(path, name)	Extend package path for PEP 302 and PEP 420 support.
find_loader	find_loader(fullname, path=None)	Find loader for module (deprecated in 3.4+).
get_data	get_data(package, resource)	Get resource bytes from a package.
get_importer	get_importer(path_item)	Return importer for a path item.
iter_importers	iter_importers(fullname='')	Yield importers for a module/package.
iter_modules	iter_modules(path=None, prefix='')	Yield (module_finder, name, ispkg) for modules.
walk_packages	walk_packages(path=None, prefix='', onerror=None)	Recursively yield (module_finder, name, ispkg).
ModuleInfo	class ModuleInfo(module_finder, name, ispkg)	Info about a discovered module.
ImpImporter	class ImpImporter(path_item)	Deprecated: Importer for legacy import system.
ImpLoader	class ImpLoader(fullname, file, filename, etc.)	Deprecated: Loader for legacy import system.

---

Practical Use Cases

1. Iterating Over All Modules in a Package

import pkgutil
for finder, name, ispkg in pkgutil.iter_modules():
    print(f"{name} (Package: {ispkg})")

2. Walking Packages Recursively

import pkgutil
for finder, name, ispkg in pkgutil.walk_packages(path=None, prefix='myproject.'):
    print(f"Discovered: {name} (Package: {ispkg})")

3. Loading Data from a Package Resource

import pkgutil
# Suppose 'data.txt' is inside the 'mypkg' package
content = pkgutil.get_data('mypkg', 'data.txt')
print(content.decode())

4. Extending a Package Path (Namespace Packages)

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

---

Performance Notes

• Functions like iter_modules and walk_packages are efficient for module discovery but may be slow on very large package trees.
• Deprecated classes (ImpImporter, ImpLoader) should not be used in new code.

---

Further Reading

• Official pkgutil documentation
• PEP 302 – New Import Hooks
• PEP 420 – Implicit Namespace Packages

---

Source Attribution

• Examples and descriptions adapted from the official Python documentation.