aspect_rules_py

The uv-pyproject-cases directory serves as an umbrella end-to-end (e2e) testing suite for aspect_rules_py. It is designed to provide regression coverage for various pyproject.toml, setup.py, and setup.cfg configurations that the pep517_whl/build_helper.py must correctly route.

Each case in this suite follows this pattern:

1. Pins a real PyPI package via a central uv.lock.
2. Forces the package to be resolved from its source distribution (sdist) using the [tool.uv].no-binary-package configuration.
3. Executes a smoke py_test that imports the built package. The primary assertion is that the sdist build succeeds.

aspect_rules_py is a high-performance alternative to rules_python for Bazel. It provides drop-in replacements for py_binary, py_library, and py_test designed for modern Python workflows, large-scale monorepos, and Remote Build Execution (RBE).

Key advantages include:

• Native uv integration: Uses uv.lock directly for blazing-fast, sandboxed dependency resolution.
• Hermeticity: Uses isolated Python execution (-I flag) and Bash-based launchers to prevent host environment leakage.
• Idiomatic Layouts: Uses a standard site-packages symlink tree for seamless IDE compatibility (VSCode, PyCharm).
• Cross-Platform: Supports native platform transitions for building multi-architecture OCI images and cross-compiling wheels.
• Virtual Dependencies: Allows swapping implementations at the binary level or upgrading dependencies independently within a monorepo.

Virtual dependencies allow a py_library to declare a dependency on a package name without requiring a direct Bazel label. The actual Bazel target for that package is resolved later in the py_binary or py_test that consumes the library using the resolutions attribute.

# In a library
py_library(
    name = "greet_lib",
    srcs = ["greet.py"],
    virtual_deps = ["cowsay"],
)

# In a binary consuming the library
py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [":greet_lib"],
    resolutions = {
        "cowsay": "@pypi//cowsay",
    },
)

Free-threaded mode (PEP 803) is available for Python 3.13 and newer. It is a separate axis from the standard build_config.

How to enable:

1. Globally: Use the build setting --@aspect_rules_py//py/private/interpreter:freethreaded=true during bazel build.
2. Per-target: Set the freethreaded = True attribute on py_binary or other Python targets.

Important constraints:

• Free-threaded interpreters cannot load standard (GIL) native extensions. You must ensure all native dependencies use the t ABI (e.g., cp313t).
• When inheriting a mode, the default is None, which follows the caller's mode.

# Global enable
bazel build --@aspect_rules_py//py/private/interpreter:freethreaded=true //...

# Per-target enable
py_binary(
    name = "free_threaded_app",
    srcs = ["app.py"],
    python_version = "3.13",
    freethreaded = True,
)

The PyRuntimeInfo provider contains information about a Python runtime, as returned by the py_runtime rule. It describes how a Python interpreter is accessed and how it should be bootstrapped to run targets within Bazel.

A Python runtime can be one of two types:

1. Platform runtime: Accesses a system-installed interpreter at a known absolute filesystem path (interpreter_path).
2. In-build runtime: Points to a File that acts as the interpreter (interpreter). This can be a prebuilt binary, a checked-in interpreter, or one built from source.

Warning: PyRuntimeInfo is an unstable public API. It may change frequently and has weaker compatibility guarantees.

load("@aspect_rules_py//py:defs.bzl", "PyRuntimeInfo")

The stage2_bootstrap_template is a Python code template that runs under the desired interpreter. It orchestrates the call to the program's actual main code and is responsible for affecting the runtime state (like sys.path or enabling coverage) so that the program works correctly under Bazel.

Available substitutions during expansion:

• %main%: Runfiles-relative path to the program's actual main file (.py or .pyc).
• %coverage_tool%: Runfiles-relative path to the coverage library's entry point (empty string if disabled).
• %import_all%: String True if all repositories in runfiles should be added to sys.path, otherwise False.
• %imports%: Colon-delimited string of runfiles-relative paths to add to sys.path.
• %target%: The name of the target.
• %workspace_name%: The name of the workspace.

The zip_main_template is a Python code template used as the top-level __main__.py file for a zip file (per PEP 441). This allows the zip file to be executed directly via a Python interpreter.

Note: py_binary-generated zip files are self-executing and skip calling __main__.py.

Available substitutions during expansion:

• %stage2_bootstrap%: A runfiles-relative string to the stage 2 bootstrap file.
• %python_binary%: Path to the target Python interpreter (absolute, runfiles-relative, or PATH name).
• %workspace_name%: The name of the workspace for the built target.