Merge branch 'main' into patch-2

Author: rickeylev

CHANGELOG.md

@@ -47,6 +47,27 @@ BEGIN_UNRELEASED_TEMPLATE
 END_UNRELEASED_TEMPLATE
 -->
 
+{#v0-0-0}
+## Unreleased
+
+[0.0.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.0.0
+
+{#v0-0-0-removed}
+### Removed
+* Nothing removed.
+
+{#v0-0-0-changed}
+### Changed
+* (binaries/tests) The `PYTHONBREAKPOINT` environment variable is automatically inherited
+
+{#v0-0-0-fixed}
+### Fixed
+* Nothing fixed.
+
+{#v0-0-0-added}
+### Added
+* (binaries/tests) {obj}`--debugger`: allows specifying an extra dependency
+  to add to binaries/tests for custom debuggers.
 
 {#v1-8-0}
 ## [1.8.0] - 2025-12-19
@@ -2065,4 +2086,4 @@ Breaking changes:
 * (pip) Create all_data_requirements alias
 * Expose Python C headers through the toolchain.
 
-[0.24.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.24.0
+[0.24.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.24.0

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

@@ -45,6 +45,27 @@ This flag replaces the Bazel builtin `--build_python_zip` flag.
 :::
 ::::
 
+::::{bzl:flag} debugger
+A target for providing a custom debugger dependency.
+
+This flag is roughly equivalent to putting a target in `deps`. It allows
+injecting a dependency into executables (`py_binary`, `py_test`) without having
+to modify their deps. The expectation is it points to a target that provides an
+alternative debugger (pudb, winpdb, debugpy, etc).
+
+* Must provide {obj}`PyInfo`.
+* This dependency is only used for the target config, i.e. build tools don't
+  have it added.
+
+:::{note}
+Setting this flag adds the debugger dependency, but doesn't automatically set
+`PYTHONBREAKPOINT` to change `breakpoint()` behavior.
+:::
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+::::
+
 ::::{bzl:flag} experimental_python_import_all_repositories
 Controls whether repository directories are added to the import path.
 

docs/howto/debuggers.md

@@ -0,0 +1,66 @@
+:::{default-domain} bzl
+:::
+
+# How to integrate a debugger
+
+This guide explains how to use the {obj}`--debugger` flag to integrate a debugger
+with your Python applications built with `rules_python`.
+
+## Basic Usage
+
+The {obj}`--debugger` flag allows you to inject an extra dependency into `py_test`
+and `py_binary` targets so that they have a custom debugger available at
+runtime. The flag is roughly equivalent to manually adding it to `deps` of
+the target under test.
+
+To use the debugger, you typically provide the `--debugger` flag to your `bazel run` command.
+
+Example command line:
+
+```bash
+bazel run --@rules_python//python/config_settings:debugger=@pypi//pudb \
+    //path/to:my_python_binary
+```
+
+This will launch the Python program with the `@pypi//pudb` dependency added.
+
+The exact behavior (e.g., waiting for attachment, breaking at the first line)
+depends on the specific debugger and its configuration.
+
+:::{note}
+The specified target must be in the requirements.txt file used with
+`pip.parse()` to make it available to Bazel.
+:::
+
+## Python `PYTHONBREAKPOINT` Environment Variable
+
+For more fine-grained control over debugging, especially for programmatic breakpoints,
+you can leverage the Python built-in `breakpoint()` function and the
+`PYTHONBREAKPOINT` environment variable.
+
+The `breakpoint()` built-in function, available since Python 3.7,
+can be called anywhere in your code to invoke a debugger. The `PYTHONBREAKPOINT`
+environment variable can be set to specify which debugger to use.
+
+For example, to use `pdb` (the Python Debugger) when `breakpoint()` is called:
+
+```bash
+PYTHONBREAKPOINT=pudb.set_trace bazel run \
+    --@rules_python//python/config_settings:debugger=@pypi//pudb \
+    //path/to:my_python_binary
+```
+
+For more details on `PYTHONBREAKPOINT`, refer to the [Python documentation](https://docs.python.org/3/library/functions.html#breakpoint).
+
+## Setting a default debugger
+
+By adding settings to your user or project `.bazelrc` files, you can have
+these settings automatically added to your bazel invocations. e.g.
+
+```
+common --@rules_python//python/config_settings:debugger=@pypi//pudb
+common --test_env=PYTHONBREAKPOINT=pudb.set_trace
+```
+
+Note that `--test_env` isn't strictly necessary. The `py_test` and `py_binary`
+rules will respect the `PYTHONBREAKPOINT` environment variable in your shell.

python/config_settings/BUILD.bazel

@@ -102,6 +102,12 @@ rp_string_flag(
     visibility = ["//visibility:public"],
 )
 
+label_flag(
+    name = "debugger",
+    build_setting_default = "//python/private:empty",
+    visibility = ["//visibility:public"],
+)
+
 # For some reason, @platforms//os:windows can't be directly used
 # in the select() for the flag. But it can be used when put behind
 # a config_setting().

python/private/BUILD.bazel

@@ -16,6 +16,7 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@bazel_skylib//rules:common_settings.bzl", "bool_setting")
 load("//python:py_binary.bzl", "py_binary")
 load("//python:py_library.bzl", "py_library")
+load(":bazel_config_mode.bzl", "bazel_config_mode")
 load(":print_toolchain_checksums.bzl", "print_toolchains_checksums")
 load(":py_exec_tools_toolchain.bzl", "current_interpreter_executable")
 load(":sentinel.bzl", "sentinel")
@@ -27,6 +28,8 @@ package(
 
 licenses(["notice"])
 
+exports_files(["runtime_env_toolchain_interpreter.sh"])
+
 filegroup(
     name = "distribution",
     srcs = glob(["**"]) + [
@@ -810,6 +813,23 @@ config_setting(
     },
 )
 
+config_setting(
+    name = "is_bazel_config_mode_target",
+    flag_values = {
+        "//python/private:bazel_config_mode": "target",
+    },
+)
+
+alias(
+    name = "debugger_if_target_config",
+    actual = select({
+        ":is_bazel_config_mode_target": "//python/config_settings:debugger",
+        "//conditions:default": "//python/private:empty",
+    }),
+)
+
+bazel_config_mode(name = "bazel_config_mode")
+
 # This should only be set by analysis tests to expose additional metadata to
 # aid testing, so a setting instead of a flag.
 bool_setting(

python/private/bazel_config_mode.bzl

@@ -0,0 +1,12 @@
+"""Flag to tell if exec or target mode is active."""
+
+load(":py_internal.bzl", "py_internal")
+
+def _bazel_config_mode_impl(ctx):
+    return [config_common.FeatureFlagInfo(
+        value = "exec" if py_internal.is_tool_configuration(ctx) else "target",
+    )]
+
+bazel_config_mode = rule(
+    implementation = _bazel_config_mode_impl,
+)

python/private/common.bzl

@@ -43,116 +43,36 @@ PYTHON_FILE_EXTENSIONS = [
 
 def create_binary_semantics_struct(
         *,
-        create_executable,
-        get_cc_details_for_binary,
         get_central_uncachable_version_file,
-        get_coverage_deps,
-        get_debugger_deps,
-        get_extra_common_runfiles_for_binary,
-        get_extra_providers,
-        get_extra_write_build_data_env,
-        get_interpreter_path,
-        get_imports,
         get_native_deps_dso_name,
-        get_native_deps_user_link_flags,
-        get_stamp_flag,
-        maybe_precompile,
         should_build_native_deps_dso,
-        should_create_init_files,
         should_include_build_data):
     """Helper to ensure a semantics struct has all necessary fields.
 
     Call this instead of a raw call to `struct(...)`; it'll help ensure all
     the necessary functions are being correctly provided.
 
     Args:
-        create_executable: Callable; creates a binary's executable output. See
-            py_executable.bzl#py_executable_base_impl for details.
-        get_cc_details_for_binary: Callable that returns a `CcDetails` struct; see
-            `create_cc_detail_struct`.
         get_central_uncachable_version_file: Callable that returns an optional
             Artifact; this artifact is special: it is never cached and is a copy
             of `ctx.version_file`; see py_builtins.copy_without_caching
-        get_coverage_deps: Callable that returns a list of Targets for making
-            coverage work; only called if coverage is enabled.
-        get_debugger_deps: Callable that returns a list of Targets that provide
-            custom debugger support; only called for target-configuration.
-        get_extra_common_runfiles_for_binary: Callable that returns a runfiles
-            object of extra runfiles a binary should include.
-        get_extra_providers: Callable that returns extra providers; see
-            py_executable.bzl#_create_providers for details.
-        get_extra_write_build_data_env: Callable that returns a dict[str, str]
-            of additional environment variable to pass to build data generation.
-        get_interpreter_path: Callable that returns an optional string, which is
-            the path to the Python interpreter to use for running the binary.
-        get_imports: Callable that returns a list of the target's import
-            paths (from the `imports` attribute, so just the target's own import
-            path strings, not from dependencies).
         get_native_deps_dso_name: Callable that returns a string, which is the
             basename (with extension) of the native deps DSO library.
-        get_native_deps_user_link_flags: Callable that returns a list of strings,
-            which are any extra linker flags to pass onto the native deps DSO
-            linking action.
-        get_stamp_flag: Callable that returns bool of if the --stamp flag was
-            enabled or not.
-        maybe_precompile: Callable that may optional precompile the input `.py`
-            sources and returns the full set of desired outputs derived from
-            the source files (e.g., both py and pyc, only one of them, etc).
         should_build_native_deps_dso: Callable that returns bool; True if
             building a native deps DSO is supported, False if not.
-        should_create_init_files: Callable that returns bool; True if
-            `__init__.py` files should be generated, False if not.
         should_include_build_data: Callable that returns bool; True if
             build data should be generated, False if not.
     Returns:
         A "BinarySemantics" struct.
     """
     return struct(
         # keep-sorted
-        create_executable = create_executable,
-        get_cc_details_for_binary = get_cc_details_for_binary,
         get_central_uncachable_version_file = get_central_uncachable_version_file,
-        get_coverage_deps = get_coverage_deps,
-        get_debugger_deps = get_debugger_deps,
-        get_extra_common_runfiles_for_binary = get_extra_common_runfiles_for_binary,
-        get_extra_providers = get_extra_providers,
-        get_extra_write_build_data_env = get_extra_write_build_data_env,
-        get_imports = get_imports,
-        get_interpreter_path = get_interpreter_path,
         get_native_deps_dso_name = get_native_deps_dso_name,
-        get_native_deps_user_link_flags = get_native_deps_user_link_flags,
-        get_stamp_flag = get_stamp_flag,
-        maybe_precompile = maybe_precompile,
         should_build_native_deps_dso = should_build_native_deps_dso,
-        should_create_init_files = should_create_init_files,
         should_include_build_data = should_include_build_data,
     )
 
-def create_library_semantics_struct(
-        *,
-        get_cc_info_for_library,
-        get_imports,
-        maybe_precompile):
-    """Create a `LibrarySemantics` struct.
-
-    Call this instead of a raw call to `struct(...)`; it'll help ensure all
-    the necessary functions are being correctly provided.
-
-    Args:
-        get_cc_info_for_library: Callable that returns a CcInfo for the library;
-            see py_library_impl for arg details.
-        get_imports: Callable; see create_binary_semantics_struct.
-        maybe_precompile: Callable; see create_binary_semantics_struct.
-    Returns:
-        a `LibrarySemantics` struct.
-    """
-    return struct(
-        # keep sorted
-        get_cc_info_for_library = get_cc_info_for_library,
-        get_imports = get_imports,
-        maybe_precompile = maybe_precompile,
-    )
-
 def create_cc_details_struct(
         *,
         cc_info_for_propagating,
@@ -241,12 +161,8 @@ def collect_cc_info(ctx, extra_deps = []):
     Returns:
         CcInfo provider of merged information.
     """
-    deps = ctx.attr.deps
-    if extra_deps:
-        deps = list(deps)
-        deps.extend(extra_deps)
     cc_infos = []
-    for dep in deps:
+    for dep in collect_deps(ctx, extra_deps):
         if CcInfo in dep:
             cc_infos.append(dep[CcInfo])
 
@@ -255,29 +171,28 @@ def collect_cc_info(ctx, extra_deps = []):
 
     return cc_common.merge_cc_infos(cc_infos = cc_infos)
 
-def collect_imports(ctx, semantics):
+def collect_imports(ctx, extra_deps = []):
     """Collect the direct and transitive `imports` strings.
 
     Args:
         ctx: {type}`ctx` the current target ctx
-        semantics: semantics object for fetching direct imports.
+        extra_deps: list of Target to also collect imports from.
 
     Returns:
         {type}`depset[str]` of import paths
     """
+
     transitive = []
-    for dep in ctx.attr.deps:
+    for dep in collect_deps(ctx, extra_deps):
         if PyInfo in dep:
             transitive.append(dep[PyInfo].imports)
         if BuiltinPyInfo != None and BuiltinPyInfo in dep:
             transitive.append(dep[BuiltinPyInfo].imports)
-    return depset(direct = semantics.get_imports(ctx), transitive = transitive)
+    return depset(direct = get_imports(ctx), transitive = transitive)
 
 def get_imports(ctx):
     """Gets the imports from a rule's `imports` attribute.
 
-    See create_binary_semantics_struct for details about this function.
-
     Args:
         ctx: Rule ctx.
 
@@ -562,3 +477,19 @@ def runfiles_root_path(ctx, short_path):
         return short_path[3:]
     else:
         return "{}/{}".format(ctx.workspace_name, short_path)
+
+def collect_deps(ctx, extra_deps = []):
+    """Collect the dependencies from the rule's context.
+
+    Args:
+        ctx: rule ctx
+        extra_deps: list of Target to also collect dependencies from.
+
+    Returns:
+        list of Target
+    """
+    deps = ctx.attr.deps
+    if extra_deps:
+        deps = list(deps)
+        deps.extend(extra_deps)
+    return deps

python/private/common_labels.bzl

@@ -8,6 +8,7 @@ labels = struct(
     ADD_SRCS_TO_RUNFILES = str(Label("//python/config_settings:add_srcs_to_runfiles")),
     BOOTSTRAP_IMPL = str(Label("//python/config_settings:bootstrap_impl")),
     BUILD_PYTHON_ZIP = str(Label("//python/config_settings:build_python_zip")),
+    DEBUGGER = str(Label("//python/config_settings:debugger")),
     EXEC_TOOLS_TOOLCHAIN = str(Label("//python/config_settings:exec_tools_toolchain")),
     PIP_ENV_MARKER_CONFIG = str(Label("//python/config_settings:pip_env_marker_config")),
     NONE = str(Label("//python:none")),