feat: enable pyproject.toml as single source of truth for Python version by janwinkler1 · Pull Request #3514 · bazel-contrib/rules_python

janwinkler1 · 2026-01-14T16:48:32Z

Enables using pyproject.toml as single source of truth for Python version via
python.defaults(pyproject_toml=...) and pip.default(pyproject_toml=...).
The version is read from the requires-python field and used as the default toolchain version, so anything relying on the default (f.e. py_binary/py_test, pip.parse, compile_pip_requirements) picks it up with no explicit python_version in BUILD files:

# MODULE.bazel
python.defaults(pyproject_toml = "//:pyproject.toml")
pip.default(pyproject_toml = "//:pyproject.toml")

# BUILD.bazel (version comes from default, no need to restate it)
compile_pip_requirements(
    name="requirements",
    requirements_txt = "requirements.txt"
 )

Changes:

Added pyproject_toml attribute to python.defaults() and pip.default(), reading the version from requires-python
Parses pyproject.toml with the pure-Starlark @toml.bzl (toml.decode) (no host Python interpreter required)
Auto-registers a toolchain for the default version if no explicit python.toolchain() call exists
Made python_version optional in pip.parse() when using pip.default(pyproject_toml=...)
Precedence order: ENV > pyproject_toml > python_version_file > python_version

Requirements:

requires-python = "==X.Y.Z" format in pyproject.toml

Thanks to @aignas and @rickeylev for the review and design guidance

gemini-code-assist · 2026-01-14T16:49:08Z

Summary of Changes

Hello @janwinkler1, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Python ecosystem's integration by introducing pyproject.toml as a primary source for defining Python versions within Bazel projects. It streamlines configuration by allowing python.defaults() and pip.default() to automatically infer the Python version from pyproject.toml, reducing redundancy and potential for discrepancies. Additionally, it improves the developer experience by making config_settings optional in pip.default() and providing a dedicated repository for accessing the pyproject.toml-defined Python version in BUILD files.

Highlights

Centralized Python Version Management: Introduced the pyproject_toml attribute to python.defaults() and pip.default(), enabling the Python version to be read directly from pyproject.toml's requires-python field. This establishes pyproject.toml as a single source of truth for Python versions across the project.
BUILD File Integration for Python Version: A new repository rule, python_version_from_pyproject, has been created. This rule generates a version.bzl file that exports the PYTHON_VERSION constant, allowing BUILD files to import and use the Python version defined in pyproject.toml without hardcoding it.
Simplified pip.default() Configuration: The config_settings attribute in pip.default() is now optional. Previously, users had to pass an empty list (config_settings = []) even when no platform-specific configurations were needed, but now it can be omitted entirely.
Flexible pip.parse() Usage: The python_version attribute in pip.parse() is now optional when pip.default(pyproject_toml=...) is used, as the version can be automatically inferred from the pyproject.toml file specified in the defaults.
Dedicated Version Extraction Logic: The logic for parsing and extracting the Python version from pyproject.toml has been moved into a shared Python script (pyproject_version_extractor.py), improving maintainability and reusability of the version parsing functionality.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a significant and valuable feature by enabling pyproject.toml as a single source of truth for Python versions in both python.defaults() and pip.default(). This enhancement greatly improves consistency and maintainability across projects. The implementation includes a new repository rule (pyproject_version_repo) and utility functions to extract and validate the Python version from pyproject.toml. Additionally, config_settings in pip.default() has been made optional, which is a good usability improvement. The changes are well-tested with dedicated integration and priority tests, ensuring the new functionality works as expected and respects the defined priority order for Python version resolution. The code is clean, well-documented, and adheres to best practices.

aignas · 2026-01-19T03:09:09Z

Hey, thank you for the contribution.

In general I am +1 on having the python version read from pyproject.toml but I have concerns on depending on Python for doing that. It is trivial to do it in Python but we have a layering violation, because we need to use some python interpreter before the interpreters are setup and that would mean that we would have to use the Python interpreter from the system.

Creates python_version_from_pyproject repository for BUILD file usage:
load("@python_version_from_pyproject//:version.bzl", "PYTHON_VERSION")
compile_pip_requirements(python_version = PYTHON_VERSION, ...)

What is the benefit of this? If we are setting the default version through the pyproject.toml interpreter, the python_version should not need to be set anymore in this way.

Makes config_settings optional in pip.default(). Previously, users had
to pass an empty list (config_settings = []) even when not using platform-specific
configurations. Now it can be omitted entirely when not needed.

+1 on this change. If you'd like to merge it earlier than we decide on the various pyproject.toml processing specific details, please submit a separate PR.

