all tests working - pre-inheritance mechanism refactor

Author: bckohan

django_typer/__init__.py

@@ -0,0 +1,118 @@
+import typing as t
+from django.core.management.base import CommandError
+import typer.core
+from django_typer import TyperCommand, completers, get_command, Typer, CommandGroup
+import importlib
+import sys
+
+if sys.version_info < (3, 9):
+    from typing_extensions import Annotated
+else:
+    from typing import Annotated
+
+import typer
+from pathlib import Path
+
+import graphviz
+
+
+from enum import StrEnum
+
+
+class Format(StrEnum):
+    png = "png"
+    svg = "svg"
+    pdf = "pdf"
+    dot = "dot"
+
+
+class Command(TyperCommand):
+    """
+    Graph the Typer app tree associated with the given command.
+    """
+
+    cmd: TyperCommand
+    cmd_name: str
+    dot = graphviz.Digraph()
+    level: int = -1
+
+    def handle(
+        self,
+        command: Annotated[
+            str,
+            typer.Argument(
+                help="An import path to the command to graph, or simply the name of the command.",
+                shell_complete=completers.complete_import_path,
+            ),
+        ],
+        output: Annotated[
+            Path,
+            typer.Option(
+                "-o",
+                "--output",
+                help="The path to save the graph to.",
+                shell_complete=completers.complete_path,
+            ),
+        ] = Path("{command}_app_tree"),
+        format: Annotated[
+            Format,
+            typer.Option(
+                "-f",
+                "--format",
+                help="The format to save the graph in.",
+                shell_complete=completers.these_strings(list(Format)),
+            ),
+        ] = Format.png,
+        instantiate: Annotated[
+            bool,
+            typer.Option(help="Instantiate the command before graphing the app tree."),
+        ] = True,
+    ):
+        self.cmd_name = command.split(".")[-1]
+        if "." in command:
+            self.cmd = getattr(importlib.import_module(command), "Command")
+            if instantiate:
+                self.cmd = self.cmd()
+        elif instantiate:
+            self.cmd = get_command(command, TyperCommand)
+        else:
+            raise CommandError("Cannot instantiate a command that is not imported.")
+
+        output = Path(output.parent) / Path(output.name.format(command=self.cmd_name))
+
+        self.visit_app(self.cmd.typer_app)
+        self.dot.render(output, format=format, view=True)
+
+    def get_node_name(self, obj: t.Union[typer.models.CommandInfo, CommandGroup]):
+        assert obj.callback
+        name = (
+            obj.callback.__name__
+            if isinstance(obj, typer.models.CommandInfo)
+            else str(obj.name)
+        )
+        cli_name = (
+            obj.name or name
+            if isinstance(obj, typer.models.CommandInfo)
+            else obj.info.name or name
+        )
+        if name != cli_name:
+            name += f"({cli_name})"
+        return f"[{hex(id(obj))[-4:]}] {name}"
+
+    def visit_app(self, app: Typer):
+        """
+        Walk the typer app tree.
+        """
+        self.level += 1
+        parent_node = self.get_node_name(app) if self.level else self.cmd_name
+
+        self.dot.node(str(id(app)), parent_node)
+        for cmd in app.registered_commands:
+            node_name = self.get_node_name(cmd)
+            self.dot.node(str(id(cmd)), node_name)
+            self.dot.edge(str(id(app)), str(id(cmd)))
+        for grp in app.registered_groups:
+            assert grp.typer_instance
+            node_name = self.get_node_name(t.cast(CommandGroup, grp.typer_instance))
+            self.dot.edge(str(id(app)), str(id(grp.typer_instance)))
+            self.visit_app(t.cast(Typer, grp.typer_instance))

django_typer/tests/apps/test_app/management/commands/graph.py

@@ -1,5 +1,6 @@
-from django_typer import Typer, TyperCommand
+from django_typer import Typer, TyperCommand, CommandGroup
 from django_typer.types import Verbosity
+import typing as t
 
 Command: TyperCommand
 
@@ -23,6 +24,9 @@ def main(name: str):
 
 grp2 = Typer()
 
+# # this does not work
+# app.add_typer(t.cast(CommandGroup, grp2))
+
 
 @grp2.callback(name="grp1")
 def init_grp1(flag: bool = False):
