fix #129, progress towards #128

Author: bckohan

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Architecture
 
-The principal design challenge of [django-typer](https://pypi.python.org/pypi/django-typer) is to manage the [Typer](https://typer.tiangolo.com/) 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 plugin pattern. There are also incurred complexities with adding default django options where appropriate and supporting command callbacks as methods or static functions. Supporting dynamic command/group access through attributes on command instances also requires careful usage of advanced Python features.
+The principal design challenge of [django-typer](https://pypi.python.org/pypi/django-typer) is to manage the [Typer](https://typer.tiangolo.com/) 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 plugin pattern. There are also incurred complexities with adding default django options where appropriate and supporting command callbacks as methods or static functions. Supporting dynamic command/group access through attributes on command instances also requires careful usage of esoteric Python features.
 
 The [Typer](https://typer.tiangolo.com/) app tree defines the layers of groups and commands that define the CLI. Each [TyperCommand](https://django-typer.readthedocs.io/en/latest/reference.html#django_typer.TyperCommand) maintains its own app tree defined by a root [Typer](https://django-typer.readthedocs.io/en/latest/reference.html#django_typer.management.Typer) node. 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's tree. We extend [Typer](https://typer.tiangolo.com/)'s Typer type with our own [Typer](https://django-typer.readthedocs.io/en/latest/reference.html#django_typer.management.Typer) class that adds additional bookkeeping and attribute resolution features we need.
 

django_typer/management/__init__.py

@@ -612,6 +612,18 @@ def grp(self):
                 ...
     """
 
+    def list_commands(self, ctx: click.Context) -> t.List[str]:
+        """
+        Do our best to list commands in definition order.
+        """
+        cmds = list(self.commands.keys())
+        ordered = []
+        for defined in getattr(self.django_command, "_defined_order", []):
+            if defined in cmds:
+                ordered.append(defined)
+                cmds.remove(defined)
+        return ordered + cmds
+
 
 # staticmethod objects are not picklable which causes problems with deepcopy
 # hence the following mishegoss
@@ -1663,9 +1675,9 @@ def _add_common_initializer(
     """
     if cmd.is_compound_command and not cmd.typer_app.registered_callback:
         cmd.typer_app.callback(
-            cls=type(
+            cls=type(  # pyright: ignore[reportArgumentType]
                 "_Initializer",
-                (DTGroup,),
+                (cmd.typer_app.info.cls or DTGroup,),
                 {
                     "django_command": cmd,
                     "_callback_is_method": False,
@@ -1966,10 +1978,16 @@ def get_ctor(attr: t.Any) -> t.Optional[t.Callable[..., t.Any]]:
             to_remove = []
             to_register = []
             local_handle = attrs.pop("handle", None)
+            defined_order = []
             for cmd_cls, cls_attrs in [
                 *[(base, vars(base)) for base in command_bases()],
                 (None, attrs),
             ]:
+                defined_order += [
+                    cmd
+                    for cmd in getattr(cmd_cls, "_defined_order", [])
+                    if cmd not in defined_order
+                ]
                 for name, attr in list(cls_attrs.items()):
                     if name == "_handle":
                         continue
@@ -1980,8 +1998,12 @@ def get_ctor(attr: t.Any) -> t.Optional[t.Callable[..., t.Any]]:
                         assert name
                         to_remove.append(name)
                         _defined_groups[name] = attr
+                        if cmd_cls is None and name not in defined_order:
+                            defined_order.append(name)
                     elif register := get_ctor(attr):
                         to_register.append(register)
+                        if cmd_cls is None and name not in defined_order:
+                            defined_order.append(name)
 
                 handle = getattr(cmd_cls, "_handle", handle)
 
@@ -2002,6 +2024,7 @@ def get_ctor(attr: t.Any) -> t.Optional[t.Callable[..., t.Any]]:
 
             if handle:
                 ctor = get_ctor(handle)
+                defined_order.insert(0, typer_app.info.name)
                 if ctor:
                     to_register.append(
                         lambda cmd_cls: ctor(
@@ -2019,6 +2042,7 @@ def get_ctor(attr: t.Any) -> t.Optional[t.Callable[..., t.Any]]:
                     )
 
             attrs = {
+                "_defined_order": defined_order,
                 **attrs,
                 "_handle": handle,
                 "_to_register": to_register,
@@ -2034,20 +2058,20 @@ def get_ctor(attr: t.Any) -> t.Optional[t.Callable[..., t.Any]]:
 
         return super().__new__(mcs, cls_name, bases, attrs)
 
-    def __init__(cls, cls_name, bases, attrs, **kwargs):
+    def __init__(self, cls_name, bases, attrs, **kwargs):
         """
         This method is called after a new class is created.
         """
-        cls = t.cast(t.Type["TyperCommand"], cls)
-        if getattr(cls, "typer_app", None):
-            cls.typer_app.django_command = cls
-            cls.typer_app.info.name = (
-                cls.typer_app.info.name or cls.__module__.rsplit(".", maxsplit=1)[-1]
+        self = t.cast(t.Type["TyperCommand"], self)
+        if getattr(self, "typer_app", None):
+            self.typer_app.django_command = self
+            self.typer_app.info.name = (
+                self.typer_app.info.name or self.__module__.rsplit(".", maxsplit=1)[-1]
             )
-            for cmd in getattr(cls, "_to_register", []):
-                cmd(cls)
+            for cmd in getattr(self, "_to_register", []):
+                cmd(self)
 
-            _add_common_initializer(cls)
+            _add_common_initializer(self)
 
         super().__init__(cls_name, bases, attrs, **kwargs)
 

tests/apps/howto/management/commands/order.py

@@ -0,0 +1,33 @@
+from django_typer.management import TyperCommand, DTGroup, command, group
+from click import Context
+
+
+class ReverseAlphaCommands(DTGroup):
+    def list_commands(self, ctx: Context) -> list[str]:
+        return list(sorted(self.commands.keys(), reverse=True))
+
+
+class Command(TyperCommand, cls=ReverseAlphaCommands):
+    @command()
+    def a(self):
+        print("a")
+
+    @command()
+    def b(self):
+        print("b")
+
+    @command()
+    def c(self):
+        print("c")
+
+    @group(cls=ReverseAlphaCommands)
+    def d(self):
+        print("d")
+
+    @d.command()
+    def e(self):
+        print("e")
+
+    @d.command()
+    def f(self):
+        print("f")

tests/apps/howto/management/commands/order_typer.py

@@ -0,0 +1,43 @@
+from django_typer.management import Typer, DTGroup
+from click import Context
+
+
+class ReverseAlphaCommands(DTGroup):
+    def list_commands(self, ctx: Context) -> list[str]:
+        return list(sorted(self.commands.keys(), reverse=True))
+
+
+app = Typer(cls=ReverseAlphaCommands)
+
+d_app = Typer(cls=ReverseAlphaCommands)
+app.add_typer(d_app)
+
+
+@app.command()
+def a():
+    print("a")
+
+
+@app.command()
+def b():
+    print("b")
+
+
+@app.command()
+def c():
+    print("c")
+
+
+@d_app.callback(cls=ReverseAlphaCommands)
+def d():
+    print("d")
+
+
+@d_app.command()
+def e():
+    print("e")
+
+
+@d_app.command()
+def f():
+    print("f")

tests/apps/test_app/management/commands/order.py

@@ -0,0 +1,39 @@
+from django_typer.management import TyperCommand, command, group
+
+
+class Command(TyperCommand):
+    """
+    Test that helps list commands in definition order.
+    (This is different than click where the order is alphabetical by default)
+    """
+
+    @command()
+    def b(self):
+        print("b")
+
+    @command()
+    def a(self):
+        print("a")
+
+    @group()
+    def d(self):
+        print("d")
+
+    @command()
+    def c(self):
+        print("c")
+
+    @d.command()
+    def g(self):
+        print("g")
+
+    def handle(self):
+        print("handle")
+
+    @d.command()
+    def e(self):
+        print("e")
+
+    @d.command()
+    def f(self):
+        print("f")

tests/apps/test_app/management/commands/order2.py

@@ -0,0 +1,45 @@
+from django_typer.management import TyperCommand, command, group
+from tests.apps.test_app.management.commands.order import Command as OrderCommand
+
+
+class Command(OrderCommand):
+    """
+    Test that helps list commands in definition order.
+    (This is different than click where the order is alphabetical by default)
+    """
+
+    @group()
+    def bb(self):
+        print("bb")
+
+    @command()
+    def aa(self):
+        print("aa")
+
+    @OrderCommand.d.group()
+    def x(self):
+        print("x")
+
+    @command()
+    def b(self):
+        print("b")
+
+    @OrderCommand.d.command()
+    def i(self):
+        print("i")
+
+    @OrderCommand.d.command()
+    def h(self):
+        print("h")
+
+    @command(help="Override handle")
+    def handle(self):
+        print("handle")
+
+    @x.command()
+    def z(self):
+        print("z")
+
+    @x.command()
+    def y(self):
+        print("y")

tests/test_basics.py

@@ -125,3 +125,99 @@ def test_get_command_make_callable(self):
         self.assertEqual(
             get_command("base")(*args, **kwargs), f"base({args}, {kwargs})"
         )
+
+    def test_cmd_help_order(self):
+        buffer = StringIO()
+        cmd = get_command("order", TyperCommand, stdout=buffer, no_color=True)
+
+        cmd.print_help("./manage.py", "order")
+        hlp = buffer.getvalue()
+
+        self.assertTrue(
+            """
+╭─ Commands ───────────────────────────────────────────────────────────────────╮
+│ order                                                                        │
+│ b                                                                            │
+│ a                                                                            │
+│ d                                                                            │
+│ c                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+        """.strip()
+            in hlp
+        )
+
+        buffer.seek(0)
+        buffer.truncate()
+
+        cmd.print_help("./manage.py", "order", "d")
+        hlp = buffer.getvalue()
+
+        self.assertTrue(
+            """
+╭─ Commands ───────────────────────────────────────────────────────────────────╮
+│ g                                                                            │
+│ e                                                                            │
+│ f                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+        """.strip()
+            in hlp
+        )
+
+        cmd2 = get_command("order2", TyperCommand, stdout=buffer, no_color=True)
+
+        buffer.seek(0)
+        buffer.truncate()
+
+        cmd2.print_help("./manage.py", "order2")
+        hlp = buffer.getvalue()
+
+        self.assertTrue(
+            """
+╭─ Commands ───────────────────────────────────────────────────────────────────╮
+│ order2   Override handle                                                     │
+│ b                                                                            │
+│ a                                                                            │
+│ d                                                                            │
+│ c                                                                            │
+│ bb                                                                           │
+│ aa                                                                           │
+╰──────────────────────────────────────────────────────────────────────────────╯
+        """.strip()
+            in hlp
+        )
+
+        buffer.seek(0)
+        buffer.truncate()
+
+        cmd2.print_help("./manage.py", "order2", "d")
+        hlp = buffer.getvalue()
+
+        self.assertTrue(
+            """
+╭─ Commands ───────────────────────────────────────────────────────────────────╮
+│ g                                                                            │
+│ e                                                                            │
+│ f                                                                            │
+│ i                                                                            │
+│ h                                                                            │
+│ x                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+        """.strip()
+            in hlp
+        )
+
+        buffer.seek(0)
+        buffer.truncate()
+
+        cmd2.print_help("./manage.py", "order2", "d", "x")
+        hlp = buffer.getvalue()
+
+        self.assertTrue(
+            """
+╭─ Commands ───────────────────────────────────────────────────────────────────╮
+│ z                                                                            │
+│ y                                                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+        """.strip()
+            in hlp
+        )