Stub Publish Plan

A small tool that turns a third-party stub package directory into a publishable plan by reading its metadata, classifying dependencies, and persisting the result for release workflows.

Capabilities

Read stub metadata

• Given a stub directory with a version value like 1.2.3 and no explicit stub distribution name, the publish plan normalizes the version to an exact spec (e.g., ==1.2.3) and defaults the stub distribution to types-{distribution}. @test
• When the metadata file sets an upload flag to false, the publish plan marks the package as not uploadable while still returning the rest of the fields. @test
• If no requires-python value is present, the publish plan fills it with the repository's default minimum supported Python version. @test

Classify dependencies

• If the metadata lists both another stub package and an external library as requirements, the publish plan separates them into internal stub dependencies and external dependencies using their declared specifiers. @test

Persist publish plan

• Writing the publish plan to a path produces a JSON file containing the computed fields (distribution name, normalized version, upload flag, requires-python value, dependency groups, upstream link if present, and partial-stub flag) and returns the same structure. @test

Implementation

@generates

API

from pathlib import Path
from typing import TypedDict

class PublishPlan(TypedDict):
    stub_distribution: str
    version_spec: str
    upload_enabled: bool
    requires_python: str
    typeshed_dependencies: list[str]
    external_dependencies: list[str]
    upstream_repository: str | None
    partial_stub: bool

def build_publish_plan(distribution: str) -> PublishPlan:
    """
    Construct a publish plan for stubs/<distribution> by reading its metadata and classifying dependencies.
    """

def write_publish_plan(distribution: str, output_path: str | Path) -> PublishPlan:
    """
    Write the publish plan as JSON to output_path and return the computed plan.
    """

Dependencies { .dependencies }

typeshed publishing utilities { .dependency }

Provides metadata parsing and dependency resolution for stub distributions to prepare PEP 561 uploads.

@satisfied-by