Update README and add py_repositories() (#218)
Update the README file to explain the difference between the core Python rules
and the packaging rules. Add the py_repositories() hook and recommend that
users add it to their WORKSPACE files.
Background on the py_repositories() hook: I don't know what this might be
useful for at the moment, but I found pip_repositories() to be helpful when I
added a deprecation message for renaming the workspace to @rules_python. So
it's probably a good idea to have this just in case.
Also fix and regenerate docs.
diff --git a/README.md b/README.md
index f777f79..e708e07 100644
--- a/README.md
+++ b/README.md
@@ -10,21 +10,37 @@
## Rules
-* [pip_import](docs/python/pip.md#pip_import)
-* [py_library](docs/python/python.md#py_library)
-* [py_binary](docs/python/python.md#py_binary)
-* [py_test](docs/python/python.md#py_test)
+### Core Python rules
+
+* [py_library](docs/python.md#py_library)
+* [py_binary](docs/python.md#py_binary)
+* [py_test](docs/python.md#py_test)
+* [py_runtime](docs/python.md#py_runtime)
+* [py_runtime_pair](docs/python.md#py_runtime_pair)
+
+### Packaging rules
+
+* [pip_import](docs/pip.md#pip_import)
## Overview
-This repository provides Python rules for Bazel. Currently, support for
-rules that are available from Bazel core are simple aliases to that bundled
-functionality. On top of that, this repository provides support for installing
-dependencies typically managed via `pip`.
+This repository provides two sets of Python rules for Bazel. The core rules
+provide the essential library, binary, test, and toolchain rules that are
+expected for any language supported in Bazel. The packaging rules provide
+support for integration with dependencies that, in a non-Bazel environment,
+would typically be managed by `pip`.
+
+Historically, the core rules have been bundled with Bazel itself. The Bazel
+team is in the process of transitioning these rules to live in
+bazelbuild/rules_python instead. In the meantime, all users of Python rules in
+Bazel should migrate their builds to load these rules and their related symbols
+(`PyInfo`, etc.) from `@rules_python` instead of using built-ins or
+`@bazel_tools//tools/python`.
## Setup
-Add the following to your `WORKSPACE` file to add the external repositories:
+To use this repository, first modify your `WORKSPACE` file to load it and call
+the initialization functions as needed:
```python
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
@@ -36,19 +52,19 @@
commit = "{HEAD}",
)
-# Only needed for PIP support:
-load("@rules_python//python:pip.bzl", "pip_repositories")
+# This call should always be present.
+load("@rules_python//python:repositories.bzl", "py_repositories")
+py_repositories()
+# This one is only needed if you're using the packaging rules.
+load("@rules_python//python:pip.bzl", "pip_repositories")
pip_repositories()
```
-Then in your `BUILD` files load the python rules with:
+Then in your `BUILD` files, load the core rules as needed with:
``` python
-load(
- "@rules_python//python:defs.bzl",
- "py_binary", "py_library", "py_test",
-)
+load("@rules_python//python:defs.bzl", "py_binary")
py_binary(
name = "main",
@@ -118,18 +134,34 @@
https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras)
will have a target of the extra name (in place of `pkg` above).
-## Updating `docs/`
+## Development
-All of the content (except `BUILD`) under `docs/` is generated. To update the
-documentation simply run this in the root of the repository:
+### Documentation
+
+All of the content under `docs/` besides the `BUILD` file is generated with
+Stardoc. To regenerate the documentation, simply run
+
```shell
./update_docs.sh
```
-## Updating `tools/`
+from the repository root.
-All of the content (except `BUILD`) under `tools/` is generated. To update the
-documentation simply run this in the root of the repository:
+### Precompiled par files
+
+The `piptool.par` and `whltool.par` files underneath `tools/` are compiled
+versions of the Python scripts under the `rules_python/` directory. We need to
+check in built artifacts because they are executed during `WORKSPACE`
+evaluation, before Bazel itself is able to build anything from source.
+
+The .par files need to be regenerated whenever their sources are updated. This
+can be done by running
+
```shell
./update_tools.sh
```
+
+from the repository root. However, since these files contain compiled code,
+we do not accept commits that modify them from untrusted sources. If you submit
+a pull request that modifies the sources and we accept the changes, we will
+regenerate these files for you before merging.
diff --git a/docs/BUILD b/docs/BUILD
index 52f86c0..70b6a5c 100644
--- a/docs/BUILD
+++ b/docs/BUILD
@@ -34,6 +34,7 @@
"@bazel_tools//tools/python:srcs_version.bzl",
"@bazel_tools//tools/python:toolchain.bzl",
"@bazel_tools//tools/python:utils.bzl",
+ "@bazel_tools//tools/python:private/defs.bzl",
],
)
diff --git a/docs/pip.md b/docs/pip.md
index 6218a9e..312fc08 100755
--- a/docs/pip.md
+++ b/docs/pip.md
@@ -45,10 +45,7 @@
pip_repositories()
</pre>
-Pull in dependencies needed for pulling in pip dependencies.
-
-A placeholder method that will eventually pull in any dependencies
-needed to install pip dependencies.
+Pull in dependencies needed to use the packaging rules.
diff --git a/docs/python.md b/docs/python.md
index 87455c9..78f3d33 100755
--- a/docs/python.md
+++ b/docs/python.md
@@ -33,7 +33,7 @@
```python
# In your BUILD file...
-load("@bazel_tools//tools/python:toolchain.bzl", "py_runtime_pair")
+load("@rules_python//python:defs.bzl", "py_runtime_pair")
py_runtime(
name = "my_py2_runtime",
@@ -57,7 +57,7 @@
name = "my_toolchain",
target_compatible_with = <...>,
toolchain = ":my_py_runtime_pair",
- toolchain_type = "@bazel_tools//tools/python:toolchain_type",
+ toolchain_type = "@rules_python//python:toolchain_type",
)
```
diff --git a/python/pip.bzl b/python/pip.bzl
index 2449ee7..b69eb93 100644
--- a/python/pip.bzl
+++ b/python/pip.bzl
@@ -97,11 +97,10 @@
"""
def pip_repositories():
- """Pull in dependencies needed to use the pip rules.
-
- At the moment this is a placeholder, in that it does not actually pull in
- any dependencies. However, it does do some validation checking.
- """
+ """Pull in dependencies needed to use the packaging rules."""
+ # At the moment this is a placeholder, in that it does not actually pull in
+ # any dependencies. However, it does do some validation checking.
+ #
# As a side effect of migrating our canonical workspace name from
# "@io_bazel_rules_python" to "@rules_python" (#203), users who still
# imported us by the old name would get a confusing error about a
diff --git a/python/repositories.bzl b/python/repositories.bzl
new file mode 100644
index 0000000..997bdea
--- /dev/null
+++ b/python/repositories.bzl
@@ -0,0 +1,12 @@
+"""This file contains macros to be called during WORKSPACE evaluation.
+
+For historic reasons, pip_repositories() is defined in //python:pip.bzl.
+"""
+
+def py_repositories():
+ """Pull in dependencies needed to use the core Python rules."""
+ # At the moment this is a placeholder hook, in that it does not actually
+ # pull in any dependencies. Users should still call this function to make
+ # it less likely that they need to update their WORKSPACE files, in case
+ # this function is changed in the future.
+ pass
