feat(py_wheel): Add support for specifying Description-Content-Type and Summary in METADATA (#1274)

`py_wheel` allows to supply a description file, but it does not allow
specifying the content type of that file.
By default, the type is "text/x-rst", but many packages are using a
markdown description.


https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type

This change added the support.

---------

Co-authored-by: Richard Levasseur <[email protected]>

Author: sfc-gh-zpeng

docs/packaging.md

@@ -160,6 +160,7 @@ py_wheel(
     python_tag = "py3",
     # Requirements embedded into the wheel metadata.
     requires = ["pytest"],
+    summary = "A one-line summary of this test package",
     version = "0.0.1",
     deps = [":example_pkg"],
 )

examples/wheel/BUILD.bazel

@@ -99,7 +99,7 @@ def test_customized_wheel(self):
                 record_contents,
                 # The entries are guaranteed to be sorted.
                 b"""\
-example_customized-0.0.1.dist-info/METADATA,sha256=YUnzQ9gTMXspIBURe90Ct3aL_CCn8fwC3SiZe6MMTs8,372
+example_customized-0.0.1.dist-info/METADATA,sha256=vRiyyV45PC5fzK_40nSTtIn3yYzDdsbBAbUvkZiRyc8,461
 example_customized-0.0.1.dist-info/NOTICE,sha256=Xpdw-FXET1IRgZ_wTkx1YQfo1-alET0FVf6V1LXO4js,76
 example_customized-0.0.1.dist-info/README,sha256=WmOFwZ3Jga1bHG3JiGRsUheb4UbLffUxyTdHczS27-o,40
 example_customized-0.0.1.dist-info/RECORD,,
@@ -129,6 +129,8 @@ def test_customized_wheel(self):
 Author-email: [email protected]
 Home-page: www.example.com
 License: Apache 2.0
+Description-Content-Type: text/markdown
+Summary: A one-line summary of this test package
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Intended Audience :: Developers
 Requires-Dist: pytest

examples/wheel/wheel_test.py

@@ -155,6 +155,11 @@ _other_attrs = {
     "classifiers": attr.string_list(
         doc = "A list of strings describing the categories for the package. For valid classifiers see https://pypi.org/classifiers",
     ),
+    "description_content_type": attr.string(
+        doc = ("The type of contents in description_file. " +
+               "If not provided, the type will be inferred from the extension of description_file. " +
+               "Also see https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type"),
+    ),
     "description_file": attr.label(
         doc = "A file containing text describing the package.",
         allow_single_file = True,
@@ -181,8 +186,17 @@ _other_attrs = {
         default = [],
         doc = "path prefixes to strip from files added to the generated package",
     ),
+    "summary": attr.string(
+        doc = "A one-line summary of what the distribution does",
+    ),
 }
 
+_DESCRIPTION_FILE_EXTENSION_TO_TYPE = {
+    "md": "text/markdown",
+    "rst": "text/x-rst",
+}
+_DEFAULT_DESCRIPTION_FILE_TYPE = "text/plain"
+
 def _escape_filename_segment(segment):
     """Escape a segment of the wheel filename.
 
@@ -275,6 +289,17 @@ def _py_wheel_impl(ctx):
         metadata_contents.append("Home-page: %s" % ctx.attr.homepage)
     if ctx.attr.license:
         metadata_contents.append("License: %s" % ctx.attr.license)
+    if ctx.attr.description_content_type:
+        metadata_contents.append("Description-Content-Type: %s" % ctx.attr.description_content_type)
+    elif ctx.attr.description_file:
+        # infer the content type from description file extension.
+        description_file_type = _DESCRIPTION_FILE_EXTENSION_TO_TYPE.get(
+            ctx.file.description_file.extension,
+            _DEFAULT_DESCRIPTION_FILE_TYPE,
+        )
+        metadata_contents.append("Description-Content-Type: %s" % description_file_type)
+    if ctx.attr.summary:
+        metadata_contents.append("Summary: %s" % ctx.attr.summary)
 
     for c in ctx.attr.classifiers:
         metadata_contents.append("Classifier: %s" % c)

python/private/py_wheel.bzl

@@ -289,6 +289,9 @@ def parse_args() -> argparse.Namespace:
     wheel_group.add_argument(
         "--description_file", help="Path to the file with package description"
     )
+    wheel_group.add_argument(
+        "--description_content_type", help="Content type of the package description"
+    )
     wheel_group.add_argument(
         "--entry_points_file",
         help="Path to a correctly-formatted entry_points.txt file",