rules_python_external: fill missing docstrings (#358)
add missing docstrings for rules_python_external
also remove unused attr on pip_repository repo rule
diff --git a/experimental/rules_python_external/defs.bzl b/experimental/rules_python_external/defs.bzl
index 1e64c3c..0d21b91 100644
--- a/experimental/rules_python_external/defs.bzl
+++ b/experimental/rules_python_external/defs.bzl
@@ -91,16 +91,94 @@
pip using the same interpreter as your toolchain. If set, takes precedence over
python_interpreter.
"""),
- "quiet": attr.bool(default = True),
- "requirements": attr.label(allow_single_file = True, mandatory = True),
+ "quiet": attr.bool(
+ default = True,
+ doc = "If True, suppress printing stdout and stderr output to the terminal.",
+ ),
+ "requirements": attr.label(
+ allow_single_file = True,
+ mandatory = True,
+ doc = "A 'requirements.txt' pip requirements file.",
+ ),
# 600 is documented as default here: https://docs.bazel.build/versions/master/skylark/lib/repository_ctx.html#execute
- "timeout": attr.int(default = 600),
- "wheel_env": attr.string_dict(),
+ "timeout": attr.int(
+ default = 600,
+ doc = "Timeout (in seconds) on the rule's execution duration.",
+ ),
},
implementation = _pip_repository_impl,
+ doc = """A rule for importing `requirements.txt` dependencies into Bazel.
+
+This rule imports a `requirements.txt` file and generates a new
+`requirements.bzl` file. This is used via the `WORKSPACE` pattern:
+
+```python
+pip_repository(
+ name = "foo",
+ requirements = ":requirements.txt",
+)
+```
+
+You can then reference imported dependencies from your `BUILD` file with:
+
+```python
+load("@foo//:requirements.bzl", "requirement")
+py_library(
+ name = "bar",
+ ...
+ deps = [
+ "//my/other:dep",
+ requirement("requests"),
+ requirement("numpy"),
+ ],
+)
+```
+
+Or alternatively:
+```python
+load("@foo//:requirements.bzl", "all_requirements")
+py_binary(
+ name = "baz",
+ ...
+ deps = [
+ ":foo",
+ ] + all_requirements,
+)
+```
+""",
)
def pip_install(requirements, name = DEFAULT_REPOSITORY_NAME, **kwargs):
+ """Imports a `requirements.txt` file and generates a new `requirements.bzl` file.
+
+ This is used via the `WORKSPACE` pattern:
+
+ ```python
+ pip_install(
+ requirements = ":requirements.txt",
+ )
+ ```
+
+ You can then reference imported dependencies from your `BUILD` file with:
+
+ ```python
+ load("@pip//:requirements.bzl", "requirement")
+ py_library(
+ name = "bar",
+ ...
+ deps = [
+ "//my/other:dep",
+ requirement("requests"),
+ requirement("numpy"),
+ ],
+ )
+ ```
+
+ Args:
+ requirements: A 'requirements.txt' pip requirements file.
+ name: A unique name for the created external repository (default 'pip').
+ **kwargs: Keyword arguments passed directly to the `pip_repository` repository rule.
+ """
pip_repository(
name = name,
requirements = requirements,
diff --git a/experimental/rules_python_external/repositories.bzl b/experimental/rules_python_external/repositories.bzl
index 60c6e5d..00dc900 100644
--- a/experimental/rules_python_external/repositories.bzl
+++ b/experimental/rules_python_external/repositories.bzl
@@ -45,15 +45,18 @@
all_requirements = [name for (name, _, _) in _RULE_DEPS]
def requirement(pkg):
- return "@pypi__"+ pkg + "//:lib"
+ return "@pypi__" + pkg + "//:lib"
def rules_python_external_dependencies():
+ """
+ Fetch dependencies these rules depend on. Workspaces that use the rules_python_external should call this.
+ """
for (name, url, sha256) in _RULE_DEPS:
maybe(
http_archive,
name,
- url=url,
- sha256=sha256,
- type="zip",
- build_file_content=_GENERIC_WHEEL,
+ url = url,
+ sha256 = sha256,
+ type = "zip",
+ build_file_content = _GENERIC_WHEEL,
)
