Improve PyPI READMEs for stubs packages (#105)

Author: AlexWaygood

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)