Stub Test Suite Planner

Build a helper module to gather stubtest inputs and configuration for a typeshed-style repository while respecting repository ignore rules and cross-platform temporary file behavior.

Capabilities

Gitignore-aware filtering

• When passed a base path containing a .gitignore that excludes a subdirectory, test discovery skips that ignored directory even if it contains test cases. @test

Test case discovery

• Given stdlib and third-party stub distributions with populated test_cases directories, it returns entries in order with stdlib first followed by alphabetical distributions, each including the resolved test_cases path. @test
• If a distribution has an empty test_cases directory, discovery raises an error instead of silently ignoring it. @test

Allowlist arguments

• For a distribution with stubtest allowlist files present, it produces CLI arguments --allowlist <path> for each existing allowlist in priority order for the current platform and Python version. @test

Temporary config emission

• It provides a context manager that writes provided stubtest configuration lines to a temporary file, yields its path, keeps the file usable on Windows while open, and removes it when the context exits. @test

Implementation

@generates

API

from __future__ import annotations
from contextlib import contextmanager
from dataclasses import dataclass
from pathlib import Path
from typing import Iterable, Iterator


@dataclass(frozen=True)
class DistributionTests:
    name: str
    test_cases_path: Path


def discover_test_cases(base_path: Path) -> list[DistributionTests]:
    """Return stdlib first then third-party distributions with non-empty test_cases directories, skipping gitignored paths."""


def build_allowlist_args(distribution_name: str, base_path: Path) -> list[str]:
    """Return stubtest allowlist CLI arguments for the distribution based on existing allowlist files."""


@contextmanager
def temporary_config(lines: Iterable[str]) -> Iterator[Path]:
    """Yield the path to a temp config file containing the lines, ensuring the file remains usable cross-platform until cleanup."""

Dependencies { .dependencies }

ts_utils { .dependency }

Provides cross-platform temporary files, gitignore parsing, and stubtest discovery helpers for a typeshed-style repository.