Added pyproject_toml attribute to python.defaults() and pip.default()

LGTM, but I am wondering if this is the simplest possible interface. We could instead reuse, continue using the machinery that is used by .python-version and do detection based on extension. If it is called a pyproject.toml, then we know for sure what it can contain.

Reads Python version from requires-python field (must be ==X.Y.Z format)

Do we need to restrict the user to ==X.Y.Z? Should we also support X.Y? What about >=X.Y? We do have python version parsing reimplemented in Starlark, so we process this information statically.

Made python_version optional in pip.parse() when using pip.default(pyproject_toml=...)

Is the idea to set the default value for //python/config_settings:python_version from pyproject.toml? If so, should we do this change in 2 steps - make the pip.parse python_version optional and fallback to the default version?

rickeylev · 2026-01-29T03:08:39Z

I, too, am supportive of this.

layering violation, using python to parse it

I'm not worried about that. We should just pick a python runtime to use for repo-phase logic that rules_python uses. It simplifies us being able to assume what python is being used and its capabilities. There's also the config bzlmod extension we could use to give some ability to customize what python we use during the repo phase.

what syntax of requires-python should we support, how do they work

I'd say lets just go with what the author is willing to contribute. If someone later wants >, then they can send a PR.

janwinkler1 · 2026-02-05T07:04:44Z

hi @aignas and @rickeylev, thank you for your comments! i am currently taking a vacation, will address your comments nexy week! cheerio

rickeylev

Core logic is OK, but some of the impl details and tests need to change

rickeylev · 2026-02-08T04:49:21Z

            continue

        for tag in mod.tags.default:
+            pyproject_toml = getattr(tag, "pyproject_toml", None)


The pyproject tag will always be present, so this can use normal . for accessing.

Kept getattr because the existing unit tests in tests/pypi/extension/ create mock tag structs that don't include pyproject_toml. Using tag.pyproject_toml breaks test_simple. Happy to update the test mocks instead if preferred.

+1 to update the mocks. In there setting it to None is good enough. There is a function where that would be easy to do.

rickeylev · 2026-02-08T04:50:54Z

    ),
    "config_settings": attr.label_list(
-        mandatory = True,
+        mandatory = False,


I think a recent PR fixed this?

@rickeylev do you happen to know which one? i havent found it.. could also split this out as a separate PR if you'd prefer it merged independently.

Yeah, in main it is True.

rickeylev · 2026-02-08T04:51:18Z

+    ),
+    "pyproject_toml": attr.label(
+        mandatory = False,
+        allow_single_file = True,


allow_single_file can be omitted. It has no meaning for repo/bzlmod rules

rickeylev · 2026-02-08T04:53:21Z

+The version must be specified as `==X.Y.Z` (exact version with full semver).
+This is designed to work with dependency management tools like Renovate.
+
+:::{versionadded} 1.8.0


Change to VERSION_NEXT_FEATURE instead of 1.8.0

rickeylev · 2026-02-08T04:54:20Z

        ),
        "python_version": attr.string(
-            mandatory = True,
+            mandatory = False,


update python_version attr doc to indicate the other option

add e.g.

:::{seealso} The {obj}`pyproject_toml` attribute for getting the version from a project file. :::

rickeylev · 2026-02-08T05:00:25Z

Ah, this is a good opportunity to add a toml2json tool, there's another pending PR that needs it, too.

Copy the toml2json tool from https://github.com/bazel-contrib/rules_python/pull/3557/changes and use it in this PR for parsing the pyproject.toml file.

Copy tools/toml2json; move it to tools/private/toml2json

Copy its tests.

Use convert_uv_lock_to_json in python/private/pypi/uv_lock.bzl as inspiration for creating a pyproject_to_json bzl function. Notably, invoke the helper toml2json script using the utility functions it uses. These ensure the script is executed correctly/safely.

rickeylev · 2026-02-08T05:05:09Z

            )
-        if default_python_version_file:
+
+        # Priority order: pyproject_toml > python_version_file > python_version_env > python_version


This logic needs to be partially reverted, as its changing behavior.

The ENV attribute has highest precedence (this allows overriding on the command line), followed by version file. I'm not sure if .python-version or pyproject.toml should have higher precedence; I'm think pyproject.toml should be higher, though.

rickeylev · 2026-02-08T05:06:25Z

+    # Check if pyproject_toml was specified in defaults
+    # If so, register a toolchain for it


The diff is hiding a lot of the content -- is this new logic specific to pyproject? It would make sense that this occurs for whatever default is used, not just if pyproject is.

