Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit b111e56

Browse filesBrowse files
Jonathon Belottialexeagle
Jonathon Belotti
and
alexeagle
authored
Update docstrings for packaging rules/macros (bazel-contrib#535)
* update docstrings for packaging rules/macros Co-authored-by: Alex Eagle <eagle@post.harvard.edu>
1 parent 5bb1b58 commit b111e56
Copy full SHA for b111e56

File tree

3 files changed

+70
-36
lines changed
Filter options

3 files changed

+70
-36
lines changed

‎docs/pip.md

Copy file name to clipboardExpand all lines: docs/pip.md
+28-17Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,13 @@ compile_pip_requirements(<a href="#compile_pip_requirements-name">name</a>, <a h
99
<a href="#compile_pip_requirements-kwargs">kwargs</a>)
1010
</pre>
1111

12-
Macro creating targets for running pip-compile
12+
Generates targets for managing pip dependencies with pip-compile.
1313

14-
Produce a filegroup by default, named "[name]" which can be included in the data
14+
By default this rules generates a filegroup named "[name]" which can be included in the data
1515
of some other compile_pip_requirements rule that references these requirements
16-
(e.g. with `-r ../other/requirements.txt`)
16+
(e.g. with `-r ../other/requirements.txt`).
1717

18-
Produce two targets for checking pip-compile:
18+
It also generates two targets for running pip-compile:
1919

2020
- validate with `bazel test <name>_test`
2121
- update with `bazel run <name>.update`
@@ -43,7 +43,7 @@ Produce two targets for checking pip-compile:
4343
pip_import(<a href="#pip_import-kwargs">kwargs</a>)
4444
</pre>
4545

46-
46+
Rule for installing packages listed in a requirements file.
4747

4848
**PARAMETERS**
4949

@@ -61,17 +61,19 @@ pip_import(<a href="#pip_import-kwargs">kwargs</a>)
6161
pip_install(<a href="#pip_install-requirements">requirements</a>, <a href="#pip_install-name">name</a>, <a href="#pip_install-kwargs">kwargs</a>)
6262
</pre>
6363

64-
Imports a `requirements.txt` file and generates a new `requirements.bzl` file.
64+
Accepts a `requirements.txt` file and installs the dependencies listed within.
65+
66+
Those dependencies become available in a generated `requirements.bzl` file.
6567

66-
This is used via the `WORKSPACE` pattern:
68+
This macro runs a repository rule that invokes `pip`. In your WORKSPACE file:
6769

6870
```python
6971
pip_install(
7072
requirements = ":requirements.txt",
7173
)
7274
```
7375

74-
You can then reference imported dependencies from your `BUILD` file with:
76+
You can then reference installed dependencies from a `BUILD` file with:
7577

7678
```python
7779
load("@pip//:requirements.bzl", "requirement")
@@ -86,9 +88,16 @@ py_library(
8688
)
8789
```
8890

89-
In addition to the `requirement` macro, which is used to access the generated `py_library`
90-
target generated from a package's wheel, The generated `requirements.bzl` file contains
91-
functionality for exposing [entry points][whl_ep] as `py_binary` targets as well.
91+
> Note that this convenience comes with a cost.
92+
> Analysis of any BUILD file which loads the requirements helper in this way will
93+
> cause an eager-fetch of all the pip dependencies,
94+
> even if no python targets are requested to be built.
95+
> In a multi-language repo, this may cause developers to fetch dependencies they don't need,
96+
> so consider using the long form for dependencies if this happens.
97+
98+
In addition to the `requirement` macro, which is used to access the `py_library`
99+
target generated from a package's wheel, the generated `requirements.bzl` file contains
100+
functionality for exposing [entry points][whl_ep] as `py_binary` targets.
92101

93102
[whl_ep]: https://packaging.python.org/specifications/entry-points/
94103

@@ -104,7 +113,7 @@ alias(
104113
)
105114
```
106115

107-
Note that for packages who's name and script are the same, only the name of the package
116+
Note that for packages whose name and script are the same, only the name of the package
108117
is needed when calling the `entry_point` macro.
109118

110119
```python
@@ -135,9 +144,11 @@ alias(
135144
pip_parse(<a href="#pip_parse-requirements_lock">requirements_lock</a>, <a href="#pip_parse-name">name</a>, <a href="#pip_parse-kwargs">kwargs</a>)
136145
</pre>
137146

138-
Imports a locked/compiled requirements file and generates a new `requirements.bzl` file.
147+
Accepts a locked/compiled requirements file and installs the dependencies listed within.
139148

140-
This is used via the `WORKSPACE` pattern:
149+
Those dependencies become available in a generated `requirements.bzl` file.
150+
151+
This macro runs a repository rule that invokes `pip`. In your WORKSPACE file:
141152

142153
```python
143154
load("@rules_python//python:pip.bzl", "pip_parse")
@@ -152,7 +163,7 @@ load("@pip_deps//:requirements.bzl", "install_deps")
152163
install_deps()
153164
```
154165

155-
You can then reference imported dependencies from your `BUILD` file with:
166+
You can then reference installed dependencies from a `BUILD` file with:
156167

157168
```python
158169
load("@pip_deps//:requirements.bzl", "requirement")
@@ -186,7 +197,7 @@ alias(
186197
)
187198
```
188199

189-
Note that for packages who's name and script are the same, only the name of the package
200+
Note that for packages whose name and script are the same, only the name of the package
190201
is needed when calling the `entry_point` macro.
191202

192203
```python
@@ -217,7 +228,7 @@ alias(
217228
pip_repositories()
218229
</pre>
219230

220-
231+
Obsolete macro to pull in dependencies needed to use the pip_import rule.
221232

222233
**PARAMETERS**
223234

‎python/pip.bzl

Copy file name to clipboardExpand all lines: python/pip.bzl
+38-14Lines changed: 38 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -20,17 +20,19 @@ load("//python/pip_install:requirements.bzl", _compile_pip_requirements = "compi
2020
compile_pip_requirements = _compile_pip_requirements
2121

2222
def pip_install(requirements, name = "pip", **kwargs):
23-
"""Imports a `requirements.txt` file and generates a new `requirements.bzl` file.
23+
"""Accepts a `requirements.txt` file and installs the dependencies listed within.
2424
25-
This is used via the `WORKSPACE` pattern:
25+
Those dependencies become available in a generated `requirements.bzl` file.
26+
27+
This macro runs a repository rule that invokes `pip`. In your WORKSPACE file:
2628
2729
```python
2830
pip_install(
2931
requirements = ":requirements.txt",
3032
)
3133
```
3234
33-
You can then reference imported dependencies from your `BUILD` file with:
35+
You can then reference installed dependencies from a `BUILD` file with:
3436
3537
```python
3638
load("@pip//:requirements.bzl", "requirement")
@@ -45,9 +47,16 @@ def pip_install(requirements, name = "pip", **kwargs):
4547
)
4648
```
4749
48-
In addition to the `requirement` macro, which is used to access the generated `py_library`
49-
target generated from a package's wheel, The generated `requirements.bzl` file contains
50-
functionality for exposing [entry points][whl_ep] as `py_binary` targets as well.
50+
> Note that this convenience comes with a cost.
51+
> Analysis of any BUILD file which loads the requirements helper in this way will
52+
> cause an eager-fetch of all the pip dependencies,
53+
> even if no python targets are requested to be built.
54+
> In a multi-language repo, this may cause developers to fetch dependencies they don't need,
55+
> so consider using the long form for dependencies if this happens.
56+
57+
In addition to the `requirement` macro, which is used to access the `py_library`
58+
target generated from a package's wheel, the generated `requirements.bzl` file contains
59+
functionality for exposing [entry points][whl_ep] as `py_binary` targets.
5160
5261
[whl_ep]: https://packaging.python.org/specifications/entry-points/
5362
@@ -63,7 +72,7 @@ def pip_install(requirements, name = "pip", **kwargs):
6372
)
6473
```
6574
66-
Note that for packages who's name and script are the same, only the name of the package
75+
Note that for packages whose name and script are the same, only the name of the package
6776
is needed when calling the `entry_point` macro.
6877
6978
```python
@@ -76,9 +85,9 @@ def pip_install(requirements, name = "pip", **kwargs):
7685
```
7786
7887
Args:
79-
requirements: A 'requirements.txt' pip requirements file.
80-
name: A unique name for the created external repository (default 'pip').
81-
**kwargs: Keyword arguments passed directly to the `pip_repository` repository rule.
88+
requirements (Label): A 'requirements.txt' pip requirements file.
89+
name (str, optional): A unique name for the created external repository (default 'pip').
90+
**kwargs (dict): Keyword arguments passed directly to the `pip_repository` repository rule.
8291
"""
8392

8493
# Just in case our dependencies weren't already fetched
@@ -91,9 +100,11 @@ def pip_install(requirements, name = "pip", **kwargs):
91100
)
92101

93102
def pip_parse(requirements_lock, name = "pip_parsed_deps", **kwargs):
94-
"""Imports a locked/compiled requirements file and generates a new `requirements.bzl` file.
103+
"""Accepts a locked/compiled requirements file and installs the dependencies listed within.
104+
105+
Those dependencies become available in a generated `requirements.bzl` file.
95106
96-
This is used via the `WORKSPACE` pattern:
107+
This macro runs a repository rule that invokes `pip`. In your WORKSPACE file:
97108
98109
```python
99110
load("@rules_python//python:pip.bzl", "pip_parse")
@@ -108,7 +119,7 @@ def pip_parse(requirements_lock, name = "pip_parsed_deps", **kwargs):
108119
install_deps()
109120
```
110121
111-
You can then reference imported dependencies from your `BUILD` file with:
122+
You can then reference installed dependencies from a `BUILD` file with:
112123
113124
```python
114125
load("@pip_deps//:requirements.bzl", "requirement")
@@ -142,7 +153,7 @@ def pip_parse(requirements_lock, name = "pip_parsed_deps", **kwargs):
142153
)
143154
```
144155
145-
Note that for packages who's name and script are the same, only the name of the package
156+
Note that for packages whose name and script are the same, only the name of the package
146157
is needed when calling the `entry_point` macro.
147158
148159
```python
@@ -176,10 +187,23 @@ def pip_parse(requirements_lock, name = "pip_parsed_deps", **kwargs):
176187
)
177188

178189
def pip_repositories():
190+
"""
191+
Obsolete macro to pull in dependencies needed to use the pip_import rule.
192+
193+
Deprecated:
194+
the pip_repositories rule is obsolete. It is not used by pip_install.
195+
"""
196+
179197
# buildifier: disable=print
180198
print("DEPRECATED: the pip_repositories rule has been replaced with pip_install, please see rules_python 0.1 release notes")
181199

182200
def pip_import(**kwargs):
201+
"""
202+
Rule for installing packages listed in a requirements file.
203+
204+
Deprecated:
205+
the pip_import rule has been replaced with pip_install.
206+
"""
183207
fail("=" * 79 + """\n
184208
pip_import has been replaced with pip_install, please see the rules_python 0.1 release notes.
185209
To continue using it, you can load from "@rules_python//python/legacy_pip_import:pip.bzl"

‎python/pip_install/requirements.bzl

Copy file name to clipboardExpand all lines: python/pip_install/requirements.bzl
+4-5Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,13 @@ def compile_pip_requirements(
1111
requirements_txt = None,
1212
tags = None,
1313
**kwargs):
14-
"""
15-
Macro creating targets for running pip-compile
14+
"""Generates targets for managing pip dependencies with pip-compile.
1615
17-
Produce a filegroup by default, named "[name]" which can be included in the data
16+
By default this rules generates a filegroup named "[name]" which can be included in the data
1817
of some other compile_pip_requirements rule that references these requirements
19-
(e.g. with `-r ../other/requirements.txt`)
18+
(e.g. with `-r ../other/requirements.txt`).
2019
21-
Produce two targets for checking pip-compile:
20+
It also generates two targets for running pip-compile:
2221
2322
- validate with `bazel test <name>_test`
2423
- update with `bazel run <name>.update`

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.