### List All Installed Packages

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Iterate through all installed distributions and print their names and versions, sorted alphabetically.

```python
from importlib_metadata import distributions

for dist in sorted(distributions(), key=lambda d: d.name):
    print(f"{dist.name:40} {dist.version}")
```

--------------------------------

### Install importlib_metadata

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Install the importlib_metadata package using pip.

```bash
pip install importlib_metadata
```

--------------------------------

### List All Installed Packages

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/00-START-HERE.md

Iterate through all installed distributions and print their names and versions. This is helpful for inventorying the Python environment.

```python
from importlib_metadata import distributions
for dist in distributions():
    print(f"{dist.name}: {dist.version}")
```

--------------------------------

### Get Package Keywords

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Retrieves the keywords associated with an installed package. Returns keywords as a list of strings.

```python
from importlib_metadata import metadata

def get_keywords(package_name):
    meta = metadata(package_name)
    keywords = meta.get('Keywords', '')
    if isinstance(keywords, str):
        return keywords.split()
    return keywords

keywords = get_keywords('requests')
print(f"Keywords: {', '.join(keywords)}")
```

--------------------------------

### install

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/07-utilities.md

Decorator to register a DistributionFinder on sys.meta_path.

```APIDOC
## install

### Description
Decorator to register a DistributionFinder on sys.meta_path. Adds the finder to sys.meta_path and disables the stdlib finder functionality.

### Method
* Decorator

### Parameters
#### Path Parameters
* **cls** (type) - Required - DistributionFinder subclass

### Returns
* **type** - The class (unchanged)

### Example
```python
from importlib_metadata._compat import install, NullFinder
from importlib_metadata import DistributionFinder

@install
class CustomFinder(NullFinder, DistributionFinder):
    def find_distributions(self, context=None):
        # Custom implementation
        pass
```
```

--------------------------------

### Find All Versions of a Package

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/05-distributionfinder.md

Iterates through all installed distributions to find and list all installed versions of a specific package, like setuptools. This is useful for diagnosing environment issues.

```python
from importlib_metadata import distributions

# Find all versions installed (unusual but possible)
versions = []
for dist in distributions():
    if dist.name.lower() == 'setuptools':
        versions.append(dist.version)

if len(versions) > 1:
    print(f"Multiple setuptools versions: {versions}")
elif versions:
    print(f"Setuptools version: {versions[0]}")
```

--------------------------------

### Get All Distributions

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Retrieves an iterable of all installed Distribution instances. Useful for discovering all packages or filtering by name or path.

```python
from importlib_metadata import distributions

# Get all distributions
all_dists = list(distributions())
print(f"Total distributions: {len(all_dists)}")

# Get specific distribution
pip_dists = list(distributions(name='pip'))
for dist in pip_dists:
    print(f"Found: {dist.name} {dist.version}")

# Get distributions from specific path
local_dists = list(distributions(path=['/path/to/site-packages']))
```

--------------------------------

### List All Installed Python Packages

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Iterate through all installed distributions in the current environment and print their names and versions, sorted alphabetically by name.

```python
from importlib_metadata import distributions

for dist in sorted(distributions(), key=lambda d: d.name):
    print(f"{dist.name} {dist.version}")
```

--------------------------------

### Custom Zip Archive Distribution Finder Example

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/05-distributionfinder.md

An example of a custom distribution finder that looks for distributions within zip archives. This demonstrates how to implement the find_distributions method for custom sources.

```python
from importlib_metadata import DistributionFinder, Distribution
import pathlib

class ZipDistributionFinder(DistributionFinder):
    """Find distributions in zip archives"""
    
    def find_distributions(self, context=None):
        context = context or DistributionFinder.Context()
        
        for path_str in context.path:
            path = pathlib.Path(path_str)
            
            # Look for .zip archives with metadata
            if path.suffix == '.zip':
                # Custom logic to extract and parse metadata
                # This is a simplified example
                try:
                    # Pseudo-code: extract metadata from zip
                    yield Distribution()  # Real implementation would extract and create
                except Exception:
                    pass
```

--------------------------------

### Batch Process All Installed Packages

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Iterates through all installed distributions once to process them efficiently. Avoids converting the distributions iterator to a list to save memory.

```python
from importlib_metadata import distributions

def process_all_packages():
    """Process all packages efficiently."""
    # Iterate once, don't convert to list
    for dist in distributions():
        # Process each distribution
        print(f"{dist.name}: {dist.version}")
```

--------------------------------

### Handle Package Not Found Errors

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Demonstrates how to catch and handle a 'PackageNotFoundError' when a package is not installed.

```python
from importlib_metadata import distribution, PackageNotFoundError

try:
    dist = distribution('mypackage')
except PackageNotFoundError as e:
    print(f"Package {e.name} not found")
```

--------------------------------

### Get Distribution by Name

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Retrieves the Distribution instance for a specific package. Use this when you need detailed information about a single installed package.

