Stubtest Invocation Planner

A utility that prepares stubtest system requirements and allowlist arguments for selected stub distributions, producing a ready-to-run plan for CI.

Capabilities

Platform requirements

• Given distributions like stdlib and requests on the default platform, returns a de-duplicated, alphabetically sorted list of system packages needed to run stubtest, skipping any distribution that marks stubtest as skipped or omits the platform from its CI platforms. @test
• When the platform is overridden to win32, the requirements list is re-evaluated for that platform and excludes distributions not configured for it. @test

Allowlist discovery

• For the standard library, collects stubtest allowlist paths from stdlib/@tests/stubtest_allowlists, including common, platform-only, version-only, combined platform+version, and local version files, returning argument pairs only for files that exist. @test
• For a third-party distribution, looks in its @tests directory and returns allowlist argument pairs in order: the generic allowlist then the platform-specific allowlist when those files exist. @test

Combined plan output

• Produces a plan object that combines the platform-specific system requirements and per-distribution allowlist argument lists, preserving deterministic ordering in both sections. @test

Implementation

@generates

API

from typing import TypedDict, List, Dict, Optional

class StubtestPlan(TypedDict):
    system_requirements: List[str]
    allowlists: Dict[str, List[str]]

def build_stubtest_plan(distributions: List[str], platform: Optional[str] = None) -> StubtestPlan:
    """
    Build stubtest invocation data for the given distributions.

    - platform: optional override such as "linux", "darwin", or "win32".
    - system_requirements: unique system packages needed to run stubtest on the platform.
    - allowlists: mapping of distribution name to stubtest --allowlist arguments (each entry is a list like ["--allowlist", "<path>", ...]).
    """

Dependencies { .dependencies }

ts_utils { .dependency }

Provides access to stub metadata, platform-aware stubtest requirements, and discovery helpers for stubtest allowlist files so you don't reimplement repository-specific logic.