Skip to content

Commit d85a392

Browse files
rickeylevrickeylev
authored
feat: add public API for analysis-phase logic (bazel-contrib#2252)
This adds a public API for rules (i.e. analysis-phase code) to use code from rules_python. The main motivation for this is so that users can propagate PyInfo without having to know all the fields of PyInfo and implement the merging logic. With upcoming PRs adding additional fields to PyInfo, this becomes much more important. The way the API is exposed is through a target. There are three reasons for this: 1. It avoids loading phase costs when the implementation of the API functions change. Within Google, this makes changes to rules_python much cheaper and easier to submit and revert. This also allows us to worry less about the loading-phase impact of our code. 2. Because a target can have dependencies, it allows us to hide some details from users. For example, if we want a flag to affect behavior, we can add it to the API target's attributes; users don't have to add it to their rule's attributes 3. By having the API take the user's `ctx` as an argument, it allows us to capture it and use it as part of future API calls (this isn't used now, but gives us flexibility in the future). Work towards bazel-contrib#1647
1 parent 30fc3f9 commit d85a392

12 files changed

Lines changed: 302 additions & 23 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ A brief description of the categories of changes:
4747
* (toolchains): A public `//python/config_settings:python_version_major_minor` has
4848
been exposed for users to be able to match on the `X.Y` version of a Python
4949
interpreter.
50+
* (api) Added {obj}`merge_py_infos()` so user rules can merge and propagate
51+
`PyInfo` without losing information.
5052

5153
### Removed
5254
* Nothing yet

‎docs/BUILD.bazel‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,10 +93,12 @@ sphinx_stardocs(
9393
"//python:py_runtime_info_bzl",
9494
"//python:py_test_bzl",
9595
"//python:repositories_bzl",
96+
"//python/api:api_bzl",
9697
"//python/cc:py_cc_toolchain_bzl",
9798
"//python/cc:py_cc_toolchain_info_bzl",
9899
"//python/entry_points:py_console_script_binary_bzl",
99100
"//python/private:py_cc_toolchain_rule_bzl",
101+
"//python/private/api:py_common_api_bzl",
100102
"//python/private/common:py_binary_rule_bazel_bzl",
101103
"//python/private/common:py_library_rule_bazel_bzl",
102104
"//python/private/common:py_runtime_rule_bzl",

‎python/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ licenses(["notice"])
3434
filegroup(
3535
name = "distribution",
3636
srcs = glob(["**"]) + [
37+
"//python/api:distribution",
3738
"//python/cc:distribution",
3839
"//python/config_settings:distribution",
3940
"//python/constraints:distribution",

‎python/api/BUILD.bazel‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Copyright 2024 The Bazel Authors. All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
16+
17+
package(
18+
default_visibility = ["//:__subpackages__"],
19+
)
20+
21+
bzl_library(
22+
name = "api_bzl",
23+
srcs = ["api.bzl"],
24+
visibility = ["//visibility:public"],
25+
deps = ["//python/private/api:api_bzl"],
26+
)
27+
28+
filegroup(
29+
name = "distribution",
30+
srcs = glob(["**"]),
31+
)

‎python/api/api.bzl‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
"""Public, analysis phase APIs for Python rules."""
2+
3+
load("//python/private/api:api.bzl", _py_common = "py_common")
4+
5+
py_common = _py_common

‎python/private/api/BUILD.bazel‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Copyright 2024 The Bazel Authors. All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
16+
load(":py_common_api.bzl", "py_common_api")
17+
18+
package(
19+
default_visibility = ["//:__subpackages__"],
20+
)
21+
22+
py_common_api(
23+
name = "py_common_api",
24+
# NOTE: Not actually public. Implicit dependency of public rules.
25+
visibility = ["//visibility:public"],
26+
)
27+
28+
bzl_library(
29+
name = "api_bzl",
30+
srcs = ["api.bzl"],
31+
deps = [
32+
"//python/private:py_info_bzl",
33+
],
34+
)
35+
36+
bzl_library(
37+
name = "py_common_api_bzl",
38+
srcs = ["py_common_api.bzl"],
39+
deps = [
40+
":api_bzl",
41+
"//python/private:py_info_bzl",
42+
],
43+
)

‎python/private/api/api.bzl‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Copyright 2024 The Bazel Authors. All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
"""Implementation of py_api."""
15+
16+
_PY_COMMON_API_LABEL = Label("//python/private/api:py_common_api")
17+
18+
ApiImplInfo = provider(
19+
doc = "Provider to hold an API implementation",
20+
fields = {
21+
"impl": """
22+
:type: struct
23+
24+
The implementation of the API being provided. The object it contains
25+
will depend on the target that is providing the API struct.
26+
""",
27+
},
28+
)
29+
30+
def _py_common_get(ctx):
31+
"""Get the py_common API instance.
32+
33+
NOTE: to use this function, the rule must have added `py_common.API_ATTRS`
34+
to its attributes.
35+
36+
Args:
37+
ctx: {type}`ctx` current rule ctx
38+
39+
Returns:
40+
{type}`PyCommonApi`
41+
"""
42+
43+
# A generic provider is used to decouple the API implementations from
44+
# the loading phase of the rules using an implementation.
45+
return ctx.attr._py_common_api[ApiImplInfo].impl
46+
47+
py_common = struct(
48+
get = _py_common_get,
49+
API_ATTRS = {
50+
"_py_common_api": attr.label(
51+
default = _PY_COMMON_API_LABEL,
52+
providers = [ApiImplInfo],
53+
),
54+
},
55+
)

‎python/private/api/py_common_api.bzl‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Copyright 2024 The Bazel Authors. All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
"""Implementation of py_api."""
15+
16+
load("//python/private:py_info.bzl", "PyInfoBuilder")
17+
load("//python/private/api:api.bzl", "ApiImplInfo")
18+
19+
def _py_common_api_impl(ctx):
20+
_ = ctx # @unused
21+
return [ApiImplInfo(impl = PyCommonApi)]
22+
23+
py_common_api = rule(
24+
implementation = _py_common_api_impl,
25+
doc = "Rule implementing py_common API.",
26+
)
27+
28+
def _merge_py_infos(transitive, *, direct = []):
29+
builder = PyInfoBuilder()
30+
builder.merge_all(transitive, direct = direct)
31+
return builder.build()
32+
33+
# Exposed for doc generation, not directly used.
34+
# buildifier: disable=name-conventions
35+
PyCommonApi = struct(
36+
merge_py_infos = _merge_py_infos,
37+
PyInfoBuilder = PyInfoBuilder,
38+
)

‎python/private/py_info.bzl‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -181,11 +181,16 @@ def _PyInfoBuilder_set_uses_shared_libraries(self, value):
181181
self._uses_shared_libraries[0] = value
182182
return self
183183

184-
def _PyInfoBuilder_merge(self, *infos):
185-
return self.merge_all(infos)
184+
def _PyInfoBuilder_merge(self, *infos, direct = []):
185+
return self.merge_all(list(infos), direct = direct)
186186

187-
def _PyInfoBuilder_merge_all(self, py_infos):
188-
for info in py_infos:
187+
def _PyInfoBuilder_merge_all(self, transitive, *, direct = []):
188+
for info in direct:
189+
# BuiltinPyInfo doesn't have this field
190+
if hasattr(info, "direct_pyc_files"):
191+
self.direct_pyc_files.add(info.direct_pyc_files)
192+
193+
for info in direct + transitive:
189194
self.imports.add(info.imports)
190195
self.merge_has_py2_only_sources(info.has_py2_only_sources)
191196
self.merge_has_py3_only_sources(info.has_py3_only_sources)

‎tests/api/py_common/BUILD.bazel‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Copyright 2024 The Bazel Authors. All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
load(":py_common_tests.bzl", "py_common_test_suite")
16+
17+
py_common_test_suite(name = "py_common_tests")

0 commit comments

Comments
 (0)