Add option to print # value = comments, disable by default (#251)

Fixes #235

---------

Co-authored-by: Bryn Lloyd <12702862+dyollb@users.noreply.github.com>
Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>

Author: dyollb

README.md

@@ -33,6 +33,7 @@ pybind11-stubgen [-h]
                   --numpy-array-use-type-var|
                   --numpy-array-remove-parameters]
                  [--print-invalid-expressions-as-is]
+                 [--print-value-comments]
                  [--print-safe-value-reprs REGEX]
                  [--exit-code]
                  [--stub-extension EXT]

pybind11_stubgen/__init__.py

@@ -74,6 +74,7 @@ class CLIArgs(Namespace):
     numpy_array_remove_parameters: bool
     print_invalid_expressions_as_is: bool
     print_safe_value_reprs: re.Pattern | None
+    print_value_comments: bool
     exit_code: bool
     dry_run: bool
     stub_extension: str
@@ -191,6 +192,13 @@ def regex_colon_path(regex_path: str) -> tuple[re.Pattern, str]:
         type=regex,
         help="Override the print-safe check for values matching REGEX",
     )
+    parser.add_argument(
+        "--print-value-comments",
+        default=False,
+        action="store_true",
+        help="Print attribute values as comments for debugging, "
+        "i.e., '...  # value = <value>'",
+    )
 
     parser.add_argument(
         "--exit-code",
@@ -310,7 +318,10 @@ def main(argv: Sequence[str] | None = None) -> None:
     args = arg_parser().parse_args(argv, namespace=CLIArgs())
 
     parser = stub_parser_from_args(args)
-    printer = Printer(invalid_expr_as_ellipses=not args.print_invalid_expressions_as_is)
+    printer = Printer(
+        invalid_expr_as_ellipses=not args.print_invalid_expressions_as_is,
+        print_value_comments=args.print_value_comments,
+    )
 
     run(
         parser,

pybind11_stubgen/printer.py

@@ -137,8 +137,13 @@ def _add_edge(dependency: str, dependent: str) -> None:
 
 
 class Printer:
-    def __init__(self, invalid_expr_as_ellipses: bool):
+    def __init__(
+        self,
+        invalid_expr_as_ellipses: bool,
+        print_value_comments: bool = False,
+    ):
         self.invalid_expr_as_ellipses = invalid_expr_as_ellipses
+        self.print_value_comments = print_value_comments
 
     def _order_classes(self, classes: list[Class]) -> list[Class]:
         return _topological_sort_classes(classes)
@@ -158,7 +163,7 @@ def print_attribute(self, attr: Attribute) -> list[str]:
         else:
             if attr.annotation is None:
                 parts.append(" = ...")
-            if attr.value is not None:
+            if attr.value is not None and self.print_value_comments:
                 parts.append(f"  # value = {self.print_value(attr.value)}")
 
         return ["".join(parts)]

tests/check-demo-stubs-generation.sh

@@ -61,6 +61,7 @@ run_stubgen() {
       ${NUMPY_FORMAT} \
       --ignore-invalid-expressions="\(anonymous namespace\)::(Enum|Unbound)|<demo\._bindings\.flawed_bindings\..*" \
       --enum-class-locations="ConsoleForegroundColor:demo._bindings.enum" \
+      --print-value-comments \
       --print-safe-value-reprs="Foo\(\d+\)" \
       --exit-code
 }