feat: py_* rules in Starlark

.bazelversion

@@ -1,4 +1,4 @@
-5.0.0
+5.1.0
 # The first line of this file is used by Bazelisk and Bazel to be sure
 # the right version of Bazel is used to build and test this repo.
 # This also defines which version is used on CI.

.gitattributes

@@ -0,0 +1 @@
+docs/*.md linguist-generated=true

.gitignore

@@ -1,2 +1,6 @@
 bazel-*
 .bazelrc.user
+.idea
+.ijwb
+.venv
+**/__pycache__

BUILD.bazel

@@ -1,6 +1,8 @@
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 
+# gazelle:exclude internal_python_deps.bzl
+# gazelle:exclude internal_deps.bzl
+
 gazelle_binary(
     name = "gazelle_bin",
     languages = ["@bazel_skylib//gazelle/bzl"],
@@ -10,13 +12,3 @@ gazelle(
     name = "gazelle",
     gazelle = "gazelle_bin",
 )
-
-bzl_library(
-    name = "internal_deps",
-    srcs = ["internal_deps.bzl"],
-    visibility = ["//visibility:public"],
-    deps = [
-        "@bazel_tools//tools/build_defs/repo:http.bzl",
-        "@bazel_tools//tools/build_defs/repo:utils.bzl",
-    ],
-)

CONTRIBUTING.md

@@ -31,9 +31,7 @@ directory:
 
 ```sh
 OVERRIDE="--override_repository=rules_py=$(pwd)/rules_py"
-echo "build $OVERRIDE" >> ~/.bazelrc
-echo "fetch $OVERRIDE" >> ~/.bazelrc
-echo "query $OVERRIDE" >> ~/.bazelrc
+echo "common $OVERRIDE" >> ~/.bazelrc
 ```
 
 This means that any usage of `@rules_py` on your system will point to this folder.

README.md

@@ -1,10 +1,45 @@
-1. if you don't need to fetch platform-dependent tools, then remove anything toolchain-related.
-1. update the `actions/cache@v2` bazel cache key in [.github/workflows/ci.yaml](.github/workflows/ci.yaml) and [.github/workflows/release.yml](.github/workflows/release.yml) to be a hash of your source files.
-1. delete this section of the README (everything up to the SNIP).
+# Aspect's Bazel rules for python
 
----- SNIP ----
+`aspect_rules_py` is a layer on top of `rules_python`, the standard Python ruleset hosted at
+https://github.com/bazelbuild/rules_python.
+It is currently EXPERIMENTAL and pre-release. No support is promised. There may be breaking changes,
+or we may archive and abandon the repository.
 
-# Bazel rules for py
+Some parts of `rules_python` are reused:
+
+- Same toolchain for fetching a hermetic python interpreter.
+- `pip_parse` rule for translating a requirements-lock.txt file into Bazel repository fetching rules
+  and installing those packages into external repositories.
+- The Gazelle extension for generating BUILD.bazel files works the same.
+
+However, this ruleset introduces a new implementation of `py_library`, `py_binary`, and `py_test`.
+The starlark implementations allow us to innovate, while the existing ones are embedded in Bazel's
+Java sources in the bazelbuild/bazel repo and therefore very difficult to get changes made.
+
+> We understand that there is also an effort at Google to "starlarkify" the Python rules,
+> but there is no committed roadmap or dates.
+> Given the history of other projects coming from Google, we've chosen not to wait.
+
+Our philosophy is to behave more like idiomatic python ecosystem tools.
+Having a starlark implementation allows us to do things like
+attach Bazel transitions, mypy typechecking actions, etc.
+
+Things that are improved in rules_py:
+
+- We don't mess with the Python `sys.path`/`$PYTHONPATH`. Instead we use the standard `site-packages` folder layout produced by `pip_install`. This avoids problems like package naming collisions with built-ins (e.g. `collections`) or where `argparse` comes from a transitive dependency instead. (Maybe helps with diamond dependencies too).
+- We run python in isolated mode so we don't accidentally break out of Bazel's action sandbox, fixing:
+  - [pypi libraries installed to system python are implicitly available to builds](https://github.com/bazelbuild/rules_python/issues/27)
+  - [sys.path[0] breaks out of runfile tree.](https://github.com/bazelbuild/rules_python/issues/382)
+- We create a python-idiomatic virtualenv to run actions, which means better compatibility with userland implementations of [importlib](https://docs.python.org/3/library/importlib.html).
+- Thanks to the virtualenv, you can open the project in an editor like PyCharm and have working auto-complete, jump-to-definition, etc.
+- The launcher uses the Bash toolchain rather than Python, so we have no dependency on a system interpreter - fixes MacOS no longer shipping with python.
+
+Improvements planned:
+
+- Build wheels in actions, so it's possible to have native packages built for the target platform,
+  e.g. for a rules_docker py3_image.
+- Support `--only_binary=:all:` by always building wheels from source using a hermetic Bazel cc toolchain.
+- `dep` on wheels directly, rather than on a `py_library` that wraps it. Then we don't have to append to the `.pth` file to locate them.
 
 ## Installation
 

WORKSPACE

@@ -15,9 +15,23 @@ load("@rules_python//python:repositories.bzl", "python_register_toolchains")
 
 python_register_toolchains(
     name = "python_toolchain",
-    python_version = "3.10",
+    python_version = "3.9",
 )
 
+############################################
+# Development dependencies from pypi
+load("@python_toolchain//:defs.bzl", "interpreter")
+
+load(":internal_python_deps.bzl", "rules_py_internal_pypi_deps")
+
+rules_py_internal_pypi_deps(
+    interpreter = interpreter
+)
+
+load("@pypi//:requirements.bzl", "install_deps")
+
+install_deps()
+
 # For running our own unit tests
 load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 

docs/BUILD.bazel

@@ -3,11 +3,18 @@
 load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
 
 stardoc_with_diff_test(
+    name = "rules",
     bzl_library_target = "//py:defs",
-    out_label = "//docs:rules.md",
 )
 
-update_docs(
-    name = "update",
-    docs_folder = "docs",
+stardoc_with_diff_test(
+    name = "py_library",
+    bzl_library_target = "//py/private:py_library",
 )
+
+stardoc_with_diff_test(
+    name = "py_binary",
+    bzl_library_target = "//py/private:py_binary",
+)
+
+update_docs(name = "update")