Replaced unmaintained optional dependency ruyaml with ruamel.yaml (#768)

Author: mauvilsa

CHANGELOG.rst

@@ -49,13 +49,18 @@ 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>`__).
+- Replaced unmaintained optional dependency ``ruyaml`` with ``ruamel.yaml``
+  (`#768 <https://github.com/omni-us/jsonargparse/pull/768>`__).
 
 Deprecated
 ^^^^^^^^^^
 - ``DefaultHelpFormatter.*_yaml*_comment*`` methods are deprecated and will be
   removed in v5.0.0. This logic has been moved to a new private class
   ``YAMLCommentFormatter``. If deemed necessary, this class might be made public
   in the future (`#754 <https://github.com/omni-us/jsonargparse/pull/754>`__).
+- The ``ruyaml`` optional dependency is deprecated and will be removed in
+  v5.0.0. Instead use the ``ruamel`` optional dependency (`#768
+  <https://github.com/omni-us/jsonargparse/pull/768>`__).
 
 
 v4.40.2 (2025-08-06)

DOCUMENTATION.rst

@@ -1321,9 +1321,9 @@ Serialization
 Parsers that have an `action="config"` argument also include a
 ``--print_config`` option. This is useful particularly for command line tools
 with a large set of options to create an initial config file including all
-default values. If the `ruyaml <https://ruyaml.readthedocs.io>`__ package is
-installed, the config can be printed having the help descriptions content as
-YAML comments by using ``--print_config=comments``. Another option is
+default values. If the `ruamel.yaml <https://pypi.org/project/ruamel.yaml>`__
+package is installed, the config can be printed having the help descriptions
+content as YAML comments by using ``--print_config=comments``. Another option is
 ``--print_config=skip_null`` which skips entries whose value is ``null``.
 
 From within Python it is also possible to serialize a config object by using

README.rst

@@ -183,7 +183,7 @@ By default, the only dependency installed with ``jsonargparse`` is `PyYAML
 <https://pypi.org/project/PyYAML/>`__. However, several optional features can be
 enabled by specifying one or more of the following extras (optional
 dependencies): ``signatures``, ``jsonschema``, ``jsonnet``, ``urls``,
-``fsspec``, ``toml``, ``ruyaml``, ``omegaconf``, ``shtab``, and ``argcomplete``.
+``fsspec``, ``toml``, ``ruamel``, ``omegaconf``, ``shtab``, and ``argcomplete``.
 Additionally, the ``all`` extras can be used to enable all optional features
 (excluding tab completion ones). To install ``jsonargparse`` with extras, use
 the following syntax:

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, ruyaml_support
+from ._optionals import _get_config_read_mode, ruamel_support
 from ._type_checking import ActionsContainer, ArgumentParser
 from ._util import (
     Path,
@@ -254,13 +254,13 @@ def __init__(
                 "flags customizes the output and are one or more keywords separated by comma. The "
                 "supported flags are:%s skip_default, skip_null."
             )
-            % (" comments," if ruyaml_support else ""),
+            % (" comments," if ruamel_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, "skip_default": "skip_default", "skip_null": "skip_none"}
-        if ruyaml_support:
+        if ruamel_support:
             valid_flags["comments"] = "yaml_comments"
         if value is not None:
             flags = value[0].split(",")

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, ruyamlCommentedMap
+from ._type_checking import ArgumentParser, ruamelCommentedMap
 
 __all__ = [
     "ActionEnum",
@@ -711,34 +711,34 @@ def add_yaml_comments(self, cfg: str) -> str:
         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.")
-    def set_yaml_start_comment(self, text: str, cfg: ruyamlCommentedMap):
-        """Sets the start comment to a ruyaml object.
+    def set_yaml_start_comment(self, text: str, cfg: ruamelCommentedMap):
+        """Sets the start comment to a ruamel.yaml object.
 
         Args:
             text: The content to use for the comment.
-            cfg: The ruyaml object.
+            cfg: The ruamel.yaml 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.")
-    def set_yaml_group_comment(self, text: str, cfg: ruyamlCommentedMap, key: str, depth: int):
-        """Sets the comment for a group to a ruyaml object.
+    def set_yaml_group_comment(self, text: str, cfg: ruamelCommentedMap, key: str, depth: int):
+        """Sets the comment for a group to a ruamel.yaml object.
 
         Args:
             text: The content to use for the comment.
-            cfg: The parent ruyaml object.
+            cfg: The parent ruamel.yaml 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.")
-    def set_yaml_argument_comment(self, text: str, cfg: ruyamlCommentedMap, key: str, depth: int):
-        """Sets the comment for an argument to a ruyaml object.
+    def set_yaml_argument_comment(self, text: str, cfg: ruamelCommentedMap, key: str, depth: int):
+        """Sets the comment for an argument to a ruamel.yaml object.
 
         Args:
             text: The content to use for the comment.
-            cfg: The parent ruyaml object.
+            cfg: The parent ruamel.yaml object.
             key: The key of the argument.
             depth: The nested level of the argument.
         """

jsonargparse/_formatters.py

@@ -33,8 +33,8 @@
 from ._deprecated import HelpFormatterDeprecations
 from ._link_arguments import ActionLink
 from ._namespace import Namespace, NSKeyError
-from ._optionals import import_ruyaml
-from ._type_checking import ArgumentParser, ruyamlCommentedMap
+from ._optionals import import_ruamel
+from ._type_checking import ArgumentParser, ruamelCommentedMap
 from ._typehints import ActionTypeHint, type_to_str
 
 __all__ = ["DefaultHelpFormatter"]
@@ -63,7 +63,7 @@ def __init__(self, help_formatter: HelpFormatter):
 
     def add_yaml_comments(self, cfg: str) -> str:
         """Adds help text as yaml comments."""
-        ruyaml = import_ruyaml("add_yaml_comments")
+        ruyaml = import_ruamel("add_yaml_comments")
         yaml = ruyaml.YAML()
         cfg = yaml.load(cfg)
 
@@ -119,28 +119,28 @@ def set_comments(cfg, prefix="", depth=0):
     def set_yaml_start_comment(
         self,
         text: str,
-        cfg: ruyamlCommentedMap,
+        cfg: ruamelCommentedMap,
     ):
-        """Sets the start comment to a ruyaml object.
+        """Sets the start comment to a ruamel.yaml object.
 
         Args:
             text: The content to use for the comment.
-            cfg: The ruyaml object.
+            cfg: The ruamel.yaml object.
         """
         cfg.yaml_set_start_comment(text)
 
     def set_yaml_group_comment(
         self,
         text: str,
-        cfg: ruyamlCommentedMap,
+        cfg: ruamelCommentedMap,
         key: str,
         depth: int,
     ):
-        """Sets the comment for a group to a ruyaml object.
+        """Sets the comment for a group to a ruamel.yaml object.
 
         Args:
             text: The content to use for the comment.
-            cfg: The parent ruyaml object.
+            cfg: The parent ruamel.yaml object.
             key: The key of the group.
             depth: The nested level of the group.
         """
@@ -149,15 +149,15 @@ def set_yaml_group_comment(
     def set_yaml_argument_comment(
         self,
         text: str,
-        cfg: ruyamlCommentedMap,
+        cfg: ruamelCommentedMap,
         key: str,
         depth: int,
     ):
-        """Sets the comment for an argument to a ruyaml object.
+        """Sets the comment for an argument to a ruamel.yaml object.
 
         Args:
             text: The content to use for the comment.
-            cfg: The parent ruyaml object.
+            cfg: The parent ruamel.yaml object.
             key: The key of the argument.
             depth: The nested level of the argument.
         """

jsonargparse/_loaders_dumpers.py

@@ -13,7 +13,7 @@
     import_toml_loads,
     omegaconf_support,
     pyyaml_available,
-    ruyaml_support,
+    ruamel_support,
 )
 from ._type_checking import ArgumentParser
 
@@ -263,7 +263,7 @@ def toml_dump(data):
     "toml": toml_dump,
     "jsonnet": json_indented_dump,
 }
-if ruyaml_support:
+if ruamel_support:
     dumpers["yaml_comments"] = yaml_comments_dump
 
 comment_prefix: Dict[str, str] = {

jsonargparse/_optionals.py

@@ -22,7 +22,7 @@
 url_support = find_spec("requests") is not None
 docstring_parser_support = find_spec("docstring_parser") is not None
 fsspec_support = find_spec("fsspec") is not None
-ruyaml_support = find_spec("ruyaml") is not None
+ruamel_support = bool(find_spec("ruamel") and find_spec("ruamel.yaml"))
 omegaconf_support = find_spec("omegaconf") is not None
 reconplogger_support = find_spec("reconplogger") is not None
 attrs_support = find_spec("attrs") is not None
@@ -152,10 +152,10 @@ def import_fsspec(importer):
     return fsspec
 
 
-def import_ruyaml(importer):
-    with missing_package_raise("ruyaml", importer):
-        import ruyaml
-    return ruyaml
+def import_ruamel(importer):
+    with missing_package_raise("ruamel.yaml", importer):
+        import ruamel.yaml
+    return ruamel.yaml
 
 
 def import_reconplogger(importer):

jsonargparse/_type_checking.py

@@ -5,12 +5,12 @@
     "ActionsContainer",
     "ArgumentParser",
     "docstring_parser",
-    "ruyamlCommentedMap",
+    "ruamelCommentedMap",
 ]
 
 if TYPE_CHECKING:  # pragma: no cover
     import docstring_parser
-    from ruyaml.comments import CommentedMap as ruyamlCommentedMap
+    from ruamel.yaml.comments import CommentedMap as ruamelCommentedMap
 
     from ._core import ActionsContainer, ArgumentGroup, ArgumentParser
 else:

jsonargparse_tests/test_cli.py

@@ -17,7 +17,7 @@
 
 from jsonargparse import CLI, auto_cli, auto_parser, capture_parser, lazy_instance
 from jsonargparse._namespace import Namespace
-from jsonargparse._optionals import docstring_parser_support, ruyaml_support
+from jsonargparse._optionals import docstring_parser_support, ruamel_support
 from jsonargparse.typing import final
 from jsonargparse_tests.conftest import json_or_yaml_dump, json_or_yaml_load, skip_if_docstring_parser_unavailable
 
@@ -351,7 +351,7 @@ def test_function_and_class_print_config_before_subcommands():
 
 
 @skip_if_docstring_parser_unavailable
-@pytest.mark.skipif(not ruyaml_support, reason="ruyaml not installed")
+@pytest.mark.skipif(not ruamel_support, reason="ruamel.yaml package is required")
 def test_function_and_class_print_config_comments():
     out = get_cli_stdout([cmd1, Cmd2, cmd3], args=["--print_config=comments", "Cmd2", "method2"])
     assert "# Description of Cmd2" in out