```python
from importlib_metadata import distribution, PackageNotFoundError

try:
    dist = distribution('requests')
    print(f"Found: {dist.name} {dist.version}")
except PackageNotFoundError:
    print("Package 'requests' not found")
```

--------------------------------

### Compare Package Versions

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Compare versions of two installed packages using `version` and `packaging.version.Version`. Handles `PackageNotFoundError` if a package is not installed.

```python
from importlib_metadata import version, PackageNotFoundError
from packaging.version import Version

def compare_versions(package1, package2):
    """Compare versions of two packages."""
    try:
        v1 = Version(version(package1))
        v2 = Version(version(package2))
        
        if v1 > v2:
            return f"{package1} ({v1}) is newer"
        elif v1 < v2:
            return f"{package2} ({v2}) is newer"
        else:
            return f"Both are version {v1}"
    except PackageNotFoundError as e:
        return f"Package {e.name} not found"

print(compare_versions('pip', 'setuptools'))
```

--------------------------------

### Generate Package Report

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Create a summary report of all installed packages, including total count, package names with versions, and counts grouped by author and license. Uses `distributions` to iterate over installed packages.

```python
from importlib_metadata import distributions

def generate_package_report():
    """Generate summary report of installed packages."""
    report = {
        'total': 0,
        'packages': [],
        'by_author': {},
        'by_license': {},
    }
    
    for dist in distributions():
        report['total'] += 1
        
        meta = dist.metadata
        name = meta['Name']
        version = meta['Version']
        author = meta.get('Author', 'Unknown')
        license_type = meta.get('License', 'Unknown')
        
        report['packages'].append(f"{name}=={version}")
        
        # Track by author
        if author not in report['by_author']:
            report['by_author'][author] = []
        report['by_author'][author].append(name)
        
        # Track by license
        if license_type not in report['by_license']:
            report['by_license'][license_type] = 0
        report['by_license'][license_type] += 1
    
    return report

report = generate_package_report()
print(f"Total packages: {report['total']}")
print(f"Licenses: {report['by_license']}")
```

--------------------------------

### Function Signature Example

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/00-START-HERE.md

Illustrates the expected format for function signatures in the documentation, including parameters with type hints and default values, and return type hints.

```python
def function_name(param1: str, param2: int = 5) -> bool:
    pass
```

--------------------------------

### Get Detailed Package Information

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Retrieve a distribution object for 'requests' and print its name, version, and summary.

```python
from importlib_metadata import distribution

dist = distribution('requests')
print(f"Name: {dist.name}")
print(f"Version: {dist.version}")
print(f"Summary: {dist.metadata.get('Summary')}")
```

--------------------------------

### Get Package Version

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/00-START-HERE.md

Retrieve the version of an installed package. This function is useful for checking compatibility or displaying package information.

```python
from importlib_metadata import version
print(version('pip'))
```

--------------------------------

### Check Installed Package Version Against Requirements

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Verifies if an installed package meets a specified version requirement using packaging.version and packaging.specifiers. Handles potential exceptions during version checking.

```python
from importlib_metadata import distribution

def check_installed_version(package_name, required_version):
    """Check if installed version meets requirement."""
    from packaging.version import Version
    from packaging.specifiers import SpecifierSet
    
    try:
        dist = distribution(package_name)
        spec = SpecifierSet(required_version)
        
        if Version(dist.version) in spec:
            return True, f"{dist.name} {dist.version} meets requirement {required_version}"
        else:
            return False, f"{dist.name} {dist.version} does not meet {required_version}"
    except Exception as e:
        return False, str(e)

success, message = check_installed_version('requests', '>=2.25.0')
print(message)
```

--------------------------------

### Python Signature Format Example

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Demonstrates the standard format for Python function signatures, including parameters, default values, and return types.

```python
def function_name(param1: str, param2: int = 5) -> bool:
    # Function body
    pass

# Explanation:
# - param1: str — Parameter name and type
# - = 5 — Default value (if present, parameter is optional)
# - → bool — Return type
```

--------------------------------

### Get Full Distribution Metadata

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Fetch all metadata for a given package, including name, version, summary, and author.

```python
from importlib_metadata import distribution

dist = distribution('requests')
print(f"Name: {dist.name}")
print(f"Version: {dist.version}")
print(f"Summary: {dist.metadata.get('Summary')}")
print(f"Author: {dist.metadata.get('Author')}")
```

--------------------------------

### Get Package URLs

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Extracts various URLs associated with an installed package, including the home page and project-specific URLs. Parses multi-valued 'Project-URL' fields into labels and URLs.

