feat: produce publishable distribution archives (#1019)

* feat: produce publishable distribution archives

Fixes #741

* fix: give unique names to dist/ folders by default

Author: alexeagle

.github/workflows/release.yml

@@ -15,15 +15,15 @@ jobs:
       - name: Prepare workspace snippet
         run: .github/workflows/workspace_snippet.sh > release_notes.txt
       - name: Build wheel dist
-        run: bazel build --stamp --embed_label=${{ env.GITHUB_REF_NAME }} //python/runfiles:wheel
+        run: bazel build --stamp --embed_label=${{ env.GITHUB_REF_NAME }} //python/runfiles:wheel.dist
       - name: Publish runfiles package to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           # Note, the PYPI_API_TOKEN was added on
           # https://github.com/bazelbuild/rules_python/settings/secrets/actions 
           # and currently uses a token which authenticates as https://pypi.org/user/alexeagle/
           password: ${{ secrets.PYPI_API_TOKEN }}
-          packages_dir: bazel-bin/python/runfiles
+          packages_dir: bazel-bin/python/runfiles/dist
       - name: Release
         uses: softprops/action-gh-release@v1
         with:

docs/packaging.md

@@ -31,6 +31,43 @@ This rule is intended to be used as data dependency to py_wheel rule.
     attrs = py_package_lib.attrs,
 )
 
+# Based on https://github.com/aspect-build/bazel-lib/tree/main/lib/private/copy_to_directory.bzl
+# Avoiding a bazelbuild -> aspect-build dependency :(
+def _py_wheel_dist_impl(ctx):
+    dir = ctx.actions.declare_directory(ctx.attr.out)
+    name_file = ctx.attr.wheel[PyWheelInfo].name_file
+    cmds = [
+        "mkdir -p \"%s\"" % dir.path,
+        """cp "{}" "{}/$(cat "{}")" """.format(ctx.files.wheel[0].path, dir.path, name_file.path),
+    ]
+    ctx.actions.run_shell(
+        inputs = ctx.files.wheel + [name_file],
+        outputs = [dir],
+        command = "\n".join(cmds),
+        mnemonic = "CopyToDirectory",
+        progress_message = "Copying files to directory",
+        use_default_shell_env = True,
+    )
+    return [
+        DefaultInfo(files = depset([dir])),
+    ]
+
+py_wheel_dist = rule(
+    doc = """\
+Prepare a dist/ folder, following Python's packaging standard practice.
+
+See https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives
+which recommends a dist/ folder containing the wheel file(s), source distributions, etc.
+
+This also has the advantage that stamping information is included in the wheel's filename.
+""",
+    implementation = _py_wheel_dist_impl,
+    attrs = {
+        "out": attr.string(doc = "name of the resulting directory", mandatory = True),
+        "wheel": attr.label(doc = "a [py_wheel rule](/docs/packaging.md#py_wheel_rule)", providers = [PyWheelInfo]),
+    },
+)
+
 def py_wheel(name, **kwargs):
     """Builds a Python Wheel.
 
@@ -80,15 +117,12 @@ def py_wheel(name, **kwargs):
         name:  A unique name for this target.
         **kwargs: other named parameters passed to the underlying [py_wheel rule](#py_wheel_rule)
     """
-    _py_wheel(name = name, **kwargs)
+    py_wheel_dist(
+        name = "{}.dist".format(name),
+        wheel = name,
+        out = kwargs.pop("dist_folder", "{}_dist".format(name)),
+    )
 
-    # TODO(alexeagle): produce an executable target like this:
-    # py_publish_wheel(
-    #     name = "{}.publish".format(name),
-    #     wheel = name,
-    #     # Optional: override the label for a py_binary that runs twine
-    #     # https://twine.readthedocs.io/en/stable/
-    #     twine_bin = "//path/to:twine",
-    # )
+    _py_wheel(name = name, **kwargs)
 
 py_wheel_rule = _py_wheel

python/packaging.bzl

@@ -73,11 +73,23 @@ Stamped targets are not rebuilt unless their dependencies change.
     ),
     "version": attr.string(
         mandatory = True,
-        doc = (
-            "Version number of the package. Note that this attribute " +
-            "supports stamp format strings (eg. `1.2.3-{BUILD_TIMESTAMP}`) " +
-            "as well as 'make variables' (e.g. `1.2.3-$(VERSION)`)."
-        ),
+        doc = """\
+Version number of the package.
+
+Note that this attribute supports stamp format strings as well as 'make variables'.
+For example:
+  - `version = "1.2.3-{BUILD_TIMESTAMP}"`
+  - `version = "{BUILD_EMBED_LABEL}"`
+  - `version = "$(VERSION)"`
+
+Note that Bazel's output filename cannot include the stamp information, as outputs must be known
+during the analysis phase and the stamp data is available only during the action execution.
+
+The [`py_wheel`](/docs/packaging.md#py_wheel) macro produces a `.dist`-suffix target which creates a
+`dist/` folder containing the wheel with the stamped name, suitable for publishing.
+
+See [`py_wheel_dist`](/docs/packaging.md#py_wheel_dist) for more info.
+""",
     ),
     "_stamp_flag": attr.label(
         doc = "A setting used to determine whether or not the `--stamp` flag is enabled",

python/private/py_wheel.bzl

@@ -41,6 +41,7 @@ py_wheel(
         "License :: OSI Approved :: Apache Software License",
     ],
     description_file = "README.md",
+    dist_folder = "dist",
     distribution = "bazel_runfiles",
     homepage = "https://github.com/bazelbuild/rules_python",
     strip_path_prefixes = ["python"],