a few more completers, flush out documentation

Author: bckohan

django_typer/__init__.py

@@ -2585,7 +2585,7 @@ def initialize(
         Override the initializer for this command class after it has been defined.
 
         .. note::
-            See :ref:`extensions` for details on when you might want to use this extension
+            See :ref:`plugins` for details on when you might want to use this extension
             pattern.
 
         .. code-block:: python
@@ -2696,7 +2696,7 @@ def command(
         use this decorator to add commands to a root command from other Django apps.
 
         .. note::
-            See :ref:`extensions` for details on when you might want to use this extension
+            See :ref:`plugins` for details on when you might want to use this extension
             pattern.
 
         .. code-block:: python
@@ -2794,7 +2794,7 @@ def group(
         use this decorator to add groups to a root command from other Django apps.
 
         .. note::
-            See :ref:`extensions` for details on when you might want to use this extension
+            See :ref:`plugins` for details on when you might want to use this extension
             pattern.
 
         .. code-block:: python

django_typer/completers.py

@@ -30,6 +30,7 @@
 from click.shell_completion import CompletionItem
 from django.apps import apps
 from django.conf import settings
+from django.core.management import get_commands
 from django.db.models import (
     CharField,
     DecimalField,
@@ -44,6 +45,9 @@
     UUIDField,
 )
 
+Completer = t.Callable[[Context, Parameter, str], t.List[CompletionItem]]
+Strings = t.Union[t.Sequence[str], t.KeysView[str], t.Generator[str, None, None]]
+
 
 class ModelObjectCompleter:
     """
@@ -515,7 +519,7 @@ def exists(pth: Path) -> bool:
 
 
 def these_strings(
-    strings: t.Union[t.Callable[[], t.Sequence[str]], t.Sequence[str]],
+    strings: t.Union[t.Callable[[], Strings], Strings],
     allow_duplicates: bool = False,
 ):
     """
@@ -545,8 +549,75 @@ def complete(ctx: Context, param: Parameter, incomplete: str):
 
 
 # use a function that returns a generator because we should not access settings on import
-databases = these_strings(lambda: settings.DATABASES.keys())
+databases = partial(these_strings, lambda: settings.DATABASES.keys())
+"""
+A completer that completes Django database aliases configured in settings.DATABASES.
+
+:param allow_duplicates: Whether or not to allow duplicate values. Defaults to False.
+:return: A completer function.
+"""
+
+commands = partial(these_strings, lambda: get_commands().keys())
 """
-A completer that provides completion logic for the Django database aliases
-configured in settings.DATABASES.
+A completer that completes management command names.
+
+:param allow_duplicates: Whether or not to allow duplicate values. Defaults to False.
+:return: A completer function.
 """
+
+
+def chain(
+    completer: Completer,
+    *completers: Completer,
+    first_match: bool = False,
+    allow_duplicates: bool = False,
+):
+    """
+    Run through the given completers and return the items from the first one, or all
+    of them if first_match is False.
+
+    .. note::
+
+        This function is also useful for filtering out previously supplied duplicate
+        values for completers that do not natively support that:
+
+        .. code-block:: python
+
+            shell_complete=chain(
+                complete_import_path,
+                allow_duplicates=False
+            )
+
+    :param completer: The first completer to use (must be at least one!)
+    :param completers: The completers to use
+    :param first_match: If true, return only the matches from the first completer that
+        finds completions. Default: False
+    :param allow_duplicates: If False (default) remove completions from previously provided
+        values.
+    """
+
+    def complete(ctx: Context, param: Parameter, incomplete: str):
+        completions = []
+        present = []
+        if (
+            not allow_duplicates
+            and param.name
+            and ctx.get_parameter_source(param.name) is not ParameterSource.DEFAULT
+        ):
+            present = [value for value in (ctx.params.get(param.name) or [])]
+        for cmpltr in [completer, *completers]:
+            completions.extend(cmpltr(ctx, param, incomplete))
+            if first_match and completions:
+                break
+
+        # eliminate duplicates
+        return list(
+            {
+                ci.value: ci
+                for ci in completions
+                if ci.value
+                if ci.value not in present
+            }.values()
+        )
+
+    return complete

django_typer/tests/apps/adapter0/apps.py

@@ -4,7 +4,7 @@
 
 class Adapter1Config(AppConfig):
     name = "django_typer.tests.apps.adapter0"
-    label = name.replace(".", "_")
+    label = "adapter0"
     verbose_name = "Adapter 0"
 
     def ready(self):

django_typer/tests/apps/adapter1/apps.py

@@ -4,7 +4,7 @@
 
 class Adapter1Config(AppConfig):
     name = "django_typer.tests.apps.adapter1"
-    label = name.replace(".", "_")
+    label = "adapter1"
     verbose_name = "Adapter 1"
 
     def ready(self):

django_typer/tests/apps/adapter2/apps.py

@@ -4,7 +4,7 @@
 
 class Adapter2Config(AppConfig):
     name = "django_typer.tests.apps.adapter2"
-    label = name.replace(".", "_")
+    label = "adapter2"
     verbose_name = "Adapter 2"
 
     def ready(self):

django_typer/tests/apps/howto/management/commands/howto1.py

@@ -1,11 +1,11 @@
 from ..commands.upstream2_typer import app
 
-# do not create a new app as with inheritance - just
-# work directly with the upstream app.
+# do not create a new app as with inheritance -
+# instead work directly with the upstream app.
 
 
 # override init
-@app.initialize()
+@app.callback()
 def init():
     return "plugin:init"
 

django_typer/tests/apps/howto/management/commands/howto3.py

@@ -21,7 +21,7 @@ def test_check(app_configs, **kwargs):
 
 class TestAppConfig(AppConfig):
     name = "django_typer.tests.apps.test_app"
-    label = name.replace(".", "_")
+    label = "test_app"
     verbose_name = "Test App"
 
     def ready(self):

django_typer/tests/apps/howto/management/plugins/upstream2_typer.py

@@ -59,6 +59,28 @@ def handle(
                 ),
             ),
         ] = None,
+        commands: t.Annotated[
+            t.List[str],
+            typer.Option(
+                "--cmd",
+                help=_("A command by import path or name."),
+                shell_complete=completers.chain(
+                    completers.complete_import_path, completers.commands()
+                ),
+            ),
+        ] = [],
+        command_dups: t.Annotated[
+            t.List[str],
+            typer.Option(
+                "--cmd-dup",
+                help=_("A list of commands by import path or name."),
+                shell_complete=completers.chain(
+                    completers.complete_import_path,
+                    completers.commands(allow_duplicates=True),
+                    allow_duplicates=True,
+                ),
+            ),
+        ] = [],
     ):
         assert self.__class__ is Command
         for app in django_apps: