New plugin API for adding CLI options. Let plugins add corresponding TOML conf

Author: hukkin

src/mdformat/_cli.py

@@ -40,6 +40,8 @@ def run(cli_args: Sequence[str]) -> int:  # noqa: C901
     cli_opts = {
         k: v for k, v in vars(arg_parser.parse_args(cli_args)).items() if v is not None
     }
+    cli_core_opts, cli_plugin_opts = separate_core_and_plugin_opts(cli_opts)
+
     if not cli_opts["paths"]:
         print_paragraphs(["No files have been passed in. Doing nothing."])
         return 0
@@ -57,7 +59,13 @@ def run(cli_args: Sequence[str]) -> int:  # noqa: C901
         except InvalidConfError as e:
             print_error(str(e))
             return 1
-        opts: Mapping = {**DEFAULT_OPTS, **toml_opts, **cli_opts}
+
+        opts: Mapping = {**DEFAULT_OPTS, **toml_opts, **cli_core_opts}
+        for plugin_id, plugin_opts in cli_plugin_opts.items():
+            if plugin_id in opts["plugin"]:
+                opts["plugin"][plugin_id] |= plugin_opts
+            else:
+                opts["plugin"][plugin_id] = plugin_opts
 
         if sys.version_info >= (3, 13):  # pragma: >=3.13 cover
             if is_excluded(path, opts["exclude"], toml_path, "exclude" in cli_opts):
@@ -182,10 +190,38 @@ def make_arg_parser(
         )
     for plugin in parser_extensions.values():
         if hasattr(plugin, "add_cli_options"):
+            # TODO: deprecate in favor of add_cli_argument_group
             plugin.add_cli_options(parser)
+    for plugin_id, plugin in parser_extensions.items():
+        if hasattr(plugin, "add_cli_argument_group"):
+            group = parser.add_argument_group(title=f"{plugin_id} plugin")
+            plugin.add_cli_argument_group(group)
+            for action in group._group_actions:
+                action.dest = f"plugin.{plugin_id}.{action.dest}"
     return parser
 
 
+def separate_core_and_plugin_opts(opts: Mapping) -> tuple[dict, dict]:
+    """Move dotted keys like 'plugin.gfm.some_key' to a separate mapping.
+
+    Return a tuple of two mappings. First is for core CLI options, the
+    second for plugin options. E.g. 'plugin.gfm.some_key' belongs to the
+    second mapping under {"gfm": {"some_key": <value>}}.
+    """
+    cli_core_opts = {}
+    cli_plugin_opts: dict = {}
+    for k, v in opts.items():
+        if k.startswith("plugin."):
+            _, plugin_id, plugin_conf_key = k.split(".", maxsplit=2)
+            if plugin_id in cli_plugin_opts:
+                cli_plugin_opts[plugin_id][plugin_conf_key] = v
+            else:
+                cli_plugin_opts[plugin_id] = {plugin_conf_key: v}
+        else:
+            cli_core_opts[k] = v
+    return cli_core_opts, cli_plugin_opts
+
+
 class InvalidPath(Exception):
     """Exception raised when a path does not exist."""
 

src/mdformat/_conf.py

@@ -11,6 +11,7 @@
     "number": False,
     "end_of_line": "lf",
     "exclude": [],
+    "plugin": {},
 }
 
 
@@ -65,6 +66,12 @@ def _validate_values(opts: Mapping, conf_path: Path) -> None:  # noqa: C901
         for pattern in opts["exclude"]:
             if not isinstance(pattern, str):
                 raise InvalidConfError(f"Invalid 'exclude' value in {conf_path}")
+    if "plugin" in opts:
+        if not isinstance(opts["plugin"], dict):
+            raise InvalidConfError(f"Invalid 'plugin' value in {conf_path}")
+        for plugin_conf in opts["plugin"].values():
+            if not isinstance(plugin_conf, dict):
+                raise InvalidConfError(f"Invalid 'plugin' value in {conf_path}")
 
 
 def _validate_keys(opts: Mapping, conf_path: Path) -> None:

src/mdformat/plugins.py

@@ -40,11 +40,27 @@ class ParserExtensionInterface(Protocol):
     # (optional)
     POSTPROCESSORS: Mapping[str, Postprocess]
 
+    # TODO: deprecate in favor of add_cli_argument_group
     @staticmethod
     def add_cli_options(parser: argparse.ArgumentParser) -> None:
         """Add options to the mdformat CLI, to be stored in
         mdit.options["mdformat"] (optional)"""
 