```python
from importlib_metadata import metadata

def get_package_urls(package_name):
    meta = metadata(package_name)
    urls = {}
    
    # Single URL fields
    if 'Home-Page' in meta:
        urls['home'] = meta['Home-Page']
    
    # Multi-valued fields
    if 'Project-URL' in meta:
        for url_entry in meta.get_all('Project-URL') or []:
            if ', ' in url_entry:
                label, url = url_entry.split(', ', 1)
                urls[label.lower()] = url
    
    return urls

urls = get_package_urls('requests')
for label, url in urls.items():
    print(f"  {label}: {url}")
```

--------------------------------

### Build Dependency Tree

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Recursively build and print a dependency tree for a given package, up to a specified depth. Uses `distribution` to get package version and `requires` to get dependencies. Includes basic error handling for missing packages or dependencies.

```python
from importlib_metadata import distribution, requires

def build_dependency_tree(package_name, depth=0, max_depth=3):
    """Build a dependency tree for a package."""
    if depth > max_depth:
        return
    
    try:
        dist = distribution(package_name)
        deps = requires(package_name) or []
        
        indent = "  " * depth
        print(f"{indent}{package_name} ({dist.version})")
        
        for dep in deps[:3]:  # Limit to first 3 deps per level
            # Extract package name (before version spec or extras)
            import re
            match = re.match(r'([a-zA-Z0-9_.-]+)', dep)
            if match:
                dep_name = match.group(1)
                build_dependency_tree(dep_name, depth + 1, max_depth)
    except Exception as e:
        indent = "  " * depth
        print(f"{indent}[Error: {e}]")

build_dependency_tree('flask')
```

--------------------------------

### Export Installed Packages to requirements.txt

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Exports a list of all installed Python packages and their versions to a 'requirements.txt' file. This is useful for documenting project dependencies.

```python
from importlib_metadata import distributions

def export_requirements():
    """Export installed packages as requirements.txt."""
    with open('requirements.txt', 'w') as f:
        for dist in sorted(distributions(), key=lambda d: d.name):
            f.write(f"{dist.name}=={dist.version}\n")

export_requirements()
```

--------------------------------

### Validate Package Installation Metadata

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Checks if a package is properly installed by verifying the presence of essential metadata like 'Name' and 'Version', and optionally checking for associated files. Returns a boolean indicating validity and a status message.

```python
from importlib_metadata import distribution, requires

def validate_package_installation(package_name):
    """Validate a package is properly installed."""
    try:
        dist = distribution(package_name)
        
        # Check metadata
        meta = dist.metadata
        assert 'Name' in meta
        assert 'Version' in meta
        
        # Check files (if available)
        if dist.files:
            assert len(dist.files) > 0
        
        return True, "Installation valid"
    except AssertionError:
        return False, "Metadata incomplete"
    except Exception as e:
        return False, str(e)

valid, message = validate_package_installation('requests')
print(f"Valid: {valid} - {message}")
```

--------------------------------

### Python Type Notation Example

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Illustrates common type notations used in Python documentation. This helps in understanding function signatures and type hints.

```python
Type      | Meaning
----------|-------------------------------------------
str       | String
int       | Integer
bool      | Boolean
Any       | Any type
dict      | Dictionary
list[T]   | List of type T
T | None  | Optional type (can be None)
Iterable[T] | Iterable of type T
Callable  | Callable/function
```

--------------------------------

### Find All Distributions

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/05-distributionfinder.md

Finds all installed distributions on the system. This method internally uses the MetadataPathFinder.

```python
from importlib_metadata import distributions

# This uses MetadataPathFinder internally
all_dists = list(distributions())

# Equivalent to:
# finder = MetadataPathFinder()
# context = DistributionFinder.Context()
# all_dists = list(finder.find_distributions(context))
```

--------------------------------

### Check if Package is Installed

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/08-errors.md

A utility function to check if a package is installed by attempting to retrieve its distribution. Returns True if found, False if PackageNotFoundError is raised.

```python
from importlib_metadata import distribution, PackageNotFoundError

def is_installed(package_name):
    try:
        distribution(package_name)
        return True
    except PackageNotFoundError:
        return False

# Check dependencies
if not is_installed('requests'):
    print("requests is not installed, some features will be unavailable")
```

--------------------------------

### Find Console Scripts Entry Points

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Discover and list console script entry points registered by installed packages.

```python
from importlib_metadata import entry_points
scripts = entry_points(group='console_scripts')
for script in scripts:
    print(script.name)
```

--------------------------------

### List Package Files

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Obtain a list of files associated with a specific installed package. This is helpful for inspecting package contents or locating specific assets.

```python
from importlib_metadata import files

pkg_files = files('requests')
for file in list(pkg_files)[:5]:
    print(file)
```

--------------------------------

### Register Custom Distribution Finder

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/05-distributionfinder.md

Registers a custom distribution finder with sys.meta_path using the @install decorator. This allows custom discovery mechanisms to be integrated.

```python
from importlib_metadata import NullFinder, DistributionFinder

@install
class MyDistributionFinder(NullFinder, DistributionFinder):
    def find_distributions(self, context=None):
        # Custom implementation
        pass
```

