Some cleanup

Author: mauvilsa

CHANGELOG.rst

@@ -12,6 +12,22 @@ The semantic versioning only considers the public API as described in
 paths are considered internals and can change in minor and patch releases.
 
 
+v4.41.0 (2025-08-??)
+--------------------
+
+Changed
+^^^^^^^
+- ``YAML`` comments feature is now implemented in a separate class to allow
+  better support for custom help formatters without breaking the comments (`#754
+  <https://github.com/omni-us/jsonargparse/pull/754>`__).
+
+Deprecated
+^^^^^^^^^^
+- ``DefaultHelpFormatter.*_yaml*_comment*`` methods are deprecated and will be
+  removed in v5.0.0. Instead use the new class ``YAMLCommentFormatter`` (`#754
+  <https://github.com/omni-us/jsonargparse/pull/754>`__).
+
+
 v4.40.2 (2025-08-06)
 --------------------
 

jsonargparse/_actions.py

@@ -12,7 +12,7 @@
 from ._common import Action, is_subclass, parser_context
 from ._loaders_dumpers import get_loader_exceptions, load_value
 from ._namespace import Namespace, NSKeyError, split_key, split_key_root
-from ._optionals import _get_config_read_mode
+from ._optionals import _get_config_read_mode, ruyaml_support
 from ._type_checking import ActionsContainer, ArgumentParser
 from ._util import (
     Path,
@@ -251,13 +251,16 @@ def __init__(
             help=(
                 "Print the configuration after applying all other arguments and exit. The optional "
                 "flags customizes the output and are one or more keywords separated by comma. The "
-                "supported flags are: comments, skip_default, skip_null."
-            ),
+                "supported flags are:%s skip_default, skip_null."
+            )
+            % (" comments," if ruyaml_support else ""),
         )
 
     def __call__(self, parser, namespace, value, option_string=None):
         kwargs = {"subparser": parser, "key": None, "skip_none": False, "skip_validation": False}
-        valid_flags = {"": None, "comments": "yaml_comments", "skip_default": "skip_default", "skip_null": "skip_none"}
+        valid_flags = {"": None, "skip_default": "skip_default", "skip_null": "skip_none"}
+        if ruyaml_support:
+            valid_flags["comments"] = "yaml_comments"
         if value is not None:
             flags = value[0].split(",")
             invalid_flags = [f for f in flags if f not in valid_flags]

jsonargparse/_deprecated.py

@@ -14,7 +14,7 @@
 from ._common import Action, null_logger
 from ._common import LoggerProperty as InternalLoggerProperty
 from ._namespace import Namespace
-from ._type_checking import ArgumentParser
+from ._type_checking import ArgumentParser, ruyamlCommentedMap
 
 __all__ = [
     "ActionEnum",
@@ -701,3 +701,70 @@ class LoggerProperty(InternalLoggerProperty):
 def namespace_to_dict(namespace: Namespace) -> Dict[str, Any]:
     """Returns a copy of a nested namespace converted into a nested dictionary."""
     return namespace.clone().as_dict()
+
+
+class HelpFormatterDeprecations:
+    def __init__(self, *args, **kwargs):
+        from jsonargparse._formatters import YAMLCommentFormatter
+
+        super().__init__(*args, **kwargs)
+        self._yaml_formatter = YAMLCommentFormatter(self)
+
+    @deprecated(
+        """
+        The add_yaml_comments method is deprecated and will be removed in v5.0.0.
+        Use :class:`YAMLCommentFormatter` instead.
+    """
+    )
+    def add_yaml_comments(self, cfg: str) -> str:
+        """Adds help text as yaml comments."""
+        return self._yaml_formatter.add_yaml_comments(cfg)
+
+    @deprecated(
+        """
+        The set_yaml_start_comment method is deprecated and will be removed in v5.0.0.
+        Use :class:`YAMLCommentFormatter` instead.
+    """
+    )
+    def set_yaml_start_comment(self, text: str, cfg: ruyamlCommentedMap):
+        """Sets the start comment to a ruyaml object.
+
+        Args:
+            text: The content to use for the comment.
+            cfg: The ruyaml object.
+        """
+        self._yaml_formatter.set_yaml_start_comment(text, cfg)
+
+    @deprecated(
+        """
+        The set_yaml_group_comment method is deprecated and will be removed in v5.0.0.
+        Use :class:`YAMLCommentFormatter` instead.
+    """
+    )
+    def set_yaml_group_comment(self, text: str, cfg: ruyamlCommentedMap, key: str, depth: int):
+        """Sets the comment for a group to a ruyaml object.
+
+        Args:
+            text: The content to use for the comment.
+            cfg: The parent ruyaml object.
+            key: The key of the group.
+            depth: The nested level of the group.
+        """
+        self._yaml_formatter.set_yaml_group_comment(text, cfg, key, depth)
+
+    @deprecated(
+        """
+        The set_yaml_argument_comment method is deprecated and will be removed in v5.0.0.
+        Use :class:`YAMLCommentFormatter` instead.
+    """
+    )
+    def set_yaml_argument_comment(self, text: str, cfg: ruyamlCommentedMap, key: str, depth: int):
+        """Sets the comment for an argument to a ruyaml object.
+
+        Args:
+            text: The content to use for the comment.
+            cfg: The parent ruyaml object.
+            key: The key of the argument.
+            depth: The nested level of the argument.
+        """
+        self._yaml_formatter.set_yaml_argument_comment(text, cfg, key, depth)

jsonargparse/_formatters.py

@@ -30,7 +30,7 @@
     supports_optionals_as_positionals,
 )
 from ._completions import ShtabAction
