trigger: model_decision description: rules_python-specific Bzlmod, PyPI, and rule usage invariants

rules_python Bzlmod & Rule Invariants

Unified @pypi Hub & pip.dep() Declarations (MODULE.bazel)

  • Declare pip.dep(name = "<pkg>") on the non-dev pip extension in MODULE.bazel (with "pypi" in use_repo(pip, "pypi", ...)) for every @pypi//<pkg> target referenced by non-test rules, macros, or BUILD files under python/** (directly or via alias).
  • Why: pip.dep() registers abstract PyPI package targets in the unified @pypi hub so downstream Bzlmod consumers do not fail during loading or analysis when <pkg> is absent from their pip.parse() lockfiles. Package names in pip.dep(name = "...") are normalized (hyphens and underscores map to the same name).

Minimum Supported Bazel Version

  • //:version.bzl defines MINIMUM_BAZEL_VERSION. Do not add compatibility logic, feature guards, or comments for older Bazel versions.
  • When guarding a feature added after MINIMUM_BAZEL_VERSION, verify and comment the exact Bazel version that introduced it.

Internal Labels & Helpers

  • Toolchain Type Labels: Define toolchain type constants in //python/private/toolchain_types:toolchain_types.bzl and targets in //python/private/toolchain_types:BUILD.bazel.
  • render Helpers (//python/private:text_util.bzl): Use render.* (render.string, render.toolchain, render.call, render.list) instead of repr() for Starlark calls; use json.encode_indent() for data constants.
  • @bazel_tools bzl_library Deps: Use "//python/private:bazel_tools" in bzl_library deps for files loading @bazel_tools//....

WORKSPACE & Bzlmod Parity

  • Extend Existing Rules Over Adding Parallel Rules: When bringing a Bzlmod tag attribute (such as pip.parse(uv_lock = ...)) to an existing WORKSPACE rule or macro (pip_parse / pip_repository), add the attribute to the existing rule and reuse its pipeline (parse_requirements -> requirements.bzl.tmpl.workspace -> whl_library) instead of creating a separate rule or duplicating Bzlmod's hub/spoke repo graph.
  • Extract Shared Pure Helpers from Bzlmod Extensions: When WORKSPACE code needs pure functions or data defined in a Bzlmod extension file (such as default_platforms() in extension.bzl), move them into a standalone Bzlmod-agnostic .bzl file instead of duplicating definitions.
  • Preserve Vendored requirements.bzl Portability in WORKSPACE: pip_repository outputs (requirements.bzl) may be vendored and evaluated on any host platform. Only emit direct Bazel downloader attributes (urls, integrity, filename) into requirements.bzl when a package resolves to the same distribution across all target platforms (len({src.url: None for src in whl.srcs}) == 1); otherwise append --hash=<digest> flags to the requirement line so pip selects the host wheel while enforcing lockfile hashes.
  • For new WORKSPACE macros without an existing rule counterpart, match Bzlmod extension defaults, tag schemas (e.g., configure list of dicts), and single-hub multi-version structure, sharing configuration and hub logic in common private .bzl helpers.
  • When WORKSPACE repos depend on downloaded manifests, split setup into a manifest repo rule (writes unfiltered DIST_MANIFESTS and a bound registration macro to dist_manifest.bzl) and a registration macro (filters platforms, instantiates tool repos, and registers the hub; also accepts explicit urls without a manifest).