more extensions doc work, some typing work

Author: bckohan

django_typer/__init__.py

@@ -152,6 +152,7 @@
 
 P = ParamSpec("P")
 R = t.TypeVar("R")
+C = t.TypeVar("C", bound=BaseCommand)
 
 _CACHE_KEY = "_register_typer"
 
@@ -220,15 +221,52 @@ def handle(
     }
 
 
+@t.overload
+def get_command(  # type: ignore[overload-overlap]
+    command_name: str,
+    stdout: t.Optional[t.IO[str]] = None,
+    stderr: t.Optional[t.IO[str]] = None,
+    no_color: bool = False,
+    force_color: bool = False,
+    **kwargs,
+) -> BaseCommand: ...
+
+
+@t.overload
+# mypy seems to break on this one, but this is correct
 def get_command(
     command_name: str,
-    *subcommand: str,
+    cmd_type: t.Type[C],
     stdout: t.Optional[t.IO[str]] = None,
     stderr: t.Optional[t.IO[str]] = None,
     no_color: bool = False,
     force_color: bool = False,
     **kwargs,
-) -> t.Union[BaseCommand, MethodType]:
+) -> C: ...
+
+
+@t.overload
+def get_command(
+    command_name: str,
+    path0: str,
+    *path: str,
+    stdout: t.Optional[t.IO[str]] = None,
+    stderr: t.Optional[t.IO[str]] = None,
+    no_color: bool = False,
+    force_color: bool = False,
+    **kwargs,
+) -> MethodType: ...
+
+
+def get_command(
+    command_name,
+    *path,
+    stdout=None,
+    stderr=None,
+    no_color: bool = False,
+    force_color: bool = False,
+    **kwargs,
+):
     """
     Get a Django_ command by its name and instantiate it with the provided options. This
     will work for subclasses of BaseCommand_ as well as for :class:`~django_typer.TyperCommand`
@@ -261,8 +299,17 @@ def get_command(
         divide = get_command('hierarchy', 'math', 'divide')
         result = divide(10, 2)
 
+    When fetching an entire TyperCommand (i.e. no group or subcommand path), you may supply
+    the type of the expected TyperCommand as the second argument. This will allow the type
+    system to infer the correct return type:
+
+    .. code-block:: python
+
+        from myapp.management.commands import Command as Hierarchy
+        hierarchy: Hierarchy = get_command('hierarchy', Hierarchy)
+
     :param command_name: the name of the command to get
-    :param subcommand: the subcommand to get if any
+    :param path: the path walking down the group/command tree
     :param stdout: the stdout stream to use
     :param stderr: the stderr stream to use
     :param no_color: whether to disable color
@@ -274,16 +321,15 @@ def get_command(
     module = import_module(
         f"{get_commands()[command_name]}.management.commands.{command_name}"
     )
-    cmd = module.Command(
+    cmd: BaseCommand = module.Command(
         stdout=stdout,
         stderr=stderr,
         no_color=no_color,
         force_color=force_color,
         **kwargs,
     )
-    if subcommand:
-        method = cmd.get_subcommand(*subcommand).click_command._callback.__wrapped__
-        return MethodType(method, cmd)  # return the bound method
+    if path and (isinstance(path[0], str) or len(path) > 1):
+        return t.cast(TyperCommand, cmd).get_subcommand(*path).callback
 
     return cmd
 
@@ -406,7 +452,7 @@ def __init__(
             parent.children.append(self)
 
 
-class _DjangoAdapterMixin(with_typehint(CoreTyperGroup)):  # type: ignore[misc]
+class DjangoTyperCommand(with_typehint(CoreTyperGroup)):  # type: ignore[misc]
     """
     A mixin we use to add additional needed contextual awareness to click Commands
     and Groups.
@@ -556,15 +602,15 @@ def call_with_self(*args, **kwargs):
         )
 
 
-class TyperCommandWrapper(_DjangoAdapterMixin, CoreTyperCommand):
+class TyperCommandWrapper(DjangoTyperCommand, CoreTyperCommand):
     """
     This class extends the TyperCommand class to work with the django-typer
     interfaces. If you need to add functionality to the command class - which
     you should not - you should inherit from this class.
     """
 
 
-class TyperGroupWrapper(_DjangoAdapterMixin, CoreTyperGroup):
+class TyperGroupWrapper(DjangoTyperCommand, CoreTyperGroup):
     """
     This class extends the TyperGroup class to work with the django-typer
     interfaces. If you need to add functionality to the group class - which
@@ -2162,16 +2208,47 @@ class CommandNode:
     """
 
     name: str