--------------------------------

### Find Modules from Distribution

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Use `packages_distributions` to map installed distributions to their top-level modules. Useful for reverse lookups when you know the distribution name but not the module names it provides.

```python
from importlib_metadata import packages_distributions

def find_modules_from_distribution(dist_name):
    """Find all top-level modules from a distribution."""
    pkg_dist = packages_distributions()
    
    modules = [
        pkg_name for pkg_name, dists in pkg_dist.items()
        if dist_name in dists
    ]
    
    return sorted(modules)

modules = find_modules_from_distribution('setuptools')
print(f"setuptools provides: {modules}")
```

--------------------------------

### Calculate Package Size

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Calculates the total size of an installed package in bytes. Returns None if the package has no file information or size data.

```python
from importlib_metadata import distribution

def get_package_size(package_name):
    """Get total package size in bytes."""
    dist = distribution(package_name)
    
    if not dist.files:
        return None
    
    total_bytes = sum(f.size for f in dist.files if f.size)
    return total_bytes

size = get_package_size('numpy')
if size:
    size_mb = size / (1024 * 1024)
    print(f"numpy size: {size_mb:.2f} MB")
```

--------------------------------

### Handle Package Not Found Error

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Use this snippet to catch and handle the PackageNotFoundError when a specified package is not installed in the environment.

```python
from importlib_metadata import distribution, PackageNotFoundError

try:
    dist = distribution('nonexistent-package')
except PackageNotFoundError as e:
    print(f"Package not found: {e.name}")
    print(f"Error: {e}")
```

--------------------------------

### Access Path Components

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Get a tuple of all components of a package path. Useful for accessing individual directory names or the filename.

```python
path = PackagePath('requests/models/response.py')
print(path.parts)  # Output: ('requests', 'models', 'response.py')
```

--------------------------------

### Get Package Version

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Retrieves the version string for a named package. This is a shortcut for accessing the 'Version' key in the package's metadata.

```python
from importlib_metadata import version

try:
    v = version('pip')
    print(f"pip version: {v}")
except Exception as e:
    print(f"Error: {e}")

# Version comparison
from packaging.version import Version
v1 = Version(version('setuptools'))
v2 = Version('65.0.0')
if v1 >= v2:
    print("setuptools is up to date")
```

--------------------------------

### Search Specific Directory for Distributions

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/05-distributionfinder.md

Searches for distributions within a specified directory, such as a site-packages path. This allows targeted discovery of installed packages.

```python
from importlib_metadata import Distribution, DistributionFinder

# Search only site-packages
context = DistributionFinder.Context(
    path=['/usr/lib/python3.11/site-packages']
)

finder = Distribution._discover_resolvers()
for resolver in finder:
    dists = resolver(context)
    for dist in dists:
        print(f"{dist.name}: {dist.version}")
```

--------------------------------

### Reverse Dependency Lookup

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Find all installed packages that list a specific package in their dependencies. This implementation performs a simple string check.

```python
from importlib_metadata import distributions

def find_reverse_dependencies(package_name):
    """Find packages that depend on the given package."""
    dependents = []
    
    for dist in distributions():
        deps = dist.requires or []
        for dep in deps:
            # Simple check - could use packaging.requirements for full parsing
            if package_name.lower() in dep.lower():
                dependents.append(dist.name)
    
    return dependents

dependents = find_reverse_dependencies('setuptools')
print(f"Packages depending on setuptools: {len(dependents)}")
```

--------------------------------

### Map Module to Distribution

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Finds which installed distribution provides a given Python module. Handles nested modules by checking the top-level module name.

```python
from importlib_metadata import packages_distributions

def find_distribution_for_module(module_name):
    """Find which distribution provides a module."""
    pkg_dist = packages_distributions()
    
    # Handle nested modules
    parts = module_name.split('.')
    top_level = parts[0]
    
    if top_level in pkg_dist:
        return pkg_dist[top_level]
    
    return None

dist_names = find_distribution_for_module('requests.auth')
if dist_names:
    print(f"Module 'requests.auth' is provided by: {dist_names}")
```

--------------------------------

### Verify Package File Hashes

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Verifies the integrity of files within an installed package by comparing their hashes against the recorded values. Skips files without hash information and reports missing files or hash mismatches.

```python
from importlib_metadata import distribution
import hashlib

def verify_package_files(package_name):
    """Verify file hashes in a package."""
    dist = distribution(package_name)
    
    if not dist.files:
        print(f"No file information for {package_name}")
        return
    
    verified = 0
    failed = 0
    
    for file in dist.files:
        if not file.hash:
            continue  # Skip files without hash
        
        try:
            located = file.locate()
            if not located.exists():
                print(f"  ✗ Missing: {file}")
                failed += 1
                continue
            
            data = located.read_bytes()
            hasher = hashlib.new(file.hash.mode)
            hasher.update(data)
            
            if hasher.hexdigest() == file.hash.value:
                verified += 1
            else:
                print(f"  ✗ Hash mismatch: {file}")
                failed += 1
        except Exception as e:
            print(f"  ✗ Error verifying {file}: {e}")
            failed += 1
    
    print(f"Verified {verified}, Failed {failed}")

verify_package_files('setuptools')
```

