| # Python Rules for Bazel | |
| [](https://buildkite.com/bazel/rules-python-python) | |
| ## Overview | |
| This repository is the home of the core Python rules -- `py_library`, | |
| `py_binary`, `py_test`, and related symbols that provide the basis for Python | |
| support in Bazel. It also contains package installation rules for integrating | |
| with PyPI and other indices. | |
| Documentation for rules_python is at <https://rules-python.readthedocs.io> and in the | |
| [Bazel Build Encyclopedia](https://docs.bazel.build/versions/master/be/python.html). | |
| Examples live in the [examples](examples) directory. | |
| The core rules are stable. Their implementation is subject to Bazel's | |
| [backward compatibility policy](https://docs.bazel.build/versions/master/backward-compatibility.html). | |
| This repository aims to follow [semantic versioning](https://semver.org). | |
| The Bazel community maintains this repository. Neither Google nor the Bazel team | |
| provides support for the code. However, this repository is part of the test | |
| suite used to vet new Bazel releases. See [How to contribute](CONTRIBUTING.md) | |
| page for information on our development workflow. | |
| ## Design | |
| * Supported OSes - as per our supported platform policy, we strive for support | |
| on all of the platforms that we have CI for. Some platforms do not have the | |
| same backwards compatibility guarantees, but we hope the community can step in | |
| where needed to make the support more robust. | |
| * `requirements.txt` is how users have been defining dependencies for a long | |
| time. We support this to support legacy usecases or package managers that we | |
| don't support directly. Any additional information that we need will be | |
| retrieved from the SimpleAPI during the `bzlmod` extension evaluation phase. | |
| Then it will be written to the `MODULE.bazel.lock` file for future reuse. We | |
| have plans to support `uv.lock` file directly. `uv` is recommended for | |
| generating a fully locked `requirements.txt` file and we do provide a rule for | |
| it. | |
| * The `py_binary`, `py_test` rules should scale to large monorepos and we work | |
| hard to minimize the work done during analysis and build phase. What is more, | |
| the space requirements for should be minimal, so we strive to use symlinks | |
| rather than extracting wheels at build time. This means that for different | |
| configurations of the same build, we are not extracting the wheel multiple | |
| times thus scaling better over the time. From `2.0` onwards we are creating a | |
| virtual env for each target by creating an actual minimal virtual environment | |
| using symlinks. We plan on creating the traditional `site-packages` layout in | |
| the future by default. | |
| * Support for standards - we strive to first implement any standards needed | |
| within `rules_python` and this has resulted in a few PEPs supported within | |
| pure starlark - PEP440, PEP509. | |
| Common misconceptions: | |
| * `rules_python` has to keep backwards compatibility with `google3`. Whilst this | |
| might have been true in the past, `rules_python` is an open source project and | |
| any compatibility needs should come from the community - we have no | |
| requirement to keep this compatibility and are allowed to make our decisions. | |
| However, we do want to keep backwards compatibility as long as possible to not | |
| upset users with never ending migrations. | |
| * `rules_python` is not caching pip downloads. With 2.0, we use Bazel's | |
| downloader by default and rely on bazel to provide the repository caching | |
| mechanisms. This means that for simpler setups this should result in | |
| transparent and scalable caching with the most recent bazel versions unless | |
| there are issues in the bazel itself. | |
| ## Documentation | |
| For detailed documentation, see <https://rules-python.readthedocs.io> | |
| ## Bzlmod support | |
| See [Bzlmod support](BZLMOD_SUPPORT.md) for more details. |