-    click_command: click.Command
+    """
+    The name of the group or command that this node represents.
+    """
+
+    click_command: DjangoTyperCommand
+    """
+    The click command object that this node represents.
+    """
+
     context: TyperContext
+    """
+    The Typer context object used to run this command.
+    """
+
     django_command: "TyperCommand"
+    """
+    Back reference to the django command instance that this command belongs to.
+    """
+
     parent: t.Optional["CommandNode"] = None
+    """
+    The parent node of this command node or None if this is a root node.
+    """
+
     children: t.Dict[str, "CommandNode"]
+    """
+    The child group and command nodes of this command node.
+    """
+
+    @property
+    def callback(self) -> t.Callable[..., t.Any]:
+        """Get the function for this command or group"""
+        cb = getattr(self.click_command._callback, "__wrapped__")
+        return (
+            MethodType(cb, self.django_command) if self.click_command.is_method else cb
+        )
 
     def __init__(
         self,
         name: str,
-        click_command: click.Command,
+        click_command: DjangoTyperCommand,
         context: TyperContext,
         django_command: "TyperCommand",
         parent: t.Optional["CommandNode"] = None,
@@ -2197,8 +2274,9 @@ def get_command(self, *command_path: str) -> "CommandNode":
         Return the command node for the given command path at or below
         this node.
 
-        :param command_path: the path(s) to the command to retrieve
-        :return: the command node at the given path
+        :param command_path: the parent group names followed by the name of the command
+            or group to retrieve
+        :return: the command node at the given group/subcommand path
         :raises LookupError: if the command path does not exist
         """
         if not command_path:
@@ -2208,6 +2286,15 @@ def get_command(self, *command_path: str) -> "CommandNode":
         except KeyError as err:
             raise LookupError(f'No such command "{command_path[0]}"') from err
 
+    def __call__(self, *args, **kwargs) -> t.Any:
+        """
+        Call this command or group directly.
+
+        :param args: the arguments to pass to the command or group callback
+        :param kwargs: the named parameters to pass to the command or group callback
+        """
+        return self.callback(*args, **kwargs)
+
 
 class TyperParser:
     """
@@ -2902,7 +2989,14 @@ def __init__(
                 ) from rerr
 
     def get_subcommand(self, *command_path: str) -> CommandNode:
-        """Get the CommandNode"""
+        """
+        Retrieve a :class:`~django_typer.CommandNode` at the given command path.
+
+        :param command_path: the path to the command to retrieve, where each argument
+            is the string name in order of a group or command in the hierarchy.
+        :return: the command node at the given path
+        :raises LookupError: if no group or command exists at the given path
+        """
         return self.command_tree.get_command(*command_path)
 
     def _filter_commands(
@@ -2955,6 +3049,7 @@ def _build_cmd_tree(
         :param node: the parent node or None if this is a root node
         """
         assert cmd.name
+        assert isinstance(cmd, DjangoTyperCommand)
         ctx = Context(cmd, info_name=info_name, parent=parent, django_command=self)
         current = CommandNode(cmd.name, cmd, ctx, self, parent=node)
         if node:

django_typer/examples/tutorial/backup/backup.py

@@ -7,7 +7,13 @@
 from django.conf import settings
 from django.core.management import CommandError, call_command
 
-from django_typer import TyperCommand, command, completers, initialize
+from django_typer import (
+    TyperCommand,
+    CommandNode,
+    command,
+    completers,
+    initialize,
+)
 
 
 class Command(TyperCommand):
@@ -29,7 +35,7 @@ class Command(TyperCommand):
     @initialize(invoke_without_command=True)
     def init_or_run_all(
         self,
-        # if we add a context argument click will provide it
+        # if we add a context argument Typer will provide it
         context: typer.Context,
         output_directory: t.Annotated[
             Path,
@@ -53,9 +59,9 @@ def init_or_run_all(
         # if it was not we run all the backup routines
         if not context.invoked_subcommand:
             for cmd in self.get_backup_routines():
-                getattr(self, cmd)()
+                cmd()
 
-    def get_backup_routines(self) -> t.List[str]:
+    def get_backup_routines(self) -> t.List[CommandNode]:
         """
         Return the list of backup subcommands. This is every registered command
         except for the list command.
@@ -64,8 +70,8 @@ def get_backup_routines(self) -> t.List[str]:
         # except for list, which we know to not be a backup routine
         return [
             cmd
-            for cmd in self.get_subcommand().children.keys()
-            if cmd != "list"
+            for name, cmd in self.get_subcommand().children.items()
+            if name != "list"
         ]
 
     @command()
@@ -75,14 +81,15 @@ def list(self):
         """
         self.echo("Default backup routines:")
         for cmd in self.get_backup_routines():
-            kwargs = {
-                name: str(param.default)
+            sig = {
+                name: param.default
                 for name, param in inspect.signature(
-                    getattr(self, cmd)
+                    cmd.callback
                 ).parameters.items()
+                if not name == "self"
             }
-            params = ", ".join([f"{k}={v}" for k, v in kwargs.items()])
-            self.secho(f"  {cmd}({params})", fg="green")
+            params = ", ".join([f"{k}={v}" for k, v in sig.items()])
+            self.secho(f"  {cmd.name}({params})", fg="green")
 
     @command()
     def database(

django_typer/examples/tutorial/backup/backup_ext1.py

@@ -9,11 +9,13 @@
     Command as Backup,
 )
 
-DEFAULT_MEDIA_FILENAME = "media.tar.gz"
-
 
+# instead of inheriting we add the command using the classmethod decorator
+# on the backup Command class to decorate a module scoped function
 @Backup.command()
 def media(
+    # self is optional, but if you want to access the command instance, you
+    # can specify it
     self,
     filename: t.Annotated[
         str,
@@ -22,7 +24,7 @@ def media(
             "--filename",
             help=("The name of the file to use for the media backup tar."),
         ),
-    ] = DEFAULT_MEDIA_FILENAME,
+    ] = "media.tar.gz",
 ):
     """
     Backup the media files (i.e. those files in MEDIA_ROOT).

django_typer/examples/tutorial/backup/backup_ext2.py

@@ -1,8 +1,11 @@
+import shutil
 import subprocess
 import typing as t
+import datetime
 
 import typer
 
+from django.conf import settings
 from django_typer.tests.apps.backup.backup.management.commands.backup import (
     Command as Backup,
 )
@@ -29,3 +32,17 @@ def environment(
     typer.echo(f"Capturing python environment to {output_file}")
     with output_file.open("w") as f:
         subprocess.run(["pip", "freeze"], stdout=f)
+
+
+@Backup.command()
+def database(self):
+    """
+    Backup the database by copying the sqlite file and tagging it with the
+    current date.
+    """
+    db_file = self.output_directory / f"backup_{datetime.date.today()}.sqlite3"
+    self.echo("Backing up database to {db_file}")
+    shutil.copy(
+        settings.DATABASES["default"]["NAME"],
+        db_file,
+    )

django_typer/examples/tutorial/backup/backup_inherit.py

@@ -11,7 +11,8 @@
 )
 
 
-class Command(Backup):
+class Command(Backup):  # inherit from the original command
+    # add a new command called media that archives the MEDIA_ROOT dir
     @command()
     def media(
         self,

django_typer/tests/apps/backup/extend2/apps.py

@@ -8,5 +8,4 @@ class Extend2Config(AppConfig):
 
     def ready(self):
         from .management import extensions
-
         register_command_extensions(extensions)

django_typer/tests/test_backup_example.py

@@ -5,6 +5,7 @@
 from django.test import SimpleTestCase
 from pathlib import Path
 from django_typer.tests.utils import run_command
+import datetime
 import shutil
 
 
@@ -93,9 +94,7 @@ def test_extend_backup(self):
         self.assertEqual(retcode, 0, msg=stderr)
         lines = [line.strip() for line in stdout.strip().splitlines()[1:]]
         self.assertEqual(len(lines), 3)
-        self.assertTrue(
-            "database(filename={database}.json, databases=['default'])" in lines
-        )
+        self.assertTrue("database()" in lines)
         self.assertTrue("environment(filename=requirements.txt)" in lines)
         self.assertTrue("media(filename=media.tar.gz)" in lines)
 
@@ -108,7 +107,9 @@ def test_extend_backup(self):
         )
         self.assertEqual(retcode, 0, msg=stderr)
         self.assertTrue(BACKUP_DIRECTORY.exists())
-        self.assertTrue((BACKUP_DIRECTORY / "default.json").exists())
+        self.assertTrue(
+            (BACKUP_DIRECTORY / f"backup_{datetime.date.today()}.sqlite3").exists()
+        )
         self.assertTrue((BACKUP_DIRECTORY / "media.tar.gz").exists())
         self.assertTrue((BACKUP_DIRECTORY / "requirements.txt").exists())
         self.assertTrue(len(os.listdir(BACKUP_DIRECTORY)) == 3)