refactor!: do not use a wrapper macro for pip_parse (#1514)

This brings back the generated documentation for the pip_parse
attributes making switches to default values more prominent.

Towards #1496.

Author: aignas

CHANGELOG.md

@@ -29,11 +29,16 @@ A brief description of the categories of changes:
   `GAZELLE_PYTHON_RUNTIME_DEPS` from `@rules_python_gazelle_plugin//:def.bzl` is
   no longer necessary.
 
+* The installation of `pip_parse` repository rule toolchain dependencies is now
+  done as part of `py_repositories` call.
+
 Breaking changes:
 
 * (pip) `pip_install` repository rule in this release has been disabled and
   will fail by default. The API symbol is going to be removed in the next
-  version, please migrate to `pip_parse` as a replacement.
+  version, please migrate to `pip_parse` as a replacement. The `pip_parse`
+  rule no longer supports `requirements` attribute, please use
+  `requirements_lock` instead.
 
 * (py_wheel) switch `incompatible_normalize_name` and
   `incompatible_normalize_version` to `True` by default to enforce `PEP440`

python/pip.bzl

@@ -20,14 +20,14 @@ for internal use only.
 """
 
 load("//python/pip_install:pip_repository.bzl", "pip_repository", _package_annotation = "package_annotation")
-load("//python/pip_install:repositories.bzl", "pip_install_dependencies")
 load("//python/pip_install:requirements.bzl", _compile_pip_requirements = "compile_pip_requirements")
 load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED")
 load("//python/private:full_version.bzl", "full_version")
 load("//python/private:render_pkg_aliases.bzl", "NO_MATCH_ERROR_MESSAGE_TEMPLATE")
 
 compile_pip_requirements = _compile_pip_requirements
 package_annotation = _package_annotation
+pip_parse = pip_repository
 
 def pip_install(requirements = None, name = "pip", allow_pip_install = False, **kwargs):
     """Will be removed in 0.28.0
@@ -44,41 +44,6 @@ def pip_install(requirements = None, name = "pip", allow_pip_install = False, **
     else:
         fail("pip_install support has been disabled, please use pip_parse as a replacement.")
 
-def pip_parse(requirements = None, requirements_lock = None, name = "pip_parsed_deps", **kwargs):
-    """Accepts a locked/compiled requirements file and installs the dependencies listed within.
-
-    Those dependencies become available as addressable targets and
-    in a generated `requirements.bzl` file. The `requirements.bzl` file can
-    be checked into source control, if desired; see {ref}`vendoring-requirements`
-
-    For more information, see {ref}`pip-integration`.
-
-    Args:
-        requirements_lock (Label): A fully resolved 'requirements.txt' pip requirement file
-            containing the transitive set of your dependencies. If this file is passed instead
-            of 'requirements' no resolve will take place and pip_repository will create
-            individual repositories for each of your dependencies so that wheels are
-            fetched/built only for the targets specified by 'build/run/test'.
-            Note that if your lockfile is platform-dependent, you can use the `requirements_[platform]`
-            attributes.
-        requirements (Label): Deprecated. See requirements_lock.
-        name (str, optional): The name of the generated repository. The generated repositories
-            containing each requirement will be of the form `<name>_<requirement-name>`.
-        **kwargs (dict): Additional arguments to the [`pip_repository`](./pip_repository.md) repository rule.
-    """
-    pip_install_dependencies()
-
-    # Temporary compatibility shim.
-    # pip_install was previously document to use requirements while pip_parse was using requirements_lock.
-    # We would prefer everyone move to using requirements_lock, but we maintain a temporary shim.
-    reqs_to_use = requirements_lock if requirements_lock else requirements
-
-    pip_repository(
-        name = name,
-        requirements_lock = reqs_to_use,
-        **kwargs
-    )
-
 def _multi_pip_parse_impl(rctx):
     rules_python = rctx.attr._rules_python_workspace.workspace_name
     load_statements = []

python/pip_install/pip_repository.bzl

@@ -454,10 +454,14 @@ pip_repository_attrs = {
     ),
     "requirements_lock": attr.label(
         allow_single_file = True,
-        doc = """
-A fully resolved 'requirements.txt' pip requirement file containing the transitive set of your dependencies. If this file is passed instead
-of 'requirements' no resolve will take place and pip_repository will create individual repositories for each of your dependencies so that
-wheels are fetched/built only for the targets specified by 'build/run/test'.
+        doc = """\
+A fully resolved 'requirements.txt' pip requirement file containing the
+transitive set of your dependencies. If this file is passed instead of
+'requirements' no resolve will take place and pip_repository will create
+individual repositories for each of your dependencies so that wheels are
+fetched/built only for the targets specified by 'build/run/test'. Note that if
+your lockfile is platform-dependent, you can use the `requirements_[platform]`
+attributes.
 """,
     ),
     "requirements_windows": attr.label(
@@ -473,22 +477,32 @@ pip_repository_attrs.update(**common_attrs)
 
 pip_repository = repository_rule(
     attrs = pip_repository_attrs,
-    doc = """A rule for importing `requirements.txt` dependencies into Bazel.
+    doc = """Accepts a locked/compiled requirements file and installs the dependencies listed within.
+
+Those dependencies become available in a generated `requirements.bzl` file.
+You can instead check this `requirements.bzl` file into your repo, see the "vendoring" section below.
 
-This rule imports a `requirements.txt` file and generates a new
-`requirements.bzl` file.  This is used via the `WORKSPACE` pattern:
+This macro wraps the [`pip_repository`](./pip_repository.md) rule that invokes `pip`.
+In your WORKSPACE file:
 
-```python
-pip_repository(
-    name = "foo",
-    requirements = ":requirements.txt",
+```starlark
+load("@rules_python//python:pip.bzl", "pip_parse")
+
+pip_parse(
+    name = "pip_deps",
+    requirements_lock = ":requirements.txt",
 )
+
+load("@pip_deps//:requirements.bzl", "install_deps")
+
+install_deps()
 ```
 
-You can then reference imported dependencies from your `BUILD` file with:
+You can then reference installed dependencies from a `BUILD` file with:
+
+```starlark
+load("@pip_deps//:requirements.bzl", "requirement")
 
-```python
-load("@foo//:requirements.bzl", "requirement")
 py_library(
     name = "bar",
     ...
@@ -500,17 +514,52 @@ py_library(
 )
 ```
 
-Or alternatively:
-```python
-load("@foo//:requirements.bzl", "all_requirements")
-py_binary(
-    name = "baz",
-    ...
-    deps = [
-       ":foo",
-    ] + all_requirements,
+In addition to the `requirement` macro, which is used to access the generated `py_library`
+target generated from a package's wheel, The generated `requirements.bzl` file contains
+functionality for exposing [entry points][whl_ep] as `py_binary` targets as well.
+
+[whl_ep]: https://packaging.python.org/specifications/entry-points/
+
+```starlark
+load("@pip_deps//:requirements.bzl", "entry_point")
+
+alias(
+    name = "pip-compile",
+    actual = entry_point(
+        pkg = "pip-tools",
+        script = "pip-compile",
+    ),
 )
 ```
+
+Note that for packages whose name and script are the same, only the name of the package
+is needed when calling the `entry_point` macro.
+
+```starlark
+load("@pip_deps//:requirements.bzl", "entry_point")
+
+alias(
+    name = "flake8",
+    actual = entry_point("flake8"),
+)
+```
+
+## Vendoring the requirements.bzl file
+
+In some cases you may not want to generate the requirements.bzl file as a repository rule
+while Bazel is fetching dependencies. For example, if you produce a reusable Bazel module
+such as a ruleset, you may want to include the requirements.bzl file rather than make your users
+install the WORKSPACE setup to generate it.
+See https://github.com/bazelbuild/rules_python/issues/608
+
+This is the same workflow as Gazelle, which creates `go_repository` rules with
+[`update-repos`](https://github.com/bazelbuild/bazel-gazelle#update-repos)
+
+To do this, use the "write to source file" pattern documented in
+https://blog.aspect.dev/bazel-can-write-to-the-source-folder
+to put a copy of the generated requirements.bzl into your project.
+Then load the requirements.bzl file directly rather than from the generated repository.
+See the example in rules_python/examples/pip_parse_vendored.
 """,
     implementation = _pip_repository_impl,
     environ = common_env,

python/pip_install/repositories.bzl

@@ -14,10 +14,8 @@
 
 ""
 
-load("@bazel_skylib//lib:versions.bzl", "versions")
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
-load("//:version.bzl", "MINIMUM_BAZEL_VERSION")
 
 _RULE_DEPS = [
     # START: maintained by 'bazel run //tools/private:update_pip_deps'
@@ -137,13 +135,6 @@ def pip_install_dependencies():
 
     (However we call it from pip_install, making it optional for users to do so.)
     """
-
-    # We only support Bazel LTS and rolling releases.
-    # Give the user an obvious error to upgrade rather than some obscure missing symbol later.
-    # It's not guaranteed that users call this function, but it's used by all the pip fetch
-    # repository rules so it's likely that most users get the right error.
-    versions.check(MINIMUM_BAZEL_VERSION)
-
     for (name, url, sha256) in _RULE_DEPS:
         maybe(
             http_archive,

python/repositories.bzl

@@ -19,6 +19,7 @@ For historic reasons, pip_repositories() is defined in //python:pip.bzl.
 
 load("@bazel_tools//tools/build_defs/repo:http.bzl", _http_archive = "http_archive")
 load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe", "read_netrc", "read_user_netrc", "use_netrc")
+load("//python/pip_install:repositories.bzl", "pip_install_dependencies")
 load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED")
 load("//python/private:coverage_deps.bzl", "coverage_dep")
 load("//python/private:full_version.bzl", "full_version")
@@ -59,6 +60,7 @@ def py_repositories():
             "https://github.com/bazelbuild/bazel-skylib/releases/download/1.3.0/bazel-skylib-1.3.0.tar.gz",
         ],
     )
+    pip_install_dependencies()
 
 ########
 # Remaining content of the file is only used to support toolchains.