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.
bazelbuild · Aug 2, 2019 · 6c5f479 · 6c5f479
1 parent 04fae2a
commit 6c5f479
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -10,21 +10,37 @@ Status: This is **ALPHA** software.
 
 ## 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 @@ git_repository(
     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 @@ format in the future.
 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
+
+### Documentation
+
+All of the content under `docs/` besides the `BUILD` file is generated with
+Stardoc. To regenerate the documentation, simply run
 
-All of the content (except `BUILD`) under `docs/` is generated.  To update the
-documentation simply run this in the root of the repository:
 ```shell
 ./update_docs.sh
 ```
 
-## Updating `tools/`
+from the repository root.
+
+### 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
 
-All of the content (except `BUILD`) under `tools/` is generated.  To update the
-documentation simply run this in the root of the repository:
 ```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
@@ -34,6 +34,7 @@ bzl_library(
         "@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
@@ -45,10 +45,7 @@ pip_import(<a href="#pip_import-name">name</a>, <a href="#pip_import-requirement
 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
@@ -33,7 +33,7 @@ Example usage:
 ```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 @@ toolchain(
     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
@@ -97,11 +97,10 @@ Args:
 """
 
 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
@@ -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