docs: clarify that PyInfo.transitive_sources may not include py files (#2367)
The docs previously somewhat implied that the `srcs` were always
present, which isn't true
for e.g. pyc-only builds.
diff --git a/python/private/py_info.bzl b/python/private/py_info.bzl
index 7a0bdea..4b2b888 100644
--- a/python/private/py_info.bzl
+++ b/python/private/py_info.bzl
@@ -129,11 +129,14 @@
"transitive_sources": """\
:type: depset[File]
-A (`postorder`-compatible) depset of `.py` files appearing in the target's
-`srcs` and the `srcs` of the target's transitive `deps`.
+A (`postorder`-compatible) depset of `.py` files that are considered required
+and downstream binaries (or equivalent) **must** include in their outputs
+to have a functioning program.
-These are `.py` source files that are considered required and downstream
-binaries (or equivalent) must include in their outputs.
+Normally, these are the `.py` files in the appearing in the target's `srcs` and
+the `srcs` of the target's transitive `deps`, **however**, precompile settings
+may cause `.py` files to be omitted. In particular, pyc-only builds may result
+in this depset being **empty**.
::::{versionchanged} 0.37.0
The files are considered necessary for downstream binaries to function;
