Stub Metadata Report

Build utilities that summarize third-party stub packages from their repository metadata. The report must rely on the dependency package's metadata helpers for parsing and validation rather than bespoke TOML handling.

Capabilities

Summarize stub metadata

• Calling summarize_stub("alpha") on a stub whose METADATA.toml contains version = "1.2.0", requires = ["types-urllib3", "requests>=2.28"], upload = false, partial_stub = true, requires_python = ">=3.9", and tool.stubtest.ci_platforms = ["linux", "darwin"] returns a summary with version equal to "==1.2.0", stub_distribution defaulted to "types-alpha", typeshed_dependencies = ["urllib3"], external_dependencies = ["requests>=2.28"], uploaded_to_pypi = False, partial_stub = True, requires_python = ">=3.9", and ci_platforms listing ["linux", "darwin"]. @test

Optional platform requirements

• When platform="linux" and the stub's tool.stubtest section lists apt_dependencies = ["libxml2-dev"] and brew_dependencies = ["libxml2"], the summary includes system_requirements["linux"] = ["libxml2-dev"] and omits other package manager keys; when platform="darwin", the summary includes the brew values; unsupported platforms raise ValueError. @test

Missing stub handling

• Requesting a summary for a stub that has no METADATA.toml entry raises an exception that mentions the missing distribution name. @test

Implementation

@generates

API

from dataclasses import dataclass
from typing import Optional, Sequence

@dataclass
class StubSummary:
    distribution: str
    version: str
    stub_distribution: str
    upstream_repository: Optional[str]
    requires_python: str
    uploaded_to_pypi: bool
    partial_stub: bool
    obsolete: Optional[str]
    typeshed_dependencies: list[str]
    external_dependencies: list[str]
    ci_platforms: list[str]
    system_requirements: dict[str, list[str]]

def summarize_stub(distribution: str, platform: Optional[str] = None) -> StubSummary:
    """
    Produce a summary of a stub package using repository metadata and validation helpers.
    The optional platform flag filters system requirements for a single platform.
    """

def summarize_many(distributions: Sequence[str], platform: Optional[str] = None) -> list[StubSummary]:
    """
    Produce summaries for multiple stub packages, preserving the input order.
    """

Dependencies { .dependencies }

typeshed { .dependency }

Provides stub metadata parsing and validation helpers.