I removed the pyproject-specific auto-registration. _create_toolchain_attr_structs now receives the already-computed default_python_version and auto-registers a toolchain for it if no explicit python.toolchain() exists for that version. This is generic and works for any default source (pyproject, version file, env, static string). WDYT?

rickeylev · 2026-02-08T05:06:51Z

+When specified, reads the `requires-python` field from pyproject.toml.
+The version must be specified as `==X.Y.Z` (exact version with full semver).
+
+:::{versionadded} 1.8.0


Specify VERSION_NEXT_FEATURE

rickeylev · 2026-02-08T05:09:52Z

These tests are OK, but they're integration tests. We only add integration tests when absolutely necessary because we have a limited number of jobs we can run (and we're near that limit already).

I think there are some more unittest-style things with pieces mocked out.

Otherwise, we'll just have to leave the code paths as untested 🤷

janwinkler1 · 2026-02-16T14:01:14Z

@aignas:

Do we need to restrict the user to ==X.Y.Z? Should we also support X.Y? What about >=X.Y? We do have python version parsing reimplemented in Starlark, so we process this information statically.

i decided to start with ==X.Y.Z only as the simplest useful subset. the usecase i had in mind was mainly that tools like renovate can easily update it with exactly pinned versions. IMO Support for >=, X.Y, could be added in follow-up PRs. WDYT?

Is the idea to set the default value for //python/config_settings:python_version from pyproject.toml? If so, should we do this change in 2 steps - make the pip.parse python_version optional and fallback to the default version?

python_version is now optional in pip.parse() and falls back to the version from pip.default(pyproject_toml=...). If neither is set, it fails with a clear error message.

janwinkler1 · 2026-04-23T11:16:44Z

any update on this @rickeylev ?

aignas · 2026-02-25T09:20:56Z

            continue

        for tag in mod.tags.default:
+            pyproject_toml = getattr(tag, "pyproject_toml", None)


+1 to update the mocks. In there setting it to None is good enough. There is a function where that would be easy to do.

aignas · 2026-02-25T09:24:15Z

    ),
    "config_settings": attr.label_list(
-        mandatory = True,
+        mandatory = False,


Yeah, in main it is True.

aignas · 2026-02-25T09:26:12Z

+            default = "//tools/private/toml2json:toml2json.py",
+        ),
+        # TODO: Set a proper default once interpreter bootstrapping is resolved.
+        # See https://github.com/bazel-contrib/rules_python/pull/3557


What does this mean? Should we have some better default here?

janwinkler1 · 2026-06-29T12:19:34Z

@aignas any update here?

aignas

Sorry it took a while to get to this.

Leaving some comments as rules_python has moved ahead a little since you created this PR.

My thinking is that the following structure would make sense:

Create a helper that reads pyproject.toml and parses the contents.
Pass pyproject.toml to the python.bzl to parse and detect the default here. This will take care of everything during runtime. Since the DEFAULT_PYTHON_VERSION can be retrieved, no need for the extra repository. Also this plays well with only the root module being able to set the python version.
Pass pyproject.toml and get the version for the hub_builder and friends. Again, no need to create a separate repo. In the future we can use the requires_python to support dynamic selection/registration. This is especially useful since we have introduced uv.lock support.

Just to reiterate, I think this feature is really good and a welcome addition to rules_python. Thank you for your work!

aignas · 2026-06-30T09:09:24Z

+    result = module_ctx.execute([
+        "python3",
+        str(toml2json),
+        str(pyproject_path),
+    ])


We no longer need this, we can use a pure starlark library to parse toml into JSON.

aignas · 2026-06-30T09:10:38Z

+
+    return bare_version
+
+def read_pyproject_version(module_ctx, pyproject_label, logger = None):


Maybe it would be good to have read_pyproject function instead of this. Then it could return a struct with important values:

struct( version = "3.13.9" )

aignas · 2026-06-30T09:11:12Z

+    bare_version = requires_python[2:].strip()
+
+    # Validate X.Y.Z format
+    parts = bare_version.split(".")


please use the python/private/version.bzl to parse and normalize the version here. It will ensure that the code fails in the right way.

aignas · 2026-06-30T09:14:16Z

