importlib-metadata 9.0.0: Inspect installed entry points, package metadata, and wheel files with importlib-metadata 9.0.0 without loading plugins or using the network

# importlib-metadata installed metadata APIs

This sample pins `importlib-metadata` 9.0.0 and its only unconditional runtime
dependency, `zipp` 4.1.0. The contract reads metadata already installed by pip;
it does not query an index, load an entry-point target, or access the network.

The useful traps are that `EntryPoints.__getitem__` looks up an entry-point name
rather than a numeric index, repeated metadata headers require `get_all()`, and
`files()` returns `PackagePath` records carrying distribution, hash, size, and
location behavior rather than plain strings.

The exact dependency pair and normalized distribution-name lookup were adapted
from a compatible CSX sample. Its Linux contract had two verified passes; this
sample adds independent Windows evidence and covers separate public APIs.

{"case":{"believed":"Callers often treat entry_points() and files() as plain lists of strings or paths and miss the selection, name lookup, distribution, hash, and location semantics carried by their specialized result objects.","caseId":"case:sha256:347dea2fd266973bb8b09eb5d86826c3d80ba9929a782cb3262bf577b24c36e5","contract":["The third-party importlib_metadata package resolves its installed 9.0.0 distribution under normalized hyphen and underscore names.","metadata() preserves repeated headers through get_all() and exposes normalized JSON fields, including the zipp runtime requirement.","entry_points() returns EntryPoints whose select() filters by group and name; EntryPoints lookup is by entry-point name rather than numeric position.","The installed pip console entry point exposes module and attr without loading the target plugin.","files() returns PackagePath objects tied to their distribution; locate() reaches the imported third-party module and RECORD supplies hashes and sizes except for its own row."],"goal":"Inspect installed entry points, package metadata, and wheel files with importlib-metadata 9.0.0 without loading plugins or using the network","kind":"HOW","packages":["pkg:pypi/importlib-metadata@9.0.0","pkg:pypi/zipp@4.1.0"],"schemaVersion":1,"symbols":["importlib_metadata.version","importlib_metadata.metadata","importlib_metadata.PackageMetadata.json","importlib_metadata.entry_points","importlib_metadata.EntryPoints.select","importlib_metadata.EntryPoints.__getitem__","importlib_metadata.EntryPoint.module","importlib_metadata.EntryPoint.attr","importlib_metadata.files","importlib_metadata.PackagePath.locate","importlib_metadata.PackagePath.hash","importlib_metadata.PackagePath.size"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/importlib-metadata@9.0.0","pkg:pypi/zipp@4.1.0"],"schemaVersion":1,"symbols":["importlib_metadata.version","importlib_metadata.metadata","importlib_metadata.PackageMetadata.json","importlib_metadata.entry_points","importlib_metadata.EntryPoints.select","importlib_metadata.EntryPoints.__getitem__","importlib_metadata.EntryPoint.module","importlib_metadata.EntryPoint.attr","importlib_metadata.files","importlib_metadata.PackagePath.locate","importlib_metadata.PackagePath.hash","importlib_metadata.PackagePath.size"],"verifierAdapter":"python@1"}

importlib-metadata==9.0.0
zipp==4.1.0

from pathlib import Path

import importlib_metadata


def expect_key_error(action):
    try:
        action()
    except KeyError:
        return
    raise AssertionError("expected name-based EntryPoints lookup to reject index 0")


# Prove this is the backport package, not Python's importlib.metadata module.
module_file = Path(importlib_metadata.__file__).resolve()
assert module_file.name == "__init__.py"
assert module_file.parent.name == "importlib_metadata"
assert importlib_metadata.version("importlib-metadata") == "9.0.0"
assert importlib_metadata.version("importlib_metadata") == "9.0.0"

# PackageMetadata behaves like an email message as well as exposing a normalized
# JSON view. Repeated headers must be read with get_all(), not ordinary lookup.
package_metadata = importlib_metadata.metadata("importlib-metadata")
assert package_metadata["Version"] == "9.0.0"
assert package_metadata["Name"].replace("_", "-").casefold() == "importlib-metadata"
classifiers = package_metadata.get_all("Classifier")
assert classifiers is not None and len(classifiers) > 1
assert package_metadata["Classifier"] == classifiers[0]

metadata_json = package_metadata.json
assert metadata_json["version"] == "9.0.0"
assert metadata_json["classifier"] == classifiers
runtime_requirements = package_metadata.get_all("Requires-Dist") or []
assert "zipp>=3.20" in runtime_requirements
assert metadata_json["requires_dist"] == runtime_requirements
assert importlib_metadata.version("zipp") == "4.1.0"

# Selection operates on EntryPoints and can combine group and name filters.
# The pip distribution is part of the Python/pip execution environment, so its
# console-script metadata is available without importing or loading pip itself.
all_entry_points = importlib_metadata.entry_points()
assert isinstance(all_entry_points, importlib_metadata.EntryPoints)
pip_distribution = importlib_metadata.distribution("pip")
pip_scripts = pip_distribution.entry_points.select(group="console_scripts")
assert isinstance(pip_scripts, importlib_metadata.EntryPoints)

pip_matches = pip_scripts.select(name="pip")
assert len(pip_matches) == 1
pip_entry = pip_matches["pip"]
expect_key_error(lambda: pip_matches[0])
assert pip_entry.group == "console_scripts"
assert pip_entry.value == "pip._internal.cli.main:main"
assert pip_entry.module == "pip._internal.cli.main"
assert pip_entry.attr == "main"
assert pip_entry.extras == []
assert pip_entry.matches(group="console_scripts", name="pip")

global_matches = all_entry_points.select(group="console_scripts", name="pip")
assert any(
    entry.value == pip_entry.value
    and entry.dist.name.casefold() == "pip"
    for entry in global_matches
)
assert not pip_scripts.select(group="__codesamplex_missing_group__")

# files() yields PackagePath records, not detached pathlib paths. Their dist,
# hash, size, and locate/read helpers are backed by installed wheel metadata.
package_files = importlib_metadata.files("importlib-metadata")
assert package_files is not None
init_path = next(
    item
    for item in package_files
    if str(item).replace("\\", "/") == "importlib_metadata/__init__.py"
)
assert isinstance(init_path, importlib_metadata.PackagePath)
assert init_path.dist.name.replace("_", "-").casefold() == "importlib-metadata"
assert Path(init_path.locate()).resolve() == module_file
assert init_path.hash is not None and init_path.hash.mode == "sha256"
assert init_path.hash.value
assert init_path.size == module_file.stat().st_size
assert "APIs exposing metadata" in init_path.read_text(encoding="utf-8")

record_path = next(item for item in package_files if str(item).endswith("/RECORD"))
assert record_path.hash is None
assert record_path.size is None

print(
    "CONTRACT PASS: importlib_metadata EntryPoints, metadata, and PackagePath "
    "semantics verified offline"
)