feat: add api for analysis-phase code

docs/BUILD.bazel

@@ -93,6 +93,7 @@ sphinx_stardocs(
         "//python:py_runtime_info_bzl",
         "//python:py_test_bzl",
         "//python:repositories_bzl",
+        "//python/api:api_bzl",
         "//python/cc:py_cc_toolchain_bzl",
         "//python/cc:py_cc_toolchain_info_bzl",
         "//python/entry_points:py_console_script_binary_bzl",

python/BUILD.bazel

@@ -34,6 +34,7 @@ licenses(["notice"])
 filegroup(
     name = "distribution",
     srcs = glob(["**"]) + [
+        "//python/api:distribution",
         "//python/cc:distribution",
         "//python/config_settings:distribution",
         "//python/constraints:distribution",

python/api/BUILD.bazel

@@ -0,0 +1,27 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+bzl_library(
+    name = "api_bzl",
+    srcs = ["api.bzl"],
+    visibility = ["//visibility:public"],
+    deps = ["//python/private/api:api_bzl"],
+)
+
+filegroup(
+    name = "distribution",
+    srcs = glob(["**"]),
+)

python/api/api.bzl

@@ -0,0 +1,5 @@
+"""Public, analysis phase APIs for Python rules."""
+
+load("//python/private/api:api.bzl", _py_common = "py_common")
+
+py_common = _py_common

python/private/api/BUILD.bazel

@@ -0,0 +1,43 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load(":py_common_api.bzl", "py_common_api")
+
+package(
+    default_visibility = ["//:__subpackages__"],
+)
+
+py_common_api(
+    name = "py_common_api",
+    # NOTE: Not actually public. Implicit dependency of public rules.
+    visibility = ["//visibility:public"],
+)
+
+bzl_library(
+    name = "api_bzl",
+    srcs = ["api.bzl"],
+    deps = [
+        "//python/private:py_info_bzl",
+    ],
+)
+
+bzl_library(
+    name = "py_common_api_bzl",
+    srcs = ["py_common_api.bzl"],
+    deps = [
+        ":api_bzl",
+        "//python/private:py_info_bzl",
+    ],
+)

python/private/api/api.bzl

@@ -0,0 +1,41 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Implementation of py_api."""
+
+_PY_COMMON_API_LABEL = Label("//python/private/api:py_common_api")
+
+ApiImplInfo = provider(
+    fields = {
+        "impl": """
+:type: struct
+
+The implementation of the API being provided.
+""",
+    },
+)
+
+def _py_common_get(ctx):
+    # A generic provider is used to decouple the API implementations from
+    # the loading phase of the rules using an implementation.
+    return ctx.attr._py_common_api[ApiImplInfo].impl
+
+py_common = struct(
+    get = _py_common_get,
+    API_ATTRS = {
+        "_py_common_api": attr.label(
+            default = _PY_COMMON_API_LABEL,
+            providers = [ApiImplInfo],
+        ),
+    },
+)

python/private/api/py_common_api.bzl

@@ -0,0 +1,50 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Implementation of py_api."""
+
+load("//python/private:py_info.bzl", "PyInfoBuilder")
+load("//python/private/api:api.bzl", "ApiImplInfo")
+
+PyCommonApiInfo = provider(
+    doc = """
+Analysis-time APIs for rule implementations.
+""",
+    fields = {
+        "merge_py_infos": """
+:type: callable
+""",
+        "PyInfoBuilder": """
+:type: callable
+""",
+    },
+)
+
+def _py_common_api_impl(ctx):
+    _ = ctx  # @unused
+    return [ApiImplInfo(impl = PyCommonApiInfo(
+        merge_py_infos = _merge_py_infos,
+        PyInfoBuilder = PyInfoBuilder,
+    ))]
+
+py_common_api = rule(
+    implementation = _py_common_api_impl,
+)
+
+def _merge_py_infos(transitive, *, direct = None):
+    builder = PyInfoBuilder()
+    if direct:
+        builder.direct_pyc_files.add(direct.direct_pyc_files)
+    builder.merge(direct)
+    builder.merge_all(transitive)
+    return builder.build()