--------------------------------

### Find Files in Package by Pattern

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Finds files within an installed package that match a given glob-style pattern. Useful for locating specific types of files like stubs or templates.

```python
from importlib_metadata import distribution

def find_files_in_package(package_name, pattern):
    """Find files matching pattern in package."""
    import fnmatch
    
    dist = distribution(package_name)
    
    if not dist.files:
        return []
    
    return [f for f in dist.files if fnmatch.fnmatch(str(f), pattern)]

# Find all type stubs
stubs = find_files_in_package('pytest', '**/*.pyi')
print(f"Type stub files: {len(stubs)}")

# Find data files
data = find_files_in_package('flask', '**/templates/*')
print(f"Template files: {len(data)}")
```

--------------------------------

### Get Package Version or Default

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/08-errors.md

A function to safely retrieve a package's version, returning a specified default value if the package is not found (PackageNotFoundError).

```python
from importlib_metadata import version, PackageNotFoundError

def get_version(package_name, default=None):
    try:
        return version(package_name)
    except PackageNotFoundError:
        return default

v = get_version('mylib', 'unknown')
print(f"Version: {v}")
```

--------------------------------

### Load a Specific Console Script

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/02-entrypoint.md

Use this snippet to find and load a console script by its group and name. Ensure the script is installed and discoverable.

```python
from importlib_metadata import entry_points

# Find and load a console script
olds = entry_points(group='console_scripts', name='pytest')
if olds:
    main_func = olds[0].load()
    main_func()  # Execute the script
```

--------------------------------

### Get Package Classifiers

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Retrieves all classifiers associated with an installed package. Allows filtering classifiers, for example, to find framework-related classifications.

```python
from importlib_metadata import metadata

def get_classifiers(package_name):
    meta = metadata(package_name)
    return meta.get_all('Classifier') or []

classifiers = get_classifiers('flask')
print(f"Flask classifiers ({len(classifiers)}):")

# Filter by type
for clf in classifiers:
    if clf.startswith('Framework'):
        print(f"  {clf}")
```

--------------------------------

### Get All File Suffixes

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Retrieve a list of all suffixes for a path, including multiple extensions. Useful for handling files with compound extensions like .tar.gz.

```python
path = PackagePath('archive.tar.gz')
print(path.suffixes)  # Output: ['.tar', '.gz']
```

--------------------------------

### Filter Entry Points

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Retrieve and select specific entry points from a given group. Useful for discovering and accessing plugins or scripts registered by installed packages.

```python
from importlib_metadata import entry_points

# Get console scripts
scripts = entry_points(group='console_scripts')

# Get specific script
pip_script = scripts.select(name='pip')[0]
print(pip_script.value)
```

--------------------------------

### Get iterator for items with specified key

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/07-utilities.md

Use this to get an iterator for distributions associated with a specific key. The example shows filtering for 'flask' related distributions.

```python
buckets = bucket(distributions(), key=lambda d: d.name[0])
flask_related = [d for d in buckets['f'] if 'flask' in d.name.lower()]
```

--------------------------------

### Retry with Alternative Package on PackageNotFoundError

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/08-errors.md

Shows a function that attempts to get a distribution, falling back to an alternative package if the primary one is not found. It re-raises PackageNotFoundError if neither is available.

```python
from importlib_metadata import distribution, PackageNotFoundError

def get_distribution(primary, fallback=None):
    try:
        return distribution(primary)
    except PackageNotFoundError:
        if fallback:
            try:
                return distribution(fallback)
            except PackageNotFoundError:
                raise PackageNotFoundError(fallback)
        raise

# Try json_encoder first, fall back to ujson
try:
    dist = get_distribution('json_encoder', 'ujson')
except PackageNotFoundError as e:
    print(f"Neither primary nor fallback package found: {e.name}")
```

--------------------------------

### Batch Query Package Versions with Error Recovery

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Query versions for all installed packages, collecting successful results and logging any errors encountered during the process. This pattern is useful for batch operations where some packages might cause issues.

```python
from importlib_metadata import distributions

def get_all_package_versions():
    """Get versions of all packages, with error handling."""
    versions = {}
    errors = []
    
    for dist in distributions():
        try:
            versions[dist.name] = dist.version
        except Exception as e:
            errors.append((dist.name, str(e)))
    
    return versions, errors

versions, errors = get_all_package_versions()
print(f"Successfully queried {len(versions)} packages")
if errors:
    print(f"Errors: {len(errors)}")
    for pkg, err in errors[:5]:
        print(f"  {pkg}: {err}")
```

