1# Python Rules for Bazel 2 3`rules_python` is the home for 4 major components with varying maturity levels. 4 5:::{topic} Core rules 6 7The core Python rules -- `py_library`, `py_binary`, `py_test`, 8`py_proto_library`, and related symbols that provide the basis for Python 9support in Bazel. 10 11When using Bazel 6 (or earlier), the core rules are bundled into the Bazel binary, and the symbols 12in this repository are simple aliases. On Bazel 7 and above `rules_python` uses 13a separate Starlark implementation, 14see {ref}`Migrating from the Bundled Rules` below. 15 16Once rules_python 1.0 is released, they will follow 17[semantic versioning](https://semver.org) and the breaking change policy 18outlined in the [support](support) page. 19 20::: 21 22:::{topic} PyPI integration 23 24Package installation rules for integrating with PyPI and other SimpleAPI 25compatible indexes. 26 27These rules work and can be used in production, but the cross-platform building 28that supports pulling PyPI dependencies for a target platform that is different 29from the host platform is still in beta and the APIs that are subject to potential 30change are marked as `experimental`. 31 32::: 33 34:::{topic} Sphinxdocs 35 36`sphinxdocs` rules allow users to generate documentation using Sphinx powered by Bazel, with additional functionality for documenting 37Starlark and Bazel code. 38 39The functionality is exposed because other projects find it useful, but 40it is available as is and **the semantic versioning and 41compatibility policy used by `rules_python` does not apply**. 42 43::: 44 45:::{topic} Gazelle plugin 46 47`gazelle` plugin for generating `BUILD.bazel` files based on Python source 48code. 49 50This is available as is and the semantic versioning used by `rules_python` does 51not apply. 52 53::: 54 55The Bazel community maintains this repository. Neither Google nor the Bazel 56team provides support for the code. However, this repository is part of the 57test suite used to vet new Bazel releases. See {gh-path}`How to contribute 58<CONTRIBUTING.md>` for information on our development workflow. 59 60## Examples 61 62This documentation is an example of `sphinxdocs` rules and the rest of the 63components have examples in the {gh-path}`examples` directory. 64 65## Migrating from the bundled rules 66 67The core rules are currently available in Bazel as built-in symbols, but this 68form is deprecated. Instead, you should depend on rules_python in your 69`WORKSPACE` or `MODULE.bazel` file and load the Python rules from 70`@rules_python//python:defs.bzl` or load paths described in the API documentation. 71 72A [buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md) 73fix is available to automatically migrate `BUILD` and `.bzl` files to add the 74appropriate `load()` statements and rewrite uses of `native.py_*`. 75 76```sh 77# Also consider using the -r flag to modify an entire workspace. 78buildifier --lint=fix --warnings=native-py <files> 79``` 80 81Currently, the `WORKSPACE` file needs to be updated manually as per 82[Getting started](getting-started). 83 84Note that Starlark-defined bundled symbols underneath 85`@bazel_tools//tools/python` are also deprecated. These are not yet rewritten 86by buildifier. 87 88## Migrating to bzlmod 89 90See {gh-path}`Bzlmod support <BZLMOD_SUPPORT.md>` for any behaviour differences between 91`bzlmod` and `WORKSPACE`. 92 93 94```{toctree} 95:hidden: 96self 97getting-started 98pypi-dependencies 99Toolchains <toolchains> 100pip 101coverage 102precompiling 103gazelle 104Contributing <contributing> 105support 106Changelog <changelog> 107api/index 108environment-variables 109Sphinxdocs <sphinxdocs/index> 110glossary 111genindex 112``` 113