-from ._deprecated import deprecated
+from ._deprecated import HelpFormatterDeprecations
 from ._link_arguments import ActionLink
 from ._namespace import Namespace, NSKeyError
 from ._optionals import import_ruyaml
@@ -119,7 +119,7 @@ def set_comments(cfg, prefix="", depth=0):
     def set_yaml_start_comment(
         self,
         text: str,
-        cfg: "ruyamlCommentedMap",
+        cfg: ruyamlCommentedMap,
     ):
         """Sets the start comment to a ruyaml object.
 
@@ -132,7 +132,7 @@ def set_yaml_start_comment(
     def set_yaml_group_comment(
         self,
         text: str,
-        cfg: "ruyamlCommentedMap",
+        cfg: ruyamlCommentedMap,
         key: str,
         depth: int,
     ):
@@ -149,7 +149,7 @@ def set_yaml_group_comment(
     def set_yaml_argument_comment(
         self,
         text: str,
-        cfg: "ruyamlCommentedMap",
+        cfg: ruyamlCommentedMap,
         key: str,
         depth: int,
     ):
@@ -164,7 +164,7 @@ def set_yaml_argument_comment(
         cfg.yaml_set_comment_before_after_key(key, before="\n" + text, indent=2 * depth)
 
 
-class DefaultHelpFormatter(HelpFormatter):
+class DefaultHelpFormatter(HelpFormatterDeprecations, HelpFormatter):
     """Help message formatter that includes types, default values and env var names.
 
     This class is an extension of `argparse.HelpFormatter
@@ -174,69 +174,6 @@ class DefaultHelpFormatter(HelpFormatter):
     the respective environment variable name is included preceded by 'ENV:'.
     """
 
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self._yaml_formatter = YAMLCommentFormatter(self)
-
-    @deprecated(
-        """
-        The add_yaml_comments method is deprecated and will be removed in a future version.
-        Use :class:`YAMLCommentFormatter` instead.
-    """
-    )
-    def add_yaml_comments(self, cfg: str) -> str:
-        """Adds help text as yaml comments."""
-        return self._yaml_formatter.add_yaml_comments(cfg)
-
-    @deprecated(
-        """
-        The set_yaml_start_comment method is deprecated and will be removed in a future version.
-        Use :class:`YAMLCommentFormatter` instead.
-    """
-    )
-    def set_yaml_start_comment(self, text: str, cfg: "ruyamlCommentedMap"):
-        """Sets the start comment to a ruyaml object.
-
-        Args:
-            text: The content to use for the comment.
-            cfg: The ruyaml object.
-        """
-        self._yaml_formatter.set_yaml_start_comment(text, cfg)
-
-    @deprecated(
-        """
-        The set_yaml_group_comment method is deprecated and will be removed in a future version.
-        Use :class:`YAMLCommentFormatter` instead.
-    """
-    )
-    def set_yaml_group_comment(self, text: str, cfg: "ruyamlCommentedMap", key: str, depth: int):
-        """Sets the comment for a group to a ruyaml object.
-
-        Args:
-            text: The content to use for the comment.
-            cfg: The parent ruyaml object.
-            key: The key of the group.
-            depth: The nested level of the group.
-        """
-        self._yaml_formatter.set_yaml_group_comment(text, cfg, key, depth)
-
-    @deprecated(
-        """
-        The set_yaml_argument_comment method is deprecated and will be removed in a future version.
-        Use :class:`YAMLCommentFormatter` instead.
-    """
-    )
-    def set_yaml_argument_comment(self, text: str, cfg: "ruyamlCommentedMap", key: str, depth: int):
-        """Sets the comment for an argument to a ruyaml object.
-
-        Args:
-            text: The content to use for the comment.
-            cfg: The parent ruyaml object.
-            key: The key of the argument.
-            depth: The nested level of the argument.
-        """
-        self._yaml_formatter.set_yaml_argument_comment(text, cfg, key, depth)
-
     def _get_help_string(self, action: Action) -> str:
         action_help = " " if action.help == empty_help else action.help
         assert isinstance(action_help, str)

jsonargparse/_loaders_dumpers.py

@@ -2,11 +2,19 @@
 
 import inspect
 import re
+from argparse import HelpFormatter
 from contextlib import suppress
 from typing import Any, Callable, Dict, Optional, Set, Tuple, Type
 
 from ._common import load_value_mode, parent_parser
-from ._optionals import import_jsonnet, import_toml_dumps, import_toml_loads, omegaconf_support, pyyaml_available
+from ._optionals import (
+    import_jsonnet,
+    import_toml_dumps,
+    import_toml_loads,
+    omegaconf_support,
+    pyyaml_available,
+    ruyaml_support,
+)
 from ._type_checking import ArgumentParser
 
 __all__ = [
@@ -249,13 +257,14 @@ def toml_dump(data):
 
 dumpers: Dict[str, Callable] = {
     "yaml": yaml_dump,
-    "yaml_comments": yaml_comments_dump,
     "json": json_compact_dump,
     "json_compact": json_compact_dump,
     "json_indented": json_indented_dump,
     "toml": toml_dump,
     "jsonnet": json_indented_dump,
 }
+if ruyaml_support:
+    dumpers["yaml_comments"] = yaml_comments_dump
 
 comment_prefix: Dict[str, str] = {
     "yaml": "# ",
@@ -336,7 +345,7 @@ def set_omegaconf_loader():
 set_loader("jsonnet", jsonnet_load, get_loader_exceptions("jsonnet"))
 
 
-def create_help_formatter_with_comments(formatter_class: Type["HelpFormatter"]) -> Type["HelpFormatter"]:
+def create_help_formatter_with_comments(formatter_class: Type[HelpFormatter]) -> Type[HelpFormatter]:
     """Creates a dynamic class that combines a formatter with YAML comment functionality.
 
     Args:
@@ -347,7 +356,7 @@ def create_help_formatter_with_comments(formatter_class: Type["HelpFormatter"])
     """
     from ._formatters import YAMLCommentFormatter
 
-    class DynamicHelpFormatter(formatter_class):
+    class DynamicHelpFormatter(formatter_class):  # type: ignore[valid-type,misc]
         def __init__(self, *args, **kwargs):
             super().__init__(*args, **kwargs)
             self._yaml_formatter = YAMLCommentFormatter(self)

jsonargparse_tests/test_core.py

@@ -759,12 +759,22 @@ def test_print_config_skip_null(print_parser):
 @pytest.mark.skipif(not ruyaml_support, reason="ruyaml package is required")
 @skip_if_docstring_parser_unavailable
 def test_print_config_comments(print_parser):
+    help_str = get_parser_help(print_parser)
+    assert "comments," in help_str
     out = get_parse_args_stdout(print_parser, ["--print_config=comments"])
     assert "# cli tool" in out
     assert "# Option v1. (default: 1)" in out
     assert "# Option v2. (default: 2)" in out
 
 
+@pytest.mark.skipif(ruyaml_support, reason="ruyaml package should not be installed")
+def test_print_config_comments_unavailable(print_parser):
+    help_str = get_parser_help(print_parser)
+    assert "comments," not in help_str
+    with pytest.raises(ArgumentError, match='Invalid option "comments"'):
+        get_parse_args_stdout(print_parser, ["--print_config=comments"])
+
+
 def test_print_config_invalid_flag(print_parser):
     with pytest.raises(ArgumentError) as ctx:
         print_parser.parse_args(["--print_config=invalid"])

jsonargparse_tests/test_deprecated.py

@@ -44,6 +44,7 @@
     import_ruyaml,
     jsonnet_support,
     pyyaml_available,
+    ruyaml_support,
     url_support,
 )
 from jsonargparse._util import argument_error
@@ -730,8 +731,8 @@ def test_namespace_to_dict():
     )
 
 
-def test_DefaultHelpFormatter_yaml_comments():
-    parser = ArgumentParser()
+@pytest.mark.skipif(not ruyaml_support, reason="ruyaml package is required")
+def test_DefaultHelpFormatter_yaml_comments(parser):
     parser.add_argument("--arg", type=int, help="Description")
     formatter = DefaultHelpFormatter(prog="test")
     from jsonargparse._common import parent_parser
@@ -743,32 +744,24 @@ def test_DefaultHelpFormatter_yaml_comments():
 
     with catch_warnings(record=True) as w:
         formatter.add_yaml_comments("arg: 1")
-    assert "The add_yaml_comments method is deprecated and will be removed in a future version. Use" in str(
-        w[-1].message
-    )
-    assert ":class:`YAMLCommentFormatter` instead" in str(w[-1].message)
+    assert "add_yaml_comments method is deprecated and will be removed in v5.0.0" in str(w[-1].message)
+    assert ":class:`YAMLCommentFormatter`" in str(w[-1].message)
     assert "formatter.add_yaml_comments(" in source[w[-1].lineno - 1]
 
     with catch_warnings(record=True) as w:
         formatter.set_yaml_start_comment("start", cfg)
-    assert "The set_yaml_start_comment method is deprecated and will be removed in a future version. Use" in str(
-        w[-1].message
-    )
-    assert ":class:`YAMLCommentFormatter` instead" in str(w[-1].message)
+    assert "set_yaml_start_comment method is deprecated and will be removed in v5.0.0" in str(w[-1].message)
+    assert ":class:`YAMLCommentFormatter`" in str(w[-1].message)
     assert "formatter.set_yaml_start_comment(" in source[w[-1].lineno - 1]
 
     with catch_warnings(record=True) as w:
         formatter.set_yaml_group_comment("group", cfg, "arg", 0)
-    assert "The set_yaml_group_comment method is deprecated and will be removed in a future version. Use" in str(
-        w[-1].message
-    )
-    assert ":class:`YAMLCommentFormatter` instead" in str(w[-1].message)
+    assert "set_yaml_group_comment method is deprecated and will be removed in v5.0.0" in str(w[-1].message)
+    assert ":class:`YAMLCommentFormatter`" in str(w[-1].message)
     assert "formatter.set_yaml_group_comment(" in source[w[-1].lineno - 1]
 
     with catch_warnings(record=True) as w:
         formatter.set_yaml_argument_comment("arg", cfg, "arg", 0)
-    assert "The set_yaml_argument_comment method is deprecated and will be removed in a future version. Use" in str(
-        w[-1].message
-    )
-    assert ":class:`YAMLCommentFormatter` instead" in str(w[-1].message)
+    assert "set_yaml_argument_comment method is deprecated and will be removed in v5.0.0" in str(w[-1].message)
+    assert ":class:`YAMLCommentFormatter`" in str(w[-1].message)
     assert "formatter.set_yaml_argument_comment(" in source[w[-1].lineno - 1]