--------------------------------

### Discover Plugins

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Load all entry points within a specified group, typically used for discovering plugins. Includes error handling for loading failures.

```python
from importlib_metadata import entry_points

def load_plugins(group_name):
    """Load all plugins in a group."""
    plugins = []
    
    for ep in entry_points(group=group_name):
        try:
            plugin_class = ep.load()
            plugins.append({
                'name': ep.name,
                'class': plugin_class,
                'module': ep.module,
            })
            print(f"Loaded plugin: {ep.name}")
        except Exception as e:
            print(f"Failed to load plugin {ep.name}: {e}")
    
    return plugins

# Discover pytest plugins
plugins = load_plugins('pytest11')
print(f"Found {len(plugins)} pytest plugins")
```

--------------------------------

### Get Package Python Version Requirement

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Retrieves the 'Requires-Python' metadata for an installed package. Returns 'Not specified' if the information is absent.

```python
from importlib_metadata import metadata

def get_python_requirement(package_name):
    meta = metadata(package_name)
    python_requires = meta.get('Requires-Python', 'Not specified')
    return python_requires

print(f"Requires-Python: {get_python_requirement('pytest')}")
```

--------------------------------

### Load and Execute Entry Point

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Find a specific console script entry point by name, load its associated function, and execute it. Includes error handling for missing commands or execution errors.

```python
from importlib_metadata import entry_points, PackageNotFoundError

def run_command(command_name, *args):
    eps = entry_points(group='console_scripts', name=command_name)
    
    if not eps:
        print(f"Command '{command_name}' not found")
        return 1
    
    try:
        main_func = eps[0].load()
        # Would normally pass args to main_func
        main_func()
        return 0
    except Exception as e:
        print(f"Error running command: {e}")
        return 1

# Usage
exit_code = run_command('pip')
```

--------------------------------

### Using the select interface for EntryPoints

Source: https://github.com/python/importlib_metadata/blob/main/NEWS.rst

Demonstrates how to use the .select() method on an EntryPoints object to filter by group and name.

```python
# eps is an EntryPoints object
selected_eps = eps.select(group='my_group', name='my_entry_point')
```

--------------------------------

### List All Entry Points

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/02-entrypoint.md

Use this snippet to list all entry points available in the current environment, grouped by their respective groups. This is useful for introspection.

```python
from importlib_metadata import entry_points

all_eps = entry_points()
for group in sorted(all_eps.groups):
    print(f"\n{group}:")
    for ep in all_eps.select(group=group):
        print(f"  {ep.name}: {ep.value}")
```

--------------------------------

### List Package Files with Metadata

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Iterate through a package's files and display their path, size, and hash algorithm. Useful for auditing package contents.

```python
from importlib_metadata import distribution

dist = distribution('flask')
if dist.files:
    for file in dist.files:
        size_str = f"{file.size} bytes" if file.size else "unknown"
        hash_str = f"{file.hash.mode}" if file.hash else "no hash"
        print(f"{str(file):40} {size_str:15} {hash_str}")
```

--------------------------------

### Find Package Home Page and Project URLs

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Extract the 'Home-Page' and 'Project-URL' metadata fields for a package. Handles multiple 'Project-URL' entries.

```python
from importlib_metadata import metadata

meta = metadata('requests')
if 'Home-Page' in meta:
    print(f"Home: {meta['Home-Page']}")
if 'Project-URL' in meta:
    urls = meta.get_all('Project-URL')
    for url_entry in urls:
        print(f"  {url_entry}")
```

--------------------------------

### Import Core Functions

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Import and view signatures for key functions used to query package information.

```python
from importlib_metadata import (
    distribution,
    distributions,
    metadata,
    version,
    entry_points,
    files,
    requires,
    packages_distributions(),
)
```

--------------------------------

### Handle Missing Metadata

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/08-errors.md

Demonstrates how to access package metadata and handle a MetadataNotFound exception if the metadata is corrupted or missing.

```python
from importlib_metadata import distribution, MetadataNotFound

dist = distribution('some-package')
try:
    meta = dist.metadata
    print(f"Name: {meta['Name']}")
except MetadataNotFound:
    print(f"Package {dist.name} is corrupted (no metadata)")
```

--------------------------------

### Handle Entry Point Loading Errors

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/02-entrypoint.md

This snippet shows how to create an EntryPoint object and handle potential errors like ImportError, AttributeError, or ValueError during the loading process.

```python
from importlib_metadata import EntryPoint

ep = EntryPoint('cli', 'nonexistent.module:func', 'console_scripts')

try:
    func = ep.load()
except ImportError as e:
    print(f"Module not found: {e}")
except AttributeError as e:
    print(f"Attribute not found: {e}")
except ValueError as e:
    print(f"Invalid entry point format: {e}")
```

--------------------------------

### Discover Plugins via Entry Points

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/00-START-HERE.md

