Broaden support for core classes

Author: ofek

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## Unreleased
+
+### Added
+
+- Add support for `click.Command`-like, `click.Group`-like and `click.Context`-like objects without requiring them to be actual subclasses. (Pull #82)
+
+### Fixed
+
+- Remove explicit reference to `click.BaseCommand` and `click.MultiCommand` objects in anticipation of their deprecation. (Pull #82)
+
 ## 0.8.1 - 2023-09-18
 
 ### Fixed

mkdocs_click/_docs.py

@@ -15,7 +15,7 @@
 
 def make_command_docs(
     prog_name: str,
-    command: click.BaseCommand,
+    command: click.Command,
     depth: int = 0,
     style: str = "plain",
     remove_ascii_art: bool = False,
@@ -42,7 +42,7 @@ def make_command_docs(
 
 def _recursively_make_command_docs(
     prog_name: str,
-    command: click.BaseCommand,
+    command: click.Command,
     parent: click.Context | None = None,
     depth: int = 0,
     style: str = "plain",
@@ -90,20 +90,26 @@ def _recursively_make_command_docs(
 
 
 def _build_command_context(
-    prog_name: str, command: click.BaseCommand, parent: click.Context | None
+    prog_name: str, command: click.Command, parent: click.Context | None
 ) -> click.Context:
-    return click.Context(cast(click.Command, command), info_name=prog_name, parent=parent)
+    return _get_context_class(command)(
+        cast(click.Command, command), info_name=prog_name, parent=parent
+    )
 
 
-def _get_sub_commands(command: click.Command, ctx: click.Context) -> list[click.Command]:
+def _get_sub_commands(
+    command: click.Command | click.Group, ctx: click.Context
+) -> list[click.Command]:
     """Return subcommands of a Click command."""
     subcommands = getattr(command, "commands", {})
     if subcommands:
         return list(subcommands.values())
 
-    if not isinstance(command, click.MultiCommand):
+    if not _is_command_group(command):
         return []
 
+    command = cast(click.Group, command)
+
     subcommands = []
 
     for name in command.list_commands(ctx):
@@ -360,3 +366,13 @@ def _make_subcommands_links(
             help_string = "*No description was provided with this command.*"
         yield f"- *{command_bullet}*: {help_string}"
     yield ""
+
+
+def _get_context_class(command: click.Command) -> type[click.Context]:
+    # https://github.com/pallets/click/blob/8.1.8/src/click/core.py#L859-L862
+    return command.context_class
+
+
+def _is_command_group(command: click.Command) -> bool:
+    # https://github.com/pallets/click/blob/8.1.8/src/click/core.py#L1806-L1811
+    return isinstance(command, click.Group) or hasattr(command, "command_class")

mkdocs_click/_extension.py

@@ -22,7 +22,7 @@ def replace_command_docs(has_attr_list: bool = False, **options: Any) -> Iterato
 
     module = options["module"]
     command = options["command"]
-    prog_name = options.get("prog_name", None)
+    prog_name = options.get("prog_name")
     depth = int(options.get("depth", 0))
     style = options.get("style", "plain")
     remove_ascii_art = options.get("remove_ascii_art", False)

mkdocs_click/_loader.py

@@ -11,15 +11,15 @@
 from ._exceptions import MkDocsClickException
 
 
-def load_command(module: str, attribute: str) -> click.BaseCommand:
+def load_command(module: str, attribute: str) -> click.Command:
     """
     Load and return the Click command object located at '<module>:<attribute>'.
     """
     command = _load_obj(module, attribute)
 
-    if not isinstance(command, click.BaseCommand):
+    if not (isinstance(command, click.Command) or hasattr(command, "context_class")):
         raise MkDocsClickException(
-            f"{attribute!r} must be a 'click.BaseCommand' object, got {type(command)}"
+            f"{attribute!r} must be a 'click.Command'-like object, got {type(command)}"
         )
 
     return command

tests/app/cli.py

@@ -50,7 +50,7 @@ def hidden():
 cli_named.add_command(hidden)
 
 
-class MultiCLI(click.MultiCommand):
+class MultiCLI(click.Group):
     def list_commands(self, ctx):
         return ["foo", "bar"]
 

tests/test_docs.py

@@ -175,7 +175,7 @@ def test_style_table(command, expected):
     assert output == expected
 
 
-class MultiCLI(click.MultiCommand):
+class MultiCLI(click.Group):
     def list_commands(self, ctx):
         return ["single-command"]
 
@@ -190,9 +190,9 @@ def get_command(self, ctx, name):
         pytest.param(MultiCLI(help="Multi help"), id="no-name"),
     ],
 )
-def test_custom_multicommand(multi):
+def test_custom_group(multi):
     """
-    Custom `MultiCommand` objects are supported (i.e. not just `Group` multi-commands).
+    Custom `Group` objects are supported (i.e. not just `Group` multi-commands).
     """
     expected = dedent(
         """
@@ -242,9 +242,9 @@ def test_custom_multicommand(multi):
         pytest.param(MultiCLI(help="Multi help"), id="no-name"),
     ],
 )
-def test_custom_multicommand_with_list_subcommands(multi):
+def test_custom_group_with_list_subcommands(multi):
     """
-    Custom `MultiCommand` objects are supported (i.e. not just `Group` multi-commands).
+    Custom `Group` objects are supported (i.e. not just `Group` multi-commands).
     """
     expected = dedent(
         """