+        The bare version string (e.g. "3.13.9").
+    """
+    if not requires_python.startswith("=="):
+        fail("requires-python must use '==' for exact version, got: {}".format(requires_python))


We could in theory just take the string instead of the version. Then we can use something like:
evaluate("{python_version}{requires_python}".format(...))

That will save us from a refactor in the future. In my experience it is best to read files and return requires_python as is and then delegate the logic of this to some other file.

just tbc, do you want me to:

just structure read_pyproject to return the raw requires_python string and keep the current effective behavior (single exact version for now) e.g. leaving full specifier support as a future change?

actually wire up evaluate(...) for arbitrary specifiers as part of this PR?

my read is the the first but happy to go further if you'd prefer

aignas · 2026-06-30T09:15:59Z

  from a python-build-standalone manifest file using
  `python.override(add_runtime_manifest_urls = ..., runtime_manifest_sha = ...)`.
+* (pip,python) Added `pyproject_toml` attribute to `pip.default()` and `python.defaults()`
+  to read Python version from pyproject.toml `requires-python` field (must be `==X.Y.Z` format).


todo: a reminder to switch to news/3514.added.md file for this snippet.

aignas · 2026-06-30T09:17:46Z

+
+Example:
+```python
+    load("@python_version_from_pyproject//:version.bzl", "PYTHON_VERSION")


not sure we need this, we could just set the default version in the extension.
Then the following should be using the default version:

compile_pip_requirements( name = "requirements", requirements_txt = "requirements.txt", )

Or am I missing something?

janwinkler1 · 2026-06-30T10:11:56Z

@aignas

Sorry it took a while to get to this.

dont worry about the timing, thank you for your thorough review

I think this feature is really good and a welcome addition to rules_python

thank you!

…oml2json

janwinkler1 · 2026-06-30T12:04:21Z

@aignas, i restructured per your suggestions.

i dropped the repo rule (version is now the default so compile_pip_requirements picks it up automatically)
swapped toml2json for pure-Starlark @toml.bzl
read_pyproject() now returns a struct parsed via version.bzl
changelog moved to a news fragment

on requires_python: i went with the raw string plus version.bzl (current exact-version behavior), leaving evaluate()-based specifier support as the future step you mentioned.

(checks fail with the same macOS jobs as on main)

janwinkler1 requested review from aignas, groodt and rickeylev as code owners January 14, 2026 16:48

gemini-code-assist Bot reviewed Jan 14, 2026

View reviewed changes

janwinkler1 marked this pull request as draft January 15, 2026 07:05

janwinkler1 force-pushed the pyproject-toml-handling branch 2 times, most recently from 958106b to 1a1fef2 Compare January 15, 2026 07:46

janwinkler1 marked this pull request as ready for review January 15, 2026 07:57

janwinkler1 force-pushed the pyproject-toml-handling branch from 1a1fef2 to bd73882 Compare January 15, 2026 08:07

rickeylev reviewed Feb 8, 2026

View reviewed changes

janwinkler1 force-pushed the pyproject-toml-handling branch 2 times, most recently from 653998b to e5ffe1e Compare February 16, 2026 13:20

janwinkler1 requested a review from rickeylev February 16, 2026 14:09

aignas reviewed Apr 24, 2026

View reviewed changes

janwinkler1 force-pushed the pyproject-toml-handling branch 3 times, most recently from 4002e56 to edaeacc Compare April 28, 2026 06:12

janwinkler1 requested a review from aignas April 28, 2026 07:08

janwinkler1 force-pushed the pyproject-toml-handling branch 3 times, most recently from 4b8c563 to 5482aec Compare June 30, 2026 09:13

aignas reviewed Jun 30, 2026

View reviewed changes

feat: enable pyproject.toml as single source of truth for Python version

1dd2d63

janwinkler1 force-pushed the pyproject-toml-handling branch from 5482aec to 1dd2d63 Compare June 30, 2026 09:31

Address review: use toml.decode and version.bzl, drop repo rule and t…

af9a093

…oml2json

janwinkler1 force-pushed the pyproject-toml-handling branch from c864558 to af9a093 Compare June 30, 2026 11:27

janwinkler1 requested a review from aignas June 30, 2026 13:18

		# Check if pyproject_toml was specified in defaults
		# If so, register a toolchain for it


		return bare_version

		def read_pyproject_version(module_ctx, pyproject_label, logger = None):

Uh oh!

Uh oh!

Conversation

janwinkler1 commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot commented Jan 14, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

aignas commented Jan 19, 2026

Uh oh!

rickeylev commented Jan 29, 2026

Uh oh!

janwinkler1 commented Feb 5, 2026

Uh oh!

rickeylev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janwinkler1 Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janwinkler1 commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

janwinkler1 commented Apr 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janwinkler1 commented Jun 29, 2026

Uh oh!

aignas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

janwinkler1 commented Jan 14, 2026 •

edited

Loading

janwinkler1 Feb 16, 2026 •

edited

Loading

janwinkler1 commented Feb 16, 2026 •

edited

Loading

aignas left a comment •

edited

Loading

janwinkler1 commented Jun 30, 2026 •

edited

Loading

janwinkler1 commented Jun 30, 2026 •

edited

Loading