Find plugins registered under a specific group name. This is essential for discovering and utilizing extension points in applications.

```python
from importlib_metadata import entry_points
plugins = entry_points(group='myapp.plugins')
```

--------------------------------

### Retrieving metadata as JSON

Source: https://github.com/python/importlib_metadata/blob/main/NEWS.rst

Access the 'json' property of a PackageMetadata object to get the metadata in a JSON-compatible format.

```python
from importlib_metadata import metadata

meta = metadata('my_package')
json_compatible_meta = meta.json
```

--------------------------------

### Get Hash Value

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Access the hexadecimal hash digest of a package file. This is part of the FileHash object.

```python
from importlib_metadata import distribution

dist = distribution('requests')
if dist.files:
    file = dist.files[0]
    if file.hash:
        print(f"Digest: {file.hash.value}")
        # Value is typically a long hex string
```

--------------------------------

### Get File Extension

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Retrieve the primary file extension of a path. Useful for identifying file types.

```python
path = PackagePath('requests/api.pyi')
print(path.suffix)  # Output: .pyi
```

--------------------------------

### Discover Custom Group Plugins

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/02-entrypoint.md

This snippet demonstrates how to discover all plugins registered under a custom group. Load each plugin to instantiate its class and use its functionality.

```python
from importlib_metadata import entry_points

# Discover all plugins for a custom group
plugins = entry_points(group='myapp.plugins')
for plugin_ep in plugins:
    PluginClass = plugin_ep.load()
    plugin = PluginClass()
    # Use the plugin...
```

--------------------------------

### Get Filename Stem

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Retrieve the filename without its extension. Useful for isolating the base name of a file.

```python
path = PackagePath('requests/api.py')
print(path.stem)  # Output: api
```

--------------------------------

### FileHash String Representation

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Get a formatted string representation of a FileHash object, showing its mode and value. Useful for debugging.

```python
from importlib_metadata import FileHash

h = FileHash('sha256=abc123')
print(repr(h))
```

--------------------------------

### Parse Dependencies with Extras and Markers

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/09-usage-patterns.md

Parse dependency strings to extract package names, optional extras, and environment markers.

```python
from importlib_metadata import requires
from packaging.requirements import Requirement

deps = requires('pytest') or []
for req_str in deps:
    req = Requirement(req_str)
    extras = f" (extras: {', '.join(req.extras)})" if req.extras else ""
    marker = f" (marker: {req.marker})" if req.marker else ""
    print(f"  {req.name}{extras}{marker}")
```

--------------------------------

### Get Hash Algorithm Mode

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Access the name of the hash algorithm used for a package file. This is part of the FileHash object.

```python
from importlib_metadata import distribution

dist = distribution('requests')
if dist.files:
    for file in dist.files:
        if file.hash:
            print(f"Algorithm: {file.hash.mode}")
```

--------------------------------

### Retrieving a single EntryPoint by name

Source: https://github.com/python/importlib_metadata/blob/main/NEWS.rst

Access a specific entry point by its name from an EntryPoints object using dictionary-like item access.

```python
# eps is an EntryPoints object
entry_point = eps['my_entry_point']
```

--------------------------------

### find_distributions

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/05-distributionfinder.md

Finds distributions within a given context's path. This method is part of the MetadataPathFinder and is used for discovering installed packages.

```APIDOC
## find_distributions

### Description
Find distributions in the context's path.

### Method Signature
```python
def find_distributions(self, context=None) -> Iterable[Distribution]:
```

### Parameters
#### Path Parameters
- **context** (DistributionFinder.Context, optional) - Context for finding distributions. Defaults to None.

### Returns
- **Iterable[Distribution]** — An iterable of Distribution objects found.

### Implementation
Searches sys.path (or context.path if specified) for .dist-info and .egg-info directories, returning PathDistribution objects for each found distribution.

### Example
```python
from importlib_metadata import distributions

# This uses MetadataPathFinder internally
all_dists = list(distributions())

# Equivalent to:
# finder = MetadataPathFinder()
# context = DistributionFinder.Context()
# all_dists = list(finder.find_distributions(context))
```
```

--------------------------------

### Handling Package Errors

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/INDEX.md

Demonstrates how to handle common errors like PackageNotFoundError and MetadataNotFound when accessing package distributions and their metadata.

```python
from importlib_metadata import (
    distribution,
    PackageNotFoundError,
    MetadataNotFound,
)

# Scenario 1: Package not installed
try:
    dist = distribution('nonexistent')
except PackageNotFoundError as e:
    print(f"Package {e.name} not installed")

# Scenario 2: Corrupted distribution
try:
    meta = dist.metadata
except MetadataNotFound:
    print("Package metadata is missing")

# Scenario 3: Safe query
try:
    v = version('requests')
except PackageNotFoundError:
    v = None
```

--------------------------------

### Get Parent Path

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/04-packagepath-filehash.md

