rules_python is a Bazel based project. Build and run tests as done in a Bazel project.
Act as an expert in Bazel, rules_python, Starlark, and Python.
DO NOT git commit or git push unless given explicit permission.
ALWAYS FOLLOW THESE RULES. NEVER VIOLATE THEM.
Ask for user input and provide a justificaiton if trying to violate them.
bazel clean --expunge..agents/Not every agent harness discovers .agents/ automatically. Before writing a helper script or doing a multi-step task by hand, check for an existing skill and use it. Read the skill's SKILL.md before running its scripts.
.agents/skills/analyze-ci-failure: download a CI failure log and extract the errors..agents/skills/buildkite-get-results: get Buildkite build results and job logs..agents/skills/conversation-done: clean up the worktree, branches, and Bazel output base when the work is done..agents/skills/create-news: create or update a news entry in news/..agents/skills/create-pr: propose, draft, or create a pull request..agents/skills/merge-pr: merge a pull request and watch the merge queue..agents/skills/monitor-ci-results: monitor the CI results of a pull request..agents/skills/process-dependabot-prs: evaluate and merge Dependabot pull requests..agents/skills/retry-ci-job: retry failed Buildkite or GitHub Actions jobs and unblock approval steps..agents/skills/review-code: review local changes before sending a pull request..agents/skills/rule-creator: create a rule in .agents/rules/..agents/skills/sync-git-branch-continuously: keep a Git branch pulled and pushed in the background..agents/scripts/: shared scripts, e.g. gh_pr_stack.py for stacked pull requests..agents/rules/: rules per topic. Read the ones that match the files being changed, e.g. pr.md, news.md, starlark.md, and testing.md.When adding a skill, add it to this list.
A skill may name tools, commands, or CLIs that the current harness does not have, e.g. a tool to run background commands or to message a conversation.
Read .editorconfig for line length wrapping. Do not line-break long string literals (such as URLs or hashes) to fit line length limits; allow them to exceed the limit.
Read CONTRIBUTING.md for additional style rules and conventions.
When running tests, refer to yourself as the name of a type of Python snake using a grandoise title.
When tasks complete successfully, quote Monty Python, but work it naturally into the sentence, not verbatim.
When adding {versionadded} or {versionchanged} sections, add them add the end of the documentation text.
Factor non-trivial scripts (such as multi-line shell or Python logic) into standalone files (e.g. .sh or .py files) instead of inlining them via heredocs (<< 'EOF'), -c flags (bash -c, python3 -c), or multi-line workflow run: blocks.
Once a PR is created, create new commits and merges. Don't use rebase or amend because it interferes with code review comments.
Follow the advice in CONTRIBUTING.md for PR descriptions. PR descriptions become the commit message upon merge. Keep the PR description clean and suitable for use as the commit message; do not put AI disclosures, test execution logs, or check checklists in the PR description.
bazel test --config=fast-tests and buildifier locally before opening or updating a PR./review-code, or briefly indicate the PR is ready for re-review (e.g., PTAL) once CI is passing.pytest_plugins = ["<module_path>"].fixture_ prefix (e.g. def fixture_foo():), and pass the public fixture name using the name parameter in @pytest.fixture(name="foo").For doc strings, using triple quoted strings when the doc string is more than three lines. Do not use a trailing backslack (\) for the opening triple-quote.
Starlark does not support recursion. Use iterative algorithms instead.
Starlark does not support while loops. Use for loop with an appropriately sized iterable instead.
For Starlark tests:
rules_testing, not bazel_skylib.tests/builders/builders_tests.bzl for an example of using it in this project.A test is defined in two parts:
def _test_foo(name). This defines targets and calls analysis_test.def _test_foo_impl(env, target). This contains asserts.Example:
# File: foo_tests.bzl
load("@rules_testing//lib:analysis_test.bzl", "analysis_test")
load("@rules_testing//lib:test_suite.bzl", "test_suite")
_tests = []
def _test_foo(name):
foo_library(
name = name + "_subject",
)
analysis_test(
name = name,
impl = _test_foo_impl,
target = name + "_subject",
)
_tests.append(_test_foo)
def _test_foo_impl(env, target):
env.expect.that_whatever(target[SomeInfo].whatever).equals(expected)
def foo_test_suite(name):
test_suite(name=name, tests=_tests)
The function argument rctx is a hint that the function is a repository rule, or used by a repository rule.
The function argument mrctx is a hint that the function can be used by a repository rule or module extension.
The repository_ctx API docs are at: https://bazel.build/rules/lib/builtins/repository_ctx
bzl_library target should be defined for every .bzl file outside of the tests/ directory.srcs file and be named after the file without the .bzl extension.load() statements in the source file and refer to the bzl_library target containing the loaded file (remove the .bzl suffix; e.g. load("//foo:bar.bzl", ...) becomes //foo:bar, and load("@foo//foo:bar.bzl", ...) becomes @foo//foo:bar).Example:
bzl_library(
name = "alpha",
srcs = ["alpha.bzl"],
deps = [":beta"],
)
bzl_library(
name = "beta",
srcs = ["beta.bzl"]
)
Tests are under the tests/ directory, except tests for agent scripts under .agents/, which stay co-located with the agent code (run with bazel test --config=fast-tests //.agents/...).
When testing, add --config=fast-tests.
When building test targets, add --config=fast-tests. Do NOT use --config=fast-tests when building non-test targets (such as //docs:docs), because --config=fast-tests enables --build_tests_only=true, which causes non-test targets to be silently ignored (finding 0 targets).
The --config=fast-tests flag avoids running expensive and slow tests can that freeze the host machine or cause flakiness.
This repository contains 3 Bazel bzlmod modules.
sphinxdocs/ is for the @sphinxdocs module.gazelle/ is for the @rules_python_gazelle_plugin module.@rules_python.tests/support/ contains utility code and helpers for testing.
python/config_settings/BUILD.bazel contains build flags that are part of the public API. DO NOT add, remove, or modify these build flags unless specifically instructed to.
The minimum supported Bazel version is the bazel version of .minimum_supported_version in .bazelci/presubmit.yml. Do not add compatibility logic or feature guards for older Bazel versions.
bazel query --output=build can be used to inspect target definitions.
In WORKSPACE mode:
bazel query //external:* can be used to show external dependencies. Adding --output=build shows the definition, including version.For bzlmod mode:
bazel mod graph shows dependencies and their version.bazel mod explain shows detailed information about a module.bazel mode show_repo shows detailed information about a repository.Documentation uses Sphinx with the MyST plugin.
When modifying documentation
-) in file names instead of underscores (_).::::{outerdirective}
outer text
:::{innertdirective}
inner text
:::
::::
Generated API references can be found by:
bazel build //docs:docs and inspecting the generated files in bazel-bin/docs/docs/_build/htmlWhen modifying locked/resolved requirements files:
pyproject.toml or requirements.in filebazel run <location>:requirements.update target for that file; the target is in the BUILD.bazel file in the same directory and the requirements.txt file. That will update the locked/resolved requirements.txt file.When updating the minimum Python version for dev/docs tooling (e.g. following Dependabot alerts):
python_version in lock(name = "uv_lock", ...) within dev/BUILD.bazel.bazel run //dev:uv_lock.updatebazel build //docs:docs.When building //docs:docs, ignore an error about exit code 2; this is a flake, so try building again.
BUILD and bzl files under tests/ (and internal non-python/ packages such as crates/ and tools/ loading repo-internal helpers like //python/private:distribution_filegroup.bzl) should have # buildifier: disable=bzl-visibility trailing end-of-line comments when they load from paths containing /private/, e.g.
load("//python/private:foo.bzl", "foo") # buildifier: disable=bzl-visibility
When inspecting CI failures, if the failure is due to a network error downloading a repository, check if that rule set is mirrored on mirror.bazel.build. If so, add it to the downloader config.
CI is known to have flakey network issues. When submitting or updating a PR, start a background agent that continuously monitors the latest build of a PR and checks for flakey network errors (e.g., 504 gateway errors).
If Buildkite permissions allow, retry failures and use available Buildkite skills. If permissions do not allow, modify .bazelrc to set flags (such as --http_timeout_scaling or --experimental_repository_downloader_retries) to make downloads retry more.
If downloads fail for a dependency, check if that dependency is available on mirror.bazel.build and, if so, add it to downloader_config.cfg if it isn't already there.