refactor: API for deriving customized versions of the base rules (#2610)

This implements a "builder style" API to allow arbitrary modification of
rule, attr, etc
objects used when defining a rule. The net effect is users are able to
use the base
definition for our rules, but define their own with the modifications
they need, without
having to copy/paste portions our implementation, load private files, or
patch source.

The basic way it works is a mutable object ("builder") holds the args
and state that would
be used to create the immutable Bazel object. When `build()` is called,
the immutable
Bazel object (e.g. `attr.string()`) is created. Builders are implemented
for most objects
and their settings (rule, attrs, and supporting objects).

This design is necessary because of three Bazel behaviors:
* attr etc objects are immutable, which means we must keep our own state
* attr etc objects aren't inspectable, which means we must store the
arguments for
  creating the immutable objects.
* Starlark objects are frozen after initial bzl file evaluation, which
means creation
  of any mutable object must be done at the point of use.

The resulting API resembles the builder APIs common in other languages:

```
r = create_py_binary_rule_builder()
r.attrs.get("srcs").set_mandatory(True)
r.attrs.get("deps").aspects().append(my_aspect)
my_py_binary = r.build()
```

Most objects are thin wrappers for managing a kwargs dict. As such, and
because they're
wrapping a foreign API, they aren't strict in enforcing their internal
state and the
kwargs dict is publicly exposed as an escape hatch.

As of this PR, no public API for e.g. `create_py_binary_rule_builder()`
is exposed. That'll come in a separate PR (to add public access points
under python/api).

Work towards #1647

Author: rickeylev

docs/BUILD.bazel

@@ -103,11 +103,14 @@ sphinx_stardocs(
         "//python/cc:py_cc_toolchain_bzl",
         "//python/cc:py_cc_toolchain_info_bzl",
         "//python/entry_points:py_console_script_binary_bzl",
+        "//python/private:attr_builders_bzl",
+        "//python/private:builders_util_bzl",
         "//python/private:py_binary_rule_bzl",
         "//python/private:py_cc_toolchain_rule_bzl",
         "//python/private:py_library_rule_bzl",
         "//python/private:py_runtime_rule_bzl",
         "//python/private:py_test_rule_bzl",
+        "//python/private:rule_builders_bzl",
         "//python/private/api:py_common_api_bzl",
         "//python/private/pypi:config_settings_bzl",
         "//python/private/pypi:pkg_aliases_bzl",

docs/_includes/field_kwargs_doc.md

@@ -0,0 +1,11 @@
+:::{field} kwargs
+:type: dict[str, Any]
+
+Additional kwargs to use when building. This is to allow manipulations that
+aren't directly supported by the builder's API. The state of this dict
+may or may not reflect prior API calls, and subsequent API calls may
+modify this dict. The general contract is that modifications to this will
+be respected when `build()` is called, assuming there were no API calls
+in between.
+:::
+

python/private/BUILD.bazel

@@ -51,10 +51,20 @@ filegroup(
     visibility = ["//python:__pkg__"],
 )
 
+bzl_library(
+    name = "attr_builders_bzl",
+    srcs = ["attr_builders.bzl"],
+    deps = [
+        ":builders_util_bzl",
+        "@bazel_skylib//lib:types",
+    ],
+)
+
 bzl_library(
     name = "attributes_bzl",
     srcs = ["attributes.bzl"],
     deps = [
+        ":attr_builders_bzl",
         ":common_bzl",
         ":enum_bzl",
         ":flags_bzl",
@@ -92,6 +102,14 @@ bzl_library(
     ],
 )
 
+bzl_library(
+    name = "builders_util_bzl",
+    srcs = ["builders_util.bzl"],
+    deps = [
+        "@bazel_skylib//lib:types",
+    ],
+)
+
 bzl_library(
     name = "bzlmod_enabled_bzl",
     srcs = ["bzlmod_enabled.bzl"],
@@ -283,6 +301,7 @@ bzl_library(
     deps = [
         ":attributes_bzl",
         ":py_executable_bzl",
+        ":rule_builders_bzl",
         ":semantics_bzl",
         "@bazel_skylib//lib:dicts",
     ],
@@ -410,6 +429,7 @@ bzl_library(
         ":flags_bzl",
         ":py_cc_link_params_info_bzl",
         ":py_internal_bzl",
+        ":rule_builders_bzl",
         ":toolchain_types_bzl",
         "@bazel_skylib//lib:dicts",
         "@bazel_skylib//rules:common_settings",
@@ -475,6 +495,7 @@ bzl_library(
         ":py_internal_bzl",
         ":py_runtime_info_bzl",
         ":reexports_bzl",
+        ":rule_builders_bzl",
         ":util_bzl",
         "@bazel_skylib//lib:dicts",
         "@bazel_skylib//lib:paths",
@@ -515,6 +536,7 @@ bzl_library(
         ":attributes_bzl",
         ":common_bzl",
         ":py_executable_bzl",
+        ":rule_builders_bzl",
         ":semantics_bzl",
         "@bazel_skylib//lib:dicts",
     ],
@@ -563,6 +585,16 @@ bzl_library(
     srcs = ["repo_utils.bzl"],
 )
 
+bzl_library(
+    name = "rule_builders_bzl",
+    srcs = ["rule_builders.bzl"],
+    deps = [
+        ":builders_bzl",
+        ":builders_util_bzl",
+        "@bazel_skylib//lib:types",
+    ],
+)
+
 bzl_library(
     name = "semver_bzl",
     srcs = ["semver.bzl"],