Access the logical parent directory of a package path. Useful for navigating directory structures within a package.

```python
path = PackagePath('requests/models/response.py')
print(path.parent)  # Output: requests/models
```

--------------------------------

### Get Package Dependencies

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/00-START-HERE.md

Retrieve a list of packages that a given package depends on. This is useful for understanding package requirements and managing environments.

```python
from importlib_metadata import requires
deps = requires('flask')
```

--------------------------------

### Importing Core Components

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/INDEX.md

Import necessary components from the importlib_metadata library for accessing package information, files, and handling errors.

```python
from importlib_metadata import entry_points
```

```python
from importlib_metadata import files, Distribution
```

```python
from importlib_metadata import PackageNotFoundError, MetadataNotFound
```

--------------------------------

### Import Core Classes

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/README.md

Import the main classes used for working with package distributions and metadata.

```python
from importlib_metadata import (
    Distribution,
    DistributionFinder,
    EntryPoint,
    EntryPoints,
    PackagePath,
    FileHash,
    PackageMetadata,
)
```

--------------------------------

### version

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Retrieves the version string for a specified package. This function is equivalent to accessing the 'Version' key from the package's metadata.

```APIDOC
## version

### Description
Get the version string for the named package. Convenience function that retrieves the version from a package's metadata. Equivalent to `metadata(name)['Version']`.

### Method
```python
def version(distribution_name: str) -> str:
```

### Parameters
#### Path Parameters
- **distribution_name** (str) - Required - The name of the distribution package to query

### Returns
- **str** - The version string as defined in the package's "Version" metadata key

### Raises
- **PackageNotFoundError** - When package is not found
- **MetadataNotFound** - If no metadata file is present
- **ValueError** - When distribution_name is invalid

### Example
```python
from importlib_metadata import version

try:
    v = version('pip')
    print(f"pip version: {v}")
except Exception as e:
    print(f"Error: {e}")

# Version comparison
from packaging.version import Version
v1 = Version(version('setuptools'))
v2 = Version('65.0.0')
if v1 >= v2:
    print("setuptools is up to date")
```
```

--------------------------------

### Get Package Metadata

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Retrieves parsed metadata for a specified package. Use this to access details like Name, Version, Summary, and Classifiers.

```python
from importlib_metadata import metadata

meta = metadata('setuptools')
print(f"Name: {meta['Name']}")
print(f"Version: {meta['Version']}")
print(f"Summary: {meta.get('Summary', 'N/A')}")

# Get all values for multi-valued keys
if 'Classifier' in meta:
    classifiers = meta.get_all('Classifier')
    for classifier in classifiers:
        print(f"  {classifier}")
```

--------------------------------

### Graceful Fallback for Package Metadata

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/08-errors.md

Provides a function to retrieve package information, including name, version, and summary. It handles both PackageNotFoundError and MetadataNotFound, returning minimal info or None as appropriate.

```python
from importlib_metadata import distribution, MetadataNotFound, PackageNotFoundError

def get_package_info(package_name):
    try:
        dist = distribution(package_name)
        try:
            meta = dist.metadata
            return {
                'name': meta['Name'],
                'version': meta['Version'],
                'summary': meta.get('Summary', 'N/A')
            }
        except MetadataNotFound:
            # Metadata corrupted, provide minimal info
            return {
                'name': package_name,
                'version': 'unknown',
                'summary': 'Metadata not available'
            }
    except PackageNotFoundError:
        return None

info = get_package_info('requests')
```

--------------------------------

### Check Package Dependencies

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

List the dependencies of a specified package using the 'requires' function and parse them using packaging.requirements.

```python
from importlib_metadata import requires
from packaging.requirements import Requirement

reqs = requires('pytest') or []
for req_str in reqs:
    req = Requirement(req_str)
    print(f"Package: {req.name}, Version: {req.specifier}")
```

--------------------------------

### distribution

Source: https://github.com/python/importlib_metadata/blob/main/_autodocs/03-module-functions.md

Retrieves the Distribution instance for a specified package name. It's a convenience wrapper for Distribution.from_name() and returns the first valid distribution found.

```APIDOC
## distribution

### Description
Get the `Distribution` instance for the named package. Convenience function that wraps `Distribution.from_name()`. Returns the first valid distribution found for the given name.

### Method
```python
def distribution(distribution_name: str) -> Distribution:
```

### Parameters
#### Path Parameters
- **distribution_name** (str) - Required - The name of the distribution package as a string

### Returns
- **Distribution** - A Distribution instance (or subclass thereof)

### Raises
- **PackageNotFoundError** - When the package is not found
- **ValueError** - When distribution_name is empty or invalid

### Example
```python
from importlib_metadata import distribution, PackageNotFoundError

try:
    dist = distribution('requests')
    print(f"Found: {dist.name} {dist.version}")
except PackageNotFoundError:
    print("Package 'requests' not found")
```
```