Stub Dependency Expansion

Compute the full external requirement list for a stub distribution by walking its declared dependencies and their nested stubs using repository metadata.

@generates

Capabilities

Resolve stub requirement closure

Given a repository root containing stubs/<distribution>/METADATA.toml, derive all external requirements and dependent stub distributions for a requested stub, expanding through nested stub dependencies and optional extras. Deduplicate results and return them in a deterministic, sorted-by-string order; missing metadata raises a clear error.

• Resolving only external requirements returns them unchanged in input order. Example: when stubs/simple/METADATA.toml lists requires = ["requests>=2"], resolve_stub_requirements("simple", root) returns ["requests>=2"]. @test
• Nested stub dependencies are included with their own external requirements. Example: demo depends on stub types-foo plus pytest; types-foo depends on stub types-bar plus httpx. Expect ["pytest", "httpx"] from resolve_stub_requirements("demo", root) because types-bar has no extra external deps beyond what types-foo contributes. @test
• Extras filter which dependency sets participate. Example: featureful declares base requirement ["numpy"], extra postgres adding stub types-psycopg2 and external psycopg2-binary, and types-psycopg2 depends on typing-extensions. Calling resolve_stub_requirements("featureful", root, extras=["postgres"]) returns ["numpy", "psycopg2-binary", "typing-extensions"]; calling without extras omits the extra-only requirements. @test
• Cycles between stub dependencies do not produce duplicates; repeated requirements from shared transitive deps appear once in the deterministic output ordering. @test

API

from pathlib import Path
from typing import Iterable, Sequence

def resolve_stub_requirements(distribution: str, root: Path, extras: Iterable[str] | None = None) -> Sequence[str]:
    """
    Build the deterministically ordered, deduplicated list of requirement strings for a stub distribution.
    distribution: stub distribution name that has a metadata directory under root/stubs.
    root: repository root containing stubs metadata files.
    extras: optional extras to include; when None, include only base requirements.
    Returns requirement strings for external packages pulled from the target stub and all recursively required stubs, sorted by requirement string.
    Raises a KeyError when metadata for distribution is missing.
    """

Dependencies { .dependencies }

typeshed utilities { .dependency }

Provides helpers for reading stub metadata and resolving dependency graphs across stubs. @satisfied-by