@@ -35,6 +39,7 @@ def cmd2(fraction: float):
     return {"verbosity": _verbosity, "flag": _flag, "fraction": fraction}
 
 
+#  this works
 app.add_typer(grp2)
 
 

django_typer/tests/apps/test_app/management/commands/native_groups.py

@@ -12,3 +12,13 @@ def cmd2():
 def cmd2(self):
     assert self.__class__ is GrpOverload
     return f"g1:l2:cmd2()"
+
+
+@GrpOverload.group(invoke_without_command=True)
+def g2(self):
+    return "g2()"
+
+
+@GrpOverload.g2.group()
+def l2():
+    return "g2:l2()"

django_typer/tests/apps/test_app/management/extensions/grp_overload.py

@@ -238,12 +238,7 @@ def test_native_groups_helps(self):
             native_groups.print_help("./manage.py", *(cmd_pth.split()))
             sim = similarity(expected_help, stdout.getvalue())
             print(f"print_help({cmd_pth}) --help similiarity: {sim}")
-            try:
-                self.assertGreater(sim, 0.99)
-            except AssertionError:
-                import ipdb
-
-                ipdb.set_trace()
+            self.assertGreater(sim, 0.99)
 
             parts = cmd_pth.split()
             sim = similarity(

django_typer/tests/test_native.py

@@ -218,9 +218,19 @@ def test_grp_overload_direct(self):
 
         grp_overload = get_command("grp_overload", GrpOverload)
 
+        print("----------")
         self.assertEqual(grp_overload.g1.l2("a"), "g1:l2(a)")
+        print("----------")
         self.assertEqual(grp_overload.g0.l2(1), "g0:l2(1)")
+        print("----------")
         self.assertEqual(grp_overload.g0.l2.cmd(), "g0:l2:cmd()")
+        print("----------")
         self.assertEqual(grp_overload.g1.l2.cmd(), "g1:l2:cmd()")
-        # self.assertEqual(grp_overload.g0.l2.cmd2(), "g0:l2:cmd2()")
-        # self.assertEqual(grp_overload.g1.l2.cmd2(), "g1:l2:cmd2()")
+        print("----------")
+
+        self.assertEqual(grp_overload.g0.l2.cmd_obj(), grp_overload)
+        self.assertEqual(grp_overload.g1.l2.cmd_obj(), grp_overload)
+
+        self.assertTrue(hasattr(grp_overload.g0.l2, "cmd2"))
+        self.assertEqual(grp_overload.g0.l2.cmd2(), "g0:l2:cmd2()")
+        self.assertEqual(grp_overload.g1.l2.cmd2(), "g1:l2:cmd2()")

django_typer/tests/test_overloads.py

@@ -322,12 +322,29 @@ Say we have this command, called ``mycommand``:
     assert mycommand(10) == 10
 
 
-The rule of them is this:
+The rule of thumb is this:
 
     - Use call_command_ if your options and arguments need parsing.
     - Use :func:`~django_typer.get_command` and invoke the command functions directly if your
       options and arguments are already of the correct type.
 
+If the second argument is a type, static type checking will assume the return value of get_command
+to be of that type:
+
+.. code-block:: python
+
+    from django_typer import get_command
+    from myapp.management.commands.math import Command as Math
+
+    math = get_command("math", Math)
+    math.add(10, 5)  # type checkers will resolve add parameters correctly
+
+You may also fetch a subcommand function directly by passing its path:
+
+.. code-block:: python
+
+    get_command("math", "add")(10, 5)
+
 .. tip::
 
     Also refer to the :func:`~django_typer.get_command` docs and :ref:`here <multi_with_defaults>`
@@ -655,8 +672,8 @@ The precedence order, for a simple command is as follows:
 The rule for how helps are resolved when inheriting from other commands is that higher precedence
 helps in base classes will be chosen over lower priority helps in deriving classes. However, if
 you would like to use a docstring as the help in a derived class instead of the high priority
-help in a base class you can set the equivalent priority help in the deriving class to the empty
-string:
+help in a base class you can set the equivalent priority help in the deriving class to a falsy
+value:
 
 .. code-block:: python
 

doc/source/howto.rst

@@ -61,7 +61,7 @@ utils
 -----
 
 .. automodule:: django_typer.utils
-    :members: traceback_config, get_current_command, register_command_extensions
+    :members: traceback_config, get_current_command, register_command_extensions, is_method
 
 .. _shellcompletion:
 
@@ -70,3 +70,123 @@ shellcompletion
 
 .. automodule:: django_typer.management.commands.shellcompletion
     :members:
+
+
+Metaclass Logic: Tending the Typer Tree
+---------------------------------------
+
+The principal design challenge of django-typer_ is to manage the Typer_ app trees associated with
+each Django management command class and to keep these trees separate when classes are inherited
+and allow them to be edited directly when commands are extended through the composition pattern.
+
+The Typer_ app tree defines the layers of groups and commands that define the CLI. Each
+:class:`~django_typer.TyperCommand` maintains its own app tree, and when other classes inherit from
+a base command class, that app tree is copied and the new class can modify it without affecting the
+base class.
+
+django-typer_ must support all of the following:
+
+* Inherited classes can extend and override groups and commands defined on the base class without
+  affecting the base class so that the base class may still be imported and used directly as it
+  was originally designed.
+* Extensions defined using the composition pattern must be able to modify the app trees of the
+  commands they extend directly.
+* The group/command tree on instantiated commands must be walkable using attributes from the
+  command instance itself to support subgroup name overloads.
+
+During all of this, the correct self must be passed if the function accepts it, but all of the
+registered functions are not registered as methods because they enter the Typer_ app tree as
+regular functions. This means another thing django-typer_ must do is decide if a function is a
+method and if so, bind it to the correct class and pass the correct self instance. The method
+test is :func:`~django_typer.utils.is_method` and simply checks to see if the function accepts
+a first positional argument named `self`.
+
+django-typer_ uses metaclasses to build the typer app tree when :class:`~django_typer.TyperCommand`
+classes are instantiated. The logic flow proceeds this way:
+
+- Class definition is read and @initialize, @group, @command decorators label and store typer
+  config and registration logic onto the function objects for processing later once the root
+  Typer_ app is created.
+- Metaclass __new__ creates the root Typer_ app for the class and caches the implementation of
+  handle if it exists.
+- Metaclass __init__ walks the class tree and copies the Typer_ app tree from the parent class
+  to the child class.
+
+
+
+.. code-block:: python
+
+    class Command(TyperCommand):
+
+        # command() runs before the Typer_ app is created, therefore we
+        # have to cache it and run it later during class creation
+        @command()
+        def cmd1(self):
+            pass
+
+        @group()
+        def grp1(self):
+            pass
+
+        @grp1.group(self):
+        def grp2(self):
+            pass
+
+
+.. code-block:: python
+
+    class Command(UpstreamCommand):
+
+      # This must *not* alter the grp1 app on the base
+      # app tree but instead create a new one on this
+      # commands app tree when it is created
+      @UpstreamCommand.grp1.command()
+      def cmd3(self):
+          pass
+
+      # this gets interesting though, because these should be
+      # equivalent:
+      @UpstreamCommand.grp2.command()
+      def cmd4(self):
+          pass
+
+      @UpstreamCommand.grp1.grp2.command()
+      def cmd4(self):
+          pass
+
+
+.. code-block:: python
+
+  # extensions called at module scope should modify the app tree of the
+  # command directly
+  @UpstreamCommand.grp1.command()
+  def cmd4(self):
+      pass
+
+
+.. code-block:: python
+
+  app = Typer()
+
+  # similar to extensions these calls should modify the app tree directly
+  # the Command class exists after the first Typer() call and app is a reference
+  # directly to Command.typer_app
+  @app.callback()
+  def init():
+    pass
+
+
+  @app.command()
+  def main():
+      pass
+
+  grp2 = Typer()
+  app.add_typer(grp2)
+
+  @grp2.callback(name="grp1")
+  def init_grp1():
+      pass
+
+  @grp2.command()
+  def cmd2():
+      pass

doc/source/reference.rst

@@ -88,6 +88,7 @@ django-stubs = "^4.2.7"
 pexpect = "^4.9.0"
 pyright = "^1.1.357"
 ruff = "^0.4.1"
+graphviz = "^0.20.3"
 
 [tool.poetry.extras]
 rich = ["rich"]