fix: do not include transitive sources from pyi_deps in runtime runfiles

docs/api/rules_python/python/config_settings/index.md

@@ -242,6 +242,22 @@ The `auto` value
 The `omit_if_generated_source` value was removed
 ::::
 
+::::{bzl:flag} pyi_deps_to_runfiles
+Controls whether dependencies listed in `pyi_deps` are propagated to runtime
+runfiles.
+
+Values:
+
+* `auto`: (default) Automatically decide the effective value based on the
+  compilation mode. In `opt` and standard builds, `pyi_deps` are pruned from
+  runtime runfiles.
+* `yes`: Propagate `pyi_deps` into runtime runfiles (legacy behavior).
+* `no`: Do not propagate `pyi_deps` into runtime runfiles.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+::::
+
 ::::{bzl:flag} validate_test_main
 Determines if `py_test` runs a build-time validation that its main module
 actually runs tests.

news/4178.fixed.md

@@ -0,0 +1,6 @@
+(rules) Fixed {obj}`py_library.pyi_deps` being included in runtime output and
+bloating output. Type-checking only information is now in
+{obj}`PyInfo.type_checking_info`. Added the
+{obj}`--//python/config_settings:pyi_deps_to_runfiles` flag to configure or
+restore legacy runfile propagation if needed
+([#4178](https://github.com/bazel-contrib/rules_python/pull/4178)).

python/config_settings/BUILD.bazel

@@ -11,6 +11,7 @@ load(
     "LibcFlag",
     "PrecompileFlag",
     "PrecompileSourceRetentionFlag",
+    "PyiDepsToRunfilesFlag",
     "ValidateTestMainFlag",
     "VenvsSitePackages",
     "VenvsUseDeclareSymlinkFlag",
@@ -86,6 +87,14 @@ string_flag(
     visibility = NOT_ACTUALLY_PUBLIC,
 )
 
+string_flag(
+    name = "pyi_deps_to_runfiles",
+    build_setting_default = PyiDepsToRunfilesFlag.AUTO,
+    values = PyiDepsToRunfilesFlag.flag_values(),
+    # NOTE: Only public because it's an implicit dependency
+    visibility = NOT_ACTUALLY_PUBLIC,
+)
+
 string_flag(
     name = "precompile_source_retention",
     build_setting_default = PrecompileSourceRetentionFlag.AUTO,

python/private/BUILD.bazel

@@ -322,6 +322,7 @@ bzl_library(
     deps = [
         ":builders",
         ":cc_helper",
+        ":flags",
         ":py_cc_link_params_info",
         ":py_info",
         ":py_internal",

python/private/attributes.bzl

@@ -307,7 +307,8 @@ Dependencies providing type definitions the library needs.
 
 These are dependencies that satisfy imports guarded by `typing.TYPE_CHECKING`.
 These are build-time only dependencies and not included as part of a runnable
-program (packaging rules may include them, however).
+program (packaging rules may include them, however). Runtime inclusion can be
+configured using {obj}`--//python/config_settings:pyi_deps_to_runfiles`.
 
 :::{versionadded} 1.1.0
 :::
@@ -367,6 +368,10 @@ Allowed `.pyc` and directory inputs in `srcs`.
             default = labels.PRECOMPILE_SOURCE_RETENTION,
             providers = [BuildSettingInfo],
         ),
+        "_pyi_deps_to_runfiles_flag": lambda: attrb.Label(
+            default = labels.PYI_DEPS_TO_RUNFILES,
+            providers = [BuildSettingInfo],
+        ),
         # Force enabling auto exec groups, see
         # https://bazel.build/extending/auto-exec-groups#how-enable-particular-rule
         "_use_auto_exec_groups": lambda: attrb.Bool(

python/private/common.bzl

@@ -21,6 +21,7 @@ load("//python/private:py_interpreter_program.bzl", "PyInterpreterProgramInfo")
 load("//python/private:toolchain_types.bzl", "EXEC_TOOLS_TOOLCHAIN_TYPE", "LAUNCHER_MAKER_TOOLCHAIN_TYPE")
 load(":builders.bzl", "builders")
 load(":cc_helper.bzl", "cc_helper")
+load(":flags.bzl", "PyiDepsToRunfilesFlag")
 load(":py_cc_link_params_info.bzl", "PyCcLinkParamsInfo")
 load(":py_info.bzl", "PyInfo", "PyInfoBuilder")
 load(":py_internal.bzl", "py_internal")
@@ -409,10 +410,18 @@ def create_py_info(
                 if is_py_source(f):
                     py_info.transitive_sources.add(f)
                 py_info.merge_uses_shared_libraries(cc_helper.is_valid_shared_library_artifact(f))
+    propagate_pyi_deps = (
+        hasattr(ctx.attr, "_pyi_deps_to_runfiles_flag") and
+        PyiDepsToRunfilesFlag.is_enabled(ctx)
+    )
     for target in ctx.attr.pyi_deps:
         # PyInfo may not be present e.g. cc_library rules.
         if PyInfo in target or (BuiltinPyInfo != None and BuiltinPyInfo in target):
-            py_info.merge(_get_py_info(target))
+            target_py_info = _get_py_info(target)
+            if propagate_pyi_deps:
+                py_info.merge(target_py_info)
+            else:
+                py_info.merge_type_checking(target_py_info)
 
     py_info.transitive_sources.add(required_py_files)
 

python/private/common_labels.bzl

@@ -23,6 +23,7 @@ labels = struct(
     PRECOMPILE = str(Label("//python/config_settings:precompile")),
     PRECOMPILE_SOURCE_RETENTION = str(Label("//python/config_settings:precompile_source_retention")),
     PYC_COLLECTION = str(Label("//python/config_settings:pyc_collection")),
+    PYI_DEPS_TO_RUNFILES = str(Label("//python/config_settings:pyi_deps_to_runfiles")),
     PYTHON_IMPORT_ALL_REPOSITORIES = str(Label("//python/config_settings:experimental_python_import_all_repositories")),
     PYTHON_SRC = str(Label("//python/bin:python_src")),
     PYTHON_VERSION = str(Label("//python/config_settings:python_version")),

python/private/flags.bzl

@@ -108,6 +108,35 @@ ValidateTestMainFlag = FlagEnum(
     is_enabled = _ValidateTestMainFlag_is_enabled,
 )
 
+# Bazel compilation modes (e.g. from `ctx.var["COMPILATION_MODE"]`).
+# buildifier: disable=name-conventions
+CompilationMode = enum(
+    DBG = "dbg",
+    FASTBUILD = "fastbuild",
+    OPT = "opt",
+)
+
+def _PyiDepsToRunfilesFlag_is_enabled(ctx):
+    value = ctx.attr._pyi_deps_to_runfiles_flag[BuildSettingInfo].value
+    if value == PyiDepsToRunfilesFlag.AUTO:
+        # In 'opt' compilation mode, prune pyi_deps from runtime runfiles.
+        if ctx.var.get("COMPILATION_MODE") == CompilationMode.OPT:
+            return False
+        return False
+    return value == PyiDepsToRunfilesFlag.YES
+
+# Determines if pyi_deps are propagated to runtime runfiles.
+# buildifier: disable=name-conventions
+PyiDepsToRunfilesFlag = FlagEnum(
+    # Automatically decide the effective value based on compilation mode.
+    AUTO = "auto",
+    # Propagate pyi_deps into runtime runfiles (legacy behavior).
+    YES = "yes",
+    # Do not propagate pyi_deps into runtime runfiles.
+    NO = "no",
+    is_enabled = _PyiDepsToRunfilesFlag_is_enabled,
+)
+
 def _string_flag_impl(ctx):
     if ctx.attr.override:
         value = ctx.attr.override

python/private/precompile.bzl

@@ -16,7 +16,7 @@
 load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
 load(":attributes.bzl", "PrecompileAttr", "PrecompileInvalidationModeAttr", "PrecompileSourceRetentionAttr")
 load(":common.bzl", "actions_run", "is_py_source")
-load(":flags.bzl", "PrecompileFlag")
+load(":flags.bzl", "CompilationMode", "PrecompileFlag")
 load(":py_interpreter_program.bzl", "PyInterpreterProgramInfo")
 load(":toolchain_types.bzl", "EXEC_TOOLS_TOOLCHAIN_TYPE", "TARGET_TOOLCHAIN_TYPE")
 
@@ -144,7 +144,7 @@ def _precompile(ctx, src, *, use_pycache):
 
     invalidation_mode = ctx.attr.precompile_invalidation_mode
     if invalidation_mode == PrecompileInvalidationModeAttr.AUTO:
-        if ctx.var["COMPILATION_MODE"] == "opt":
+        if ctx.var.get("COMPILATION_MODE") == CompilationMode.OPT:
             invalidation_mode = PrecompileInvalidationModeAttr.UNCHECKED_HASH
         else:
             invalidation_mode = PrecompileInvalidationModeAttr.CHECKED_HASH