Core Functions

def distribution(distribution_name: str) -> Distribution:
    """
    Get the Distribution instance for the named package.
    
    Parameters:
    - distribution_name: The name of the distribution package as a string
    
    Returns:
    Distribution: A Distribution instance (or subclass thereof)
    
    Raises:
    PackageNotFoundError: When the named package's distribution metadata cannot be found
    """

def distributions(**kwargs) -> Iterable[Distribution]:
    """
    Get all Distribution instances in the current environment.
    
    Parameters:
    - **kwargs: Keyword arguments for constructing a DistributionFinder.Context
    
    Returns:
    Iterable[Distribution]: An iterable of Distribution instances
    """

def metadata(distribution_name: str) -> PackageMetadata | None:
    """
    Get the metadata for the named package.
    
    Parameters:
    - distribution_name: The name of the distribution package to query
    
    Returns:
    PackageMetadata: A PackageMetadata containing the parsed metadata, or None if not found
    """

def version(distribution_name: str) -> str:
    """
    Get the version string for the named package.
    
    Parameters:
    - distribution_name: The name of the distribution package to query
    
    Returns:
    str: The version string for the package as defined in the package's "Version" metadata key
    
    Raises:
    PackageNotFoundError: When the named package cannot be found
    """

import importlib_metadata

# Get a distribution object
dist = importlib_metadata.distribution('requests')
print(f"Package: {dist.name}, Version: {dist.version}")

# Get all distributions
all_dists = list(importlib_metadata.distributions())
print(f"Found {len(all_dists)} installed packages")

# Get metadata directly
meta = importlib_metadata.metadata('requests')
print(f"Author: {meta['Author']}")
print(f"Summary: {meta['Summary']}")

# Get version string
version = importlib_metadata.version('requests')
print(f"requests version: {version}")

def entry_points(**params) -> EntryPoints:
    """
    Return EntryPoint objects for all installed packages.
    
    Pass selection parameters (group or name) to filter the result to entry points 
    matching those properties (see EntryPoints.select()).
    
    Parameters:
    - **params: Selection parameters for filtering (group, name, etc.)
    
    Returns:
    EntryPoints: EntryPoints collection for all installed packages
    """

import importlib_metadata

# Get all entry points
all_eps = importlib_metadata.entry_points()
print(f"Found {len(all_eps)} entry points")

# Get console scripts only
console_scripts = importlib_metadata.entry_points(group='console_scripts')
for ep in console_scripts:
    print(f"Script: {ep.name} -> {ep.value}")

# Get entry points by name
pip_eps = importlib_metadata.entry_points(name='pip')
for ep in pip_eps:
    print(f"pip entry point in group '{ep.group}': {ep.value}")

def files(distribution_name: str) -> list[PackagePath] | None:
    """
    Return a list of files for the named package.
    
    Parameters:
    - distribution_name: The name of the distribution package to query
    
    Returns:
    list[PackagePath] | None: List of files composing the distribution, or None if 
                              the metadata file that enumerates files is missing
    """

def requires(distribution_name: str) -> list[str] | None:
    """
    Return a list of requirements for the named package.
    
    Parameters:
    - distribution_name: The name of the distribution package to query
    
    Returns:
    list[str] | None: An iterable of requirements, suitable for 
                      packaging.requirement.Requirement, or None if no requirements
    """

def packages_distributions() -> Mapping[str, list[str]]:
    """
    Return a mapping of top-level packages to their distributions.
    
    Returns:
    Mapping[str, list[str]]: Dictionary mapping package names to list of distribution names
    """

import importlib_metadata

# Get package files
files = importlib_metadata.files('requests')
if files:
    print(f"requests has {len(files)} files")
    for file_path in files[:5]:  # Show first 5
        print(f"  {file_path}")

# Get package dependencies
deps = importlib_metadata.requires('requests')
if deps:
    print("requests dependencies:")
    for dep in deps:
        print(f"  {dep}")

# Get package to distribution mapping
pkg_to_dist = importlib_metadata.packages_distributions()
print(f"requests package provided by: {pkg_to_dist.get('requests', 'unknown')}")

import importlib_metadata

try:
    version = importlib_metadata.version('nonexistent-package')
except importlib_metadata.PackageNotFoundError as e:
    print(f"Package not found: {e.name}")