Improve PyPI READMEs for stubs packages

stub_uploader/build_wheel.py

@@ -98,13 +98,18 @@
 DESCRIPTION_INTRO_TEMPLATE = """
 ## Typing stubs for {distribution}
 
-This is a PEP 561 type stub package for the `{distribution}` package. It
-can be used by type-checking tools like
+This is a [PEP 561](https://peps.python.org/pep-0561/)
+type stub package for the {formatted_distribution} package.
+It can be used by type-checking tools like
 [mypy](https://github.com/python/mypy/),
 [pyright](https://github.com/microsoft/pyright),
 [pytype](https://github.com/google/pytype/),
 PyCharm, etc. to check code that uses
-`{distribution}`. The source for this package can be found at
+`{distribution}`.
+
+This version of `{stub_distribution}` aims to provide accurate annotations
+for `{distribution}=={typeshed_version_pin}`.
+The source for this package can be found at
 https://github.com/python/typeshed/tree/main/stubs/{distribution}. All fixes for
 types and metadata should be contributed there.
 """.strip()
@@ -276,7 +281,20 @@ def generate_long_description(
 ) -> str:
  extra_description = metadata.extra_description.strip()
  parts: list[str] = []
- parts.append(DESCRIPTION_INTRO_TEMPLATE.format(distribution=distribution))
+
+ if metadata.upstream_repository is not None:
+ formatted_distribution = f"[`{distribution}`]({metadata.upstream_repository})"
+ else:
+ formatted_distribution = f"`{distribution}`"
+
+ parts.append(
+ DESCRIPTION_INTRO_TEMPLATE.format(
+ distribution=distribution,
+ formatted_distribution=formatted_distribution,
+ stub_distribution=metadata.stub_distribution,
+ typeshed_version_pin=metadata.version_spec,
+ )
+ )
  if extra_description:
  parts.append(extra_description)
  if metadata.obsolete_since:

stub_uploader/metadata.py

@@ -5,6 +5,7 @@
 import os
 import re
 import tarfile
+import urllib.parse
 from collections.abc import Generator, Iterable
 from glob import glob
 from pathlib import Path
@@ -112,6 +113,21 @@ def requires_python(self) -> str | None:
  verify_requires_python(req)
  return req
 
+ @functools.cached_property
+ def upstream_repository(self) -> str | None:
+ ts_upstream_repo = self.data.get("upstream_repository")
+ if not isinstance(ts_upstream_repo, str):
+ # either typeshed doesn't list it for these stubs,
+ # or it gives a non-str for the field (bad!)
+ return None
+ try:
+ parsed_url = urllib.parse.urlsplit(ts_upstream_repo)
+ except ValueError:
+ return None
+ if parsed_url.scheme != "https":
+ return None
+ return ts_upstream_repo
+
 
 def read_metadata(typeshed_dir: str, distribution: str) -> Metadata:
  """Parse metadata from file."""

tests/test_unit.py

@@ -3,13 +3,14 @@
 from io import StringIO
 import os
 import tempfile
+from typing import Any
 
 import pytest
 from packaging.version import Version
 
 from stub_uploader.build_wheel import collect_setup_entries
 from stub_uploader.get_version import compute_incremented_version, ensure_specificity
-from stub_uploader.metadata import _UploadedPackages, strip_types_prefix
+from stub_uploader.metadata import _UploadedPackages, strip_types_prefix, Metadata
 from stub_uploader.ts_data import parse_requirements
 
 
@@ -179,3 +180,21 @@ def test_parse_requirements__parsed_packages(name: str, version: str) -> None:
 def test_parse_requirements__skipped_packages(name: str) -> None:
  requirements = parse_requirements(StringIO(_REQUIREMENTS_TXT))
  assert name not in requirements, f"package {name} was not skipped"
+
+
+@pytest.mark.parametrize(
+ "data,expected",
+ [
+ ({}, None),
+ ({"upstream_repository": 12345}, None),
+ ({"upstream_repository": "https://[].foo.com"}, None),
+ (
+ {"upstream_repository": "https://github.com/psf/requests"},
+ "https://github.com/psf/requests",
+ ),
+ ],
+)
+def test_upstream_repo_validation(data: dict[str, Any], expected: str | None) -> None:
+ m = Metadata("foo", data)
+ assert m.upstream_repository == expected
+ assert type(m.upstream_repository) is type(expected)