document the args

Author: aignas

python/uv/private/lock.bzl

@@ -150,22 +150,22 @@ _lock = rule(
 """,
     attrs = {
         "args": attr.string_list(
-            doc = "Args to pass to `uv`.",
+            doc = "Public, see the docs in the macro.",
+            mandatory = True,
         ),
         "build_constraints": attr.label_list(
-            mandatory = False,
+            mandatory = True,
             allow_files = True,
-            doc = """The files to constrain the resolution.""",
+            doc = "Public, see the docs in the macro.",
         ),
         "constraints": attr.label_list(
-            mandatory = False,
+            mandatory = True,
             allow_files = True,
-            doc = """The files to constrain the versions used when building wheels.""",
+            doc = "Public, see the docs in the macro.",
         ),
         "env": attr.string_dict(
-            doc = """\
-The env variables that are set when executing `uv`.
-""",
+            doc = "Public, see the docs in the macro.",
+            mandatory = True,
         ),
         "existing_output": attr.label(
             mandatory = False,
@@ -176,27 +176,17 @@ modifications and the locking is not done from scratch.
 """,
         ),
         "generate_hashes": attr.bool(
-            default = True,
-            doc = """\
-Generate hashes for all of the requirements. This is a must if you want to use
-{attr}`pip.parse.experimental_index_url`.
-""",
+            mandatory = True,
+            doc = "Public, see the docs in the macro.",
         ),
         "srcs": attr.label_list(
             mandatory = True,
             allow_files = True,
-            doc = """\
-The sources that will be used. Add all of the files that would be passed as
-srcs to the `uv pip compile` command.
-""",
+            doc = "Public, see the docs in the macro.",
         ),
         "strip_extras": attr.bool(
-            default = False,
-            doc = """\
-Currently `rules_python` requires `--no-strip-extras` to properly function, but
-sometimes one may want to not have the extras if you are compiling the
-requirements file for using it as a constraints file.
-""",
+            mandatory = True,
+            doc = "Public, see the docs in the macro.",
         ),
         "update_target": attr.string(
             mandatory = True,
@@ -303,7 +293,19 @@ def _maybe_file(path):
 
     return None
 
-def lock(*, name, srcs, out, args = [], env = None, **kwargs):
+def lock(
+        *,
+        name,
+        args = [],
+        build_constraints = [],
+        constraints = [],
+        env = None,
+        generate_hashes = True,
+        out,
+        python_version = None,
+        srcs,
+        strip_extras = False,
+        **kwargs):
     """Pin the requirements based on the src files.
 
     This macro creates the following targets:
@@ -318,14 +320,27 @@ def lock(*, name, srcs, out, args = [], env = None, **kwargs):
       `native_test` to wrap this target to make a test.
 
     Args:
-        name: The name of the target to run for updating the requirements.
-        srcs: The srcs to use as inputs.
-        out: The output file.
-        args: Extra args to pass to `uv`.
-        env: Passed to `uv`.
-        **kwargs: Extra kwargs passed to the {obj}`py_binary` rule. The most
-            useful `kwarg` is `{obj}`py_binary.python_version`, which allows
-            customizing the python version used for locking.
+        name: {type}`str` The prefix of all targets created by this macro.
+        srcs: {type}`list[Label]` The sources that will be used. Add all of the
+            files that would be passed as srcs to the `uv pip compile` command.
+        out: {type}`str` The output file relative to the package.
+        args: {type}`list[str]` The list of args to pass to uv. Note, these are
+            written into the runnable `name.run` target.
+        env: {type}`dict[str, str]` the environment variables to set. Note, this
+            is passed as is and the environment variables are not expanded.
+        build_constraints: {type}`list[Label]` The list of build constraints to use.
+        constraints: {type}`list[Label]` The list of constraints files to use.
+        generate_hashes: {type}`bool` Generate hashes for all of the
+            requirements. This is a must if you want to use
+            {attr}`pip.parse.experimental_index_url`. Defaults to `True`.
+        strip_extras: {type}`bool` whether to strip extras from the output.
+            Currently `rules_python` requires `--no-strip-extras` to properly
+            function, but sometimes one may want to not have the extras if you
+            are compiling the requirements file for using it as a constraints
+            file. Defaults to `False`.
+        python_version: {type}`str | None` the python_version to transition to
+            when locking the requirements.
+        **kwargs: Extra kwargs passed to the `name.update` {obj}`py_binary` target.
     """
     update_target = "{}.update".format(name)
     locker_target = "{}.run".format(name)
@@ -354,6 +369,10 @@ def lock(*, name, srcs, out, args = [], env = None, **kwargs):
         ],
         args = args,
         env = env,
+        generate_hashes = generate_hashes,
+        constraints = constraints,
+        build_constraints = build_constraints,
+        strip_extras = strip_extras,
         target_compatible_with = target_compatible_with,
     )
 
@@ -388,5 +407,6 @@ def lock(*, name, srcs, out, args = [], env = None, **kwargs):
         name = update_target,
         srcs = [update_target + ".py"],
         data = [name] + ([] if not maybe_out else [maybe_out]),
+        python_version = python_version,
         **kwargs
     )