tools/python/srcs_version.bzl - bazel - Git at Google

 # Copyright 2019 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.

 """Defines an aspect for finding constraints on the Python version."""

 _PY2 = "PY2"
 _PY3 = "PY3"

 _TransitiveVersionInfo = provider(
     doc = """\
 Propagates information about the Python version constraints of transitive
 dependencies.

 Canonically speaking, a target is considered to be PY2-only if it returns the
 `py` provider with the `has_py2_only_sources` field set to `True`. Likewise, it
 is PY3-only if `has_py3_only_sources` is `True`. Unless something weird is going
 on with how the transitive sources are aggregated, it is expected that if any
 target is PY2-only or PY3-only, then so are all of its reverse transitive deps.

 The `py_library` rule becomes PY2-only or PY3-only when its `srcs_version`
 attribute is respectively set to `PY2ONLY` or to either `PY3` or `PY3ONLY`.
 (The asymmetry of not recongizing `PY2` is due to
 [#1393](https://github.com/bazelbuild/bazel/issues/1393) and will be moot once
 the `PY2ONLY` and `PY3ONLY` names are retired.) Therefore, if the transitive
 deps of the root target are all `py_library` targets, we can look at the
 `srcs_version` attribute to easily distinguish targets whose own sources
 require a given Python version, from targets that only require it due to their
 transitive deps.

 If on the other hand there are other rule types in the transitive deps that do
 not define `srcs_version`, then the only general way to tell that a dep
 introduces a requirement on Python 2 or 3 is if it returns true in the
 corresponding provider field and none of its direct dependencies returns true
 in that field.

 This `_TransitiveVersionInfo` provider reports transitive deps that satisfy
 either of these criteria. But of those deps, it only reports those that are
 "top-most" in relation to the root. The top-most deps are the ones that are
 reachable from the root target by a path that does not involve any other
 top-most dep (though it's possible for one top-most dep to have a separate path
 to another). Reporting only the top-most deps ensures that we give the minimal
 information needed to understand how the root target depends on PY2-only or
 PY3-only targets.
 """,
     fields = {
         "py2": """\
 A `_DepsWithPathsInfo` object for transitive deps that are known to introduce a
 PY2-only requirement.
 """,
         "py3": """\
 A `_DepsWithPathsInfo` object for transitive deps that are known to introduce a
 PY3-only requirement.
 """,
     },
 )

 _DepsWithPathsInfo = provider(
     fields = {
         "topmost": """\
 A list of labels of all top-most transitive deps known to introduce a version
 requirement. The deps appear in left-to-right order.
 """,
         "paths": """\
 A dictionary that maps labels appearing in `topmost` to their paths from the
 root. Paths are represented as depsets with `preorder` order.
 """,
         # It is technically possible for the depset keys to collide if the same
         # target appears multiple times in the build graph as different
         # configured targets, but this seems unlikely.
     },
 )

 def _join_lines(nodes):
     return "\n".join([str(n) for n in nodes]) if nodes else "<None>"

 def _str_path(path):
     return " -> ".join([str(p) for p in path.to_list()])

 def _str_tv_info(tv_info):
     """Returns a string representation of a `_TransitiveVersionInfo`."""
     path_lines = []
     path_lines.extend([_str_path(tv_info.py2.paths[n]) for n in tv_info.py2.topmost])
     path_lines.extend([_str_path(tv_info.py3.paths[n]) for n in tv_info.py3.topmost])
     return """\
 Python 2-only deps:
 {py2_nodes}

 Python 3-only deps:
 {py3_nodes}

 Paths to these deps:
 {paths}
 """.format(
         py2_nodes = _join_lines(tv_info.py2.topmost),
         py3_nodes = _join_lines(tv_info.py3.topmost),
         paths = _join_lines(path_lines),
     )

 def _has_version_requirement(target, version):
     """Returns whether a target has a version requirement, as per its provider.

     Args:
         target: the `Target` object to check
         version: either the string "PY2" or "PY3"

     Returns:
         `True` if `target` requires `version` according to the
         `has_py<?>_only_sources` fields
     """
     if version not in [_PY2, _PY3]:
         fail("Unrecognized version '%s'; must be 'PY2' or 'PY3'" % version)
     field = {
         _PY2: "has_py2_only_sources",
         _PY3: "has_py3_only_sources",
     }[version]

     if not PyInfo in target:
         return False
     field_value = getattr(target[PyInfo], field, False)
     if not type(field_value) == "bool":
         fail("Invalid type for provider field '%s': %r" % (field, field_value))
     return field_value

 def _introduces_version_requirement(target, target_attr, version):
     """Returns whether a target introduces a PY2-only or PY3-only requirement.

     A target that has a version requirement is considered to introduce this
     requirement if either 1) its rule type has a `srcs_version` attribute and
     the target sets it to `PY2ONLY` (PY2), or `PY3` or `PY3ONLY` (PY3); or 2)
     none of its direct dependencies set `has_py2_only_sources` (PY2) or
     `has_py3_only_sources` (PY3) to `True`. A target that does not actually have
     the version requirement is never considered to introduce the requirement.

     Args:
         target: the `Target` object as passed to the aspect implementation
             function
         target_attr: the attribute struct as retrieved from `ctx.rule.attr` in
             the aspect implementation function
         version: either the string "PY2" or "PY3" indicating which constraint
             to test for

     Returns:
         `True` if `target` introduces the requirement on `version`, as per the
         above definition
     """
     if version not in [_PY2, _PY3]:
         fail("Unrecognized version '%s'; must be 'PY2' or 'PY3'" % version)

     # If we don't actually have the version requirement, we can't possibly
     # introduce it, regardless of our srcs_version or what our dependencies
     # return.
     if not _has_version_requirement(target, version):
         return False

     # Try the attribute, if present.
     if hasattr(target_attr, "srcs_version"):
         sv = target_attr.srcs_version
         if version == _PY2:
             if sv == "PY2ONLY":
                 return True
         elif version == _PY3:
             if sv in ["PY3", "PY3ONLY"]:
                 return True
         else:
             fail("Illegal state")

     # No good, check the direct deps' provider fields.
     if not hasattr(target_attr, "deps"):
         return True
     else:
         return not any([
             _has_version_requirement(dep, version)
             for dep in target_attr.deps
         ])

 def _empty_depswithpaths():
     """Initializes an empty `_DepsWithPathsInfo` object."""
     return _DepsWithPathsInfo(topmost = [], paths = {})

 def _init_depswithpaths_for_node(node):
     """Initialize a new `_DepsWithPathsInfo` object.

     The object will record just the given node as its sole entry.

     Args:
         node: a label

     Returns:
         a `_DepsWithPathsInfo` object
     """
     return _DepsWithPathsInfo(
         topmost = [node],
         paths = {node: depset(direct = [node], order = "preorder")},
     )

 def _merge_depswithpaths_appending_node(depswithpaths, node_to_append):
     """Merge several `_DepsWithPathsInfo` objects and appends a path entry.

     Args:
         depswithpaths: a list of `_DepsWithPathsInfo` objects whose entries are
             to be merged
         node_to_append: a label to append to all the paths of the merged object

     Returns:
         a `_DepsWithPathsInfo` object
     """
     seen = {}
     topmost = []
     paths = {}
     for dwp in depswithpaths:
         for node in dwp.topmost:
             if node in seen:
                 continue
             seen[node] = True

             topmost.append(node)
             path = dwp.paths[node]
             path = depset(
                 direct = [node_to_append],
                 transitive = [path],
                 order = "preorder",
             )
             paths[node] = path
     return _DepsWithPathsInfo(topmost = topmost, paths = paths)

 def _find_requirements_impl(target, ctx):
     # Determine whether this target introduces a requirement. If so, any deps
     # that introduce that requirement are not propagated, though they might
     # still be considered top-most if an alternate path exists.
     if not hasattr(ctx.rule.attr, "deps"):
         dep_tv_infos = []
     else:
         dep_tv_infos = [
             d[_TransitiveVersionInfo]
             for d in ctx.rule.attr.deps
             if _TransitiveVersionInfo in d
         ]

     if not _has_version_requirement(target, "PY2"):
         new_py2 = _empty_depswithpaths()
     elif _introduces_version_requirement(target, ctx.rule.attr, "PY2"):
         new_py2 = _init_depswithpaths_for_node(target.label)
     else:
         new_py2 = _merge_depswithpaths_appending_node(
             [i.py2 for i in dep_tv_infos],
             target.label,
         )

     if not _has_version_requirement(target, "PY3"):
         new_py3 = _empty_depswithpaths()
     elif _introduces_version_requirement(target, ctx.rule.attr, "PY3"):
         new_py3 = _init_depswithpaths_for_node(target.label)
     else:
         new_py3 = _merge_depswithpaths_appending_node(
             [i.py3 for i in dep_tv_infos],
             target.label,
         )

     tv_info = _TransitiveVersionInfo(py2 = new_py2, py3 = new_py3)

     output = ctx.actions.declare_file(target.label.name + "-pyversioninfo.txt")
     ctx.actions.write(output = output, content = _str_tv_info(tv_info))

     return [tv_info, OutputGroupInfo(pyversioninfo = depset(direct = [output]))]

 find_requirements = aspect(
     implementation = _find_requirements_impl,
     attr_aspects = ["deps"],
     doc = """\
 The aspect definition. Can be invoked on the command line as

     bazel build //pkg:my_py_binary_target \
         --aspects=@rules_python//python:defs.bzl%find_requirements \
         --output_groups=pyversioninfo
 """,
 )

 def _apply_find_requirements_for_testing_impl(ctx):
     tv_info = ctx.attr.target[_TransitiveVersionInfo]
     ctx.actions.write(output = ctx.outputs.out, content = _str_tv_info(tv_info))

 apply_find_requirements_for_testing = rule(
     implementation = _apply_find_requirements_for_testing_impl,
     attrs = {
         "target": attr.label(aspects = [find_requirements]),
         "out": attr.output(),
     },
     doc = """\
 Writes the string output of `find_requirements` to a file.

 This helper exists for the benefit of PythonSrcsVersionAspectTest.java. It is
 useful because code outside this file cannot read the private
 `_TransitiveVersionInfo` provider, and `BuildViewTestCase` cannot easily access
 actions generated by an aspect.
 """,
 )
	# Copyright 2019 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.

	"""Defines an aspect for finding constraints on the Python version."""

	_PY2 = "PY2"
	_PY3 = "PY3"

	_TransitiveVersionInfo = provider(
	doc = """\
	Propagates information about the Python version constraints of transitive
	dependencies.

	Canonically speaking, a target is considered to be PY2-only if it returns the
	`py` provider with the `has_py2_only_sources` field set to `True`. Likewise, it
	is PY3-only if `has_py3_only_sources` is `True`. Unless something weird is going
	on with how the transitive sources are aggregated, it is expected that if any
	target is PY2-only or PY3-only, then so are all of its reverse transitive deps.

	The `py_library` rule becomes PY2-only or PY3-only when its `srcs_version`
	attribute is respectively set to `PY2ONLY` or to either `PY3` or `PY3ONLY`.
	(The asymmetry of not recongizing `PY2` is due to
	[#1393](https://github.com/bazelbuild/bazel/issues/1393) and will be moot once
	the `PY2ONLY` and `PY3ONLY` names are retired.) Therefore, if the transitive
	deps of the root target are all `py_library` targets, we can look at the
	`srcs_version` attribute to easily distinguish targets whose own sources
	require a given Python version, from targets that only require it due to their
	transitive deps.

	If on the other hand there are other rule types in the transitive deps that do
	not define `srcs_version`, then the only general way to tell that a dep
	introduces a requirement on Python 2 or 3 is if it returns true in the
	corresponding provider field and none of its direct dependencies returns true
	in that field.

	This `_TransitiveVersionInfo` provider reports transitive deps that satisfy
	either of these criteria. But of those deps, it only reports those that are
	"top-most" in relation to the root. The top-most deps are the ones that are
	reachable from the root target by a path that does not involve any other
	top-most dep (though it's possible for one top-most dep to have a separate path
	to another). Reporting only the top-most deps ensures that we give the minimal
	information needed to understand how the root target depends on PY2-only or
	PY3-only targets.
	""",
	fields = {
	"py2": """\
	A `_DepsWithPathsInfo` object for transitive deps that are known to introduce a
	PY2-only requirement.
	""",
	"py3": """\
	A `_DepsWithPathsInfo` object for transitive deps that are known to introduce a
	PY3-only requirement.
	""",
	},
	)

	_DepsWithPathsInfo = provider(
	fields = {
	"topmost": """\
	A list of labels of all top-most transitive deps known to introduce a version
	requirement. The deps appear in left-to-right order.
	""",
	"paths": """\
	A dictionary that maps labels appearing in `topmost` to their paths from the
	root. Paths are represented as depsets with `preorder` order.
	""",
	# It is technically possible for the depset keys to collide if the same
	# target appears multiple times in the build graph as different
	# configured targets, but this seems unlikely.
	},
	)

	def _join_lines(nodes):
	return "\n".join([str(n) for n in nodes]) if nodes else "<None>"

	def _str_path(path):
	return " -> ".join([str(p) for p in path.to_list()])

	def _str_tv_info(tv_info):
	"""Returns a string representation of a `_TransitiveVersionInfo`."""
	path_lines = []
	path_lines.extend([_str_path(tv_info.py2.paths[n]) for n in tv_info.py2.topmost])
	path_lines.extend([_str_path(tv_info.py3.paths[n]) for n in tv_info.py3.topmost])
	return """\
	Python 2-only deps:
	{py2_nodes}

	Python 3-only deps:
	{py3_nodes}

	Paths to these deps:
	{paths}
	""".format(
	py2_nodes = _join_lines(tv_info.py2.topmost),
	py3_nodes = _join_lines(tv_info.py3.topmost),
	paths = _join_lines(path_lines),
	)

	def _has_version_requirement(target, version):
	"""Returns whether a target has a version requirement, as per its provider.

	Args:
	target: the `Target` object to check
	version: either the string "PY2" or "PY3"

	Returns:
	`True` if `target` requires `version` according to the
	`has_py<?>_only_sources` fields
	"""
	if version not in [_PY2, _PY3]:
	fail("Unrecognized version '%s'; must be 'PY2' or 'PY3'" % version)
	field = {
	_PY2: "has_py2_only_sources",
	_PY3: "has_py3_only_sources",
	}[version]

	if not PyInfo in target:
	return False
	field_value = getattr(target[PyInfo], field, False)
	if not type(field_value) == "bool":
	fail("Invalid type for provider field '%s': %r" % (field, field_value))
	return field_value

	def _introduces_version_requirement(target, target_attr, version):
	"""Returns whether a target introduces a PY2-only or PY3-only requirement.

	A target that has a version requirement is considered to introduce this
	requirement if either 1) its rule type has a `srcs_version` attribute and
	the target sets it to `PY2ONLY` (PY2), or `PY3` or `PY3ONLY` (PY3); or 2)
	none of its direct dependencies set `has_py2_only_sources` (PY2) or
	`has_py3_only_sources` (PY3) to `True`. A target that does not actually have
	the version requirement is never considered to introduce the requirement.

	Args:
	target: the `Target` object as passed to the aspect implementation
	function
	target_attr: the attribute struct as retrieved from `ctx.rule.attr` in
	the aspect implementation function
	version: either the string "PY2" or "PY3" indicating which constraint
	to test for

	Returns:
	`True` if `target` introduces the requirement on `version`, as per the
	above definition
	"""
	if version not in [_PY2, _PY3]:
	fail("Unrecognized version '%s'; must be 'PY2' or 'PY3'" % version)

	# If we don't actually have the version requirement, we can't possibly
	# introduce it, regardless of our srcs_version or what our dependencies
	# return.
	if not _has_version_requirement(target, version):
	return False

	# Try the attribute, if present.
	if hasattr(target_attr, "srcs_version"):
	sv = target_attr.srcs_version
	if version == _PY2:
	if sv == "PY2ONLY":
	return True
	elif version == _PY3:
	if sv in ["PY3", "PY3ONLY"]:
	return True
	else:
	fail("Illegal state")

	# No good, check the direct deps' provider fields.
	if not hasattr(target_attr, "deps"):
	return True
	else:
	return not any([
	_has_version_requirement(dep, version)
	for dep in target_attr.deps
	])

	def _empty_depswithpaths():
	"""Initializes an empty `_DepsWithPathsInfo` object."""
	return _DepsWithPathsInfo(topmost = [], paths = {})

	def _init_depswithpaths_for_node(node):
	"""Initialize a new `_DepsWithPathsInfo` object.

	The object will record just the given node as its sole entry.

	Args:
	node: a label

	Returns:
	a `_DepsWithPathsInfo` object
	"""
	return _DepsWithPathsInfo(
	topmost = [node],
	paths = {node: depset(direct = [node], order = "preorder")},
	)

	def _merge_depswithpaths_appending_node(depswithpaths, node_to_append):
	"""Merge several `_DepsWithPathsInfo` objects and appends a path entry.

	Args:
	depswithpaths: a list of `_DepsWithPathsInfo` objects whose entries are
	to be merged
	node_to_append: a label to append to all the paths of the merged object

	Returns:
	a `_DepsWithPathsInfo` object
	"""
	seen = {}
	topmost = []
	paths = {}
	for dwp in depswithpaths:
	for node in dwp.topmost:
	if node in seen:
	continue
	seen[node] = True

	topmost.append(node)
	path = dwp.paths[node]
	path = depset(
	direct = [node_to_append],
	transitive = [path],
	order = "preorder",
	)
	paths[node] = path
	return _DepsWithPathsInfo(topmost = topmost, paths = paths)

	def _find_requirements_impl(target, ctx):
	# Determine whether this target introduces a requirement. If so, any deps
	# that introduce that requirement are not propagated, though they might
	# still be considered top-most if an alternate path exists.
	if not hasattr(ctx.rule.attr, "deps"):
	dep_tv_infos = []
	else:
	dep_tv_infos = [
	d[_TransitiveVersionInfo]
	for d in ctx.rule.attr.deps
	if _TransitiveVersionInfo in d
	]

	if not _has_version_requirement(target, "PY2"):
	new_py2 = _empty_depswithpaths()
	elif _introduces_version_requirement(target, ctx.rule.attr, "PY2"):
	new_py2 = _init_depswithpaths_for_node(target.label)
	else:
	new_py2 = _merge_depswithpaths_appending_node(
	[i.py2 for i in dep_tv_infos],
	target.label,
	)

	if not _has_version_requirement(target, "PY3"):
	new_py3 = _empty_depswithpaths()
	elif _introduces_version_requirement(target, ctx.rule.attr, "PY3"):
	new_py3 = _init_depswithpaths_for_node(target.label)
	else:
	new_py3 = _merge_depswithpaths_appending_node(
	[i.py3 for i in dep_tv_infos],
	target.label,
	)

	tv_info = _TransitiveVersionInfo(py2 = new_py2, py3 = new_py3)

	output = ctx.actions.declare_file(target.label.name + "-pyversioninfo.txt")
	ctx.actions.write(output = output, content = _str_tv_info(tv_info))

	return [tv_info, OutputGroupInfo(pyversioninfo = depset(direct = [output]))]

	find_requirements = aspect(
	implementation = _find_requirements_impl,
	attr_aspects = ["deps"],
	doc = """\
	The aspect definition. Can be invoked on the command line as

	bazel build //pkg:my_py_binary_target \
	--aspects=@rules_python//python:defs.bzl%find_requirements \
	--output_groups=pyversioninfo
	""",
	)

	def _apply_find_requirements_for_testing_impl(ctx):
	tv_info = ctx.attr.target[_TransitiveVersionInfo]
	ctx.actions.write(output = ctx.outputs.out, content = _str_tv_info(tv_info))

	apply_find_requirements_for_testing = rule(
	implementation = _apply_find_requirements_for_testing_impl,
	attrs = {
	"target": attr.label(aspects = [find_requirements]),
	"out": attr.output(),
	},
	doc = """\
	Writes the string output of `find_requirements` to a file.

	This helper exists for the benefit of PythonSrcsVersionAspectTest.java. It is
	useful because code outside this file cannot read the private
	`_TransitiveVersionInfo` provider, and `BuildViewTestCase` cannot easily access
	actions generated by an aspect.
	""",
	)