+    @staticmethod
+    def add_cli_argument_group(group: argparse._ArgumentGroup) -> None:
+        """Add an argument group to mdformat CLI and add arguments to it.
+
+        Call `group.add_argument()` to add CLI arguments (signature is
+        the same as argparse.ArgumentParser.add_argument). Values will be
+        stored in a mapping under mdit.options["mdformat"]["plugin"][<plugin_id>]
+        where <plugin_id> equals entry point name of the plugin.
+
+        The mapping will be merged with values read from TOML config file
+        section [plugin.<plugin_id>].
+
+        (optional)
+        """
+
     @staticmethod
     def update_mdit(mdit: MarkdownIt) -> None:
         """Update the parser, e.g. by adding a plugin: `mdit.use(myplugin)`"""

tests/test_config_file.py

@@ -68,6 +68,8 @@ def test_invalid_toml(tmp_path, capsys):
         ("number", "number = 0"),
         ("exclude", "exclude = '**'"),
         ("exclude", "exclude = ['1',3]"),
+        ("plugin", "plugin = []"),
+        ("plugin", "plugin.gfm = {}\nplugin.myst = 1"),
     ],
 )
 def test_invalid_conf_value(bad_conf, conf_key, tmp_path, capsys):

tests/test_plugins.py

@@ -222,6 +222,83 @@ def test_cli_options(monkeypatch, tmp_path):
     assert opts["mdformat"]["arg_name"] == 4
 
 
+class ExamplePluginWithGroupedCli:
+    """A plugin that adds CLI options."""
+
+    @staticmethod
+    def update_mdit(mdit: MarkdownIt):
+        mdit.enable("table")
+
+    @staticmethod
+    def add_cli_argument_group(group: argparse._ArgumentGroup) -> None:
+        group.add_argument("--o1", type=str)
+        group.add_argument("--o2", type=str, default="a")
+        group.add_argument("--o3", dest="arg_name", type=int)
+        group.add_argument("--override-toml")
+
+
+def test_cli_options_group(monkeypatch, tmp_path):
+    """Test that CLI arguments added by plugins are correctly added to the
+    options dict.
+
+    Use add_cli_argument_group plugin API.
+    """
+    monkeypatch.setitem(PARSER_EXTENSIONS, "table", ExamplePluginWithGroupedCli)
+    file_path = tmp_path / "test_markdown.md"
+    conf_path = tmp_path / ".mdformat.toml"
+    file_path.touch()
+    conf_path.write_text(
+        """\
+[plugin.table]
+override_toml = 'failed'
+toml_only = true
+"""
+    )
+
+    with patch.object(MDRenderer, "render", return_value="") as mock_render:
+        assert (
+            run(
+                (
+                    str(file_path),
+                    "--o1",
+                    "other",
+                    "--o3",
+                    "4",
+                    "--override-toml",
+                    "success",
+                )
+            )
+            == 0
+        )
+
+    (call_,) = mock_render.call_args_list
+    posargs = call_[0]
+    # Options is the second positional arg of MDRender.render
+    opts = posargs[1]
+    assert opts["mdformat"]["plugin"]["table"]["o1"] == "other"
+    assert opts["mdformat"]["plugin"]["table"]["o2"] == "a"
+    assert opts["mdformat"]["plugin"]["table"]["arg_name"] == 4
+    assert opts["mdformat"]["plugin"]["table"]["override_toml"] == "success"
+    assert opts["mdformat"]["plugin"]["table"]["toml_only"] is True
+
+
+def test_cli_options_group__no_toml(monkeypatch, tmp_path):
+    """Test add_cli_argument_group plugin API with configuration only from
+    CLI."""
+    monkeypatch.setitem(PARSER_EXTENSIONS, "table", ExamplePluginWithGroupedCli)
+    file_path = tmp_path / "test_markdown.md"
+    file_path.touch()
+
+    with patch.object(MDRenderer, "render", return_value="") as mock_render:
+        assert run((str(file_path), "--o1", "other")) == 0
+
+    (call_,) = mock_render.call_args_list
+    posargs = call_[0]
+    # Options is the second positional arg of MDRender.render
+    opts = posargs[1]
+    assert opts["mdformat"]["plugin"]["table"]["o1"] == "other"
+
+
 class ExampleASTChangingPlugin:
     """A plugin that makes AST breaking formatting changes."""