8000 Update README and add py_repositories() (#218) · sfraint/rules_python@6c5f479 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6c5f479

Browse files
brandjonbrandjon
authored
Update README and add py_repositories() (bazel-contrib#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.
1 parent 04fae2a commit 6c5f479

File tree

6 files changed

+74
-33
lines changed

6 files changed

+74
-33
lines changed

‎README.md

Lines changed: 54 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,37 @@ Status: This is **ALPHA** software.
1010

1111
## Rules
1212

13-
* [pip_import](docs/python/pip.md#pip_import)
14-
* [py_library](docs/python/python.md#py_library)
15-
* [py_binary](docs/python/python.md#py_binary)
16-
* [py_test](docs/python/python.md#py_test)
13+
### Core Python rules
14+
15+
* [py_library](docs/python.md#py_library)
16+
* [py_binary](docs/python.md#py_binary)
17+
* [py_test](docs/python.md#py_test)
18+
* [py_runtime](docs/python.md#py_runtime)
19+
* [py_runtime_pair](docs/python.md#py_runtime_pair)
20+
21+
### Packaging rules
22+
23+
* [pip_import](docs/pip.md#pip_import)
1724

1825
## Overview
1926

20-
This repository provides Python rules for Bazel. Currently, support for
21-
rules that are available from Bazel core are simple aliases to that bundled
22-
functionality. On top of that, this repository provides support for installing
23-
dependencies typically managed via `pip`.
27+
This repository provides two sets of Python rules for Bazel. The core rules
28+
provide the essential library, binary, test, and toolchain rules that are
29+
expected for any language supported in Bazel. The packaging rules provide
30+
support for integration with dependencies that, in a non-Bazel environment,
31+
would typically be managed by `pip`.
32+
33+
Historically, the core rules have been bundled with Bazel itself. The Bazel
34+
team is in the process of transitioning these rules to live in
35+
bazelbuild/rules_python instead. In the meantime, all users of Python rules in
36+
Bazel should migrate their builds to load these rules and their related symbols
37+
(`PyInfo`, etc.) from `@rules_python` instead of using built-ins or
38+
`@bazel_tools//tools/python`.
2439

2540
## Setup
2641

27-
Add the following to your `WORKSPACE` file to add the external repositories:
42+
To use this repository, first modify your `WORKSPACE` file to load it and call
43+
the initialization functions as needed:
2844

2945
```python
3046
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
@@ -36,19 +52,19 @@ git_repository(
3652
commit = "{HEAD}",
3753
)
3854

39-
# Only needed for PIP support:
40-
load("@rules_python//python:pip.bzl", "pip_repositories")
55+
# This call should always be present.
56+
load("@rules_python//python:repositories.bzl", "py_repositories")
57+
py_repositories()
4158

59+
# This one is only needed if you're using the packaging rules.
60+
load("@rules_python//python:pip.bzl", "pip_repositories")
4261
pip_repositories()
4362
```
4463

45-
Then in your `BUILD` files load the python rules with:
64+
Then in your `BUILD` files, load the core rules as needed with:
4665

4766
``` python
48-
load(
49-
"@rules_python//python:defs.bzl",
50-
"py_binary", "py_library", "py_test",
51-
)
67+
load("@rules_python//python:defs.bzl", "py_binary")
5268

5369
py_binary(
5470
name = "main",
@@ -118,18 +134,34 @@ format in the future.
118134
https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras)
119135
will have a target of the extra name (in place of `pkg` above).
120136

121-
## Updating `docs/`
137+
## Development
138+
139+
### Documentation
140+
141+
All of the content under `docs/` besides the `BUILD` file is generated with
142+
Stardoc. To regenerate the documentation, simply run
122143

123-
All of the content (except `BUILD`) under `docs/` is generated. To update the
124-
documentation simply run this in the root of the repository:
125144
```shell
126145
./update_docs.sh
127146
```
128147

129-
## Updating `tools/`
148+
from the repository root.
149+
150+
### Precompiled par files
151+
152+
The `piptool.par` and `whltool.par` files underneath `tools/` are compiled
153+
versions of the Python scripts under the `rules_python/` directory. We need to
154+
check in built artifacts because they are executed during `WORKSPACE`
155+
evaluation, before Bazel itself is able to build anything from source.
156+
157+
The .par files need to be regenerated whenever their sources are updated. This
158+
can be done by running
130159

131-
All of the content (except `BUILD`) under `tools/` is generated. To update the
132-
documentation simply run this in the root of the repository:
133160
```shell
134161
./update_tools.sh
135162
```
163+
164+
from the repository root. However, since these files contain compiled code,
165+
we do not accept commits that modify them from untrusted sources. If you submit
166+
a pull request that modifies the sources and we accept the changes, we will
167+
regenerate these files for you before merging.

‎docs/BUILD

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ bzl_library(
3434
"@bazel_tools//tools/python:srcs_version.bzl",
3535
"@bazel_tools//tools/python:toolchain.bzl",
3636
"@bazel_tools//tools/python:utils.bzl",
37+
"@bazel_tools//tools/python:private/defs.bzl",
3738
],
3839
)
3940

‎docs/pip.md

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,7 @@ pip_import(<a href="#pip_import-name">name</a>, <a href="#pip_import-requirement
4545
pip_repositories()
4646
</pre>
4747

48-
Pull in dependencies needed for pulling in pip dependencies.
49-
50-
A placeholder method that will eventually pull in any dependencies
51-
needed to install pip dependencies.
48+
Pull in dependencies needed to use the packaging rules.
5249

5350

5451

‎docs/python.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Example usage:
3333
```python
3434
# In your BUILD file...
3535

36-
load("@bazel_tools//tools/python:toolchain.bzl", "py_runtime_pair")
36+
load("@rules_python//python:defs.bzl", "py_runtime_pair")
3737

3838
py_runtime(
3939
name = "my_py2_runtime",
@@ -57,7 +57,7 @@ toolchain(
5757
name = "my_toolchain",
5858
target_compatible_with = <...>,
5959
toolchain = ":my_py_runtime_pair",
60-
toolchain_type = "@bazel_tools//tools/python:toolchain_type",
60+
toolchain_type = "@rules_python//python:toolchain_type",
6161
)
6262
```
6363

‎python/pip.bzl

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,10 @@ Args:
9797
"""
9898

9999
def pip_repositories():
100-
"""Pull in dependencies needed to use the pip rules.
101-
102-
At the moment this is a placeholder, in that it does not actually pull in
103-
any dependencies. However, it does do some validation checking.
104-
"""
100+
"""Pull in dependencies needed to use the packaging rules."""
101+
# At the moment this is a placeholder, in that it does not actually pull in
102+
# any dependencies. However, it does do some validation checking.
103+
#
105104
# As a side effect of migrating our canonical workspace name from
106105
# "@io_bazel_rules_python" to "@rules_python" (#203), users who still
107106
# imported us by the old name would get a confusing error about a

‎python/repositories.bzl

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
"""This file contains macros to be called during WORKSPACE evaluation.
2+
3+
For historic reasons, pip_repositories() is defined in //python:pip.bzl.
4+
"""
5+
6+
def py_repositories():
7+
"""Pull in dependencies needed to use the core Python rules."""
8+
# At the moment this is a placeholder hook, in that it does not actually
9+
# pull in any dependencies. Users should still call this function to make
10+
# it less likely that they need to update their WORKSPACE files, in case
11+
# this function is changed in the future.
12+
pass

0 commit comments

Comments
 (0)
0