fix #203 fix #186

Author: bckohan

doc/source/changelog.rst

@@ -4,16 +4,19 @@
 Change Log
 ==========
 
-v3.1.0 (2024-03-xx)
+v3.1.0 (2024-03-31)
 ===================
 
-* Implemented `Prompt before writing to dotfiles when installing completions <https://github.com/django-commons/django-typer/issues/189>`_
+* Implemented `Add completer for settings names. <https://github.com/django-commons/django-typer/issues/203>`_
 * Fixed `Shell completion tests let failures through in CI <https://github.com/django-commons/django-typer/issues/194>`_
 * Fixed `fish completion installs should respect XDG_CONFIG_HOME <https://github.com/django-commons/django-typer/issues/193>`_
 * Fixed `zsh completion installs should respect ZDOTDIR <https://github.com/django-commons/django-typer/issues/192>`_
+* Implemented `Prompt before writing to dotfiles when installing completions <https://github.com/django-commons/django-typer/issues/189>`_
 * Implemented `Support Django 5.2 <https://github.com/django-commons/django-typer/issues/188>`_
 * Implemented `Use intersphinx for external document references. <https://github.com/django-commons/django-typer/issues/187>`_
+* Implemented `Add completer for language codes. <https://github.com/django-commons/django-typer/issues/186>`_
 * Implemented `Switch poetry -> uv <https://github.com/django-commons/django-typer/issues/185>`_
+* Implemented `Model object completers should handle fields with choices appropriately <https://github.com/django-commons/django-typer/issues/182>`_
 * Implemented `Require tests to pass before release action runs. <https://github.com/django-commons/django-typer/issues/173>`_
 
 

doc/source/conf.py

@@ -11,7 +11,7 @@
 sys.path.append(str(Path(__file__).parent / 'ext'))
 
 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'tests.settings.base')
-settings.configure()
+#settings.configure()
 django.setup()
 
 import django_typer

doc/source/reference/completers.rst

@@ -23,3 +23,6 @@ Completers
 
 .. automodule:: django_typer.completers.path
     :members:
+
+.. automodule:: django_typer.completers.settings
+    :members:

doc/source/reference/shells.rst

@@ -6,6 +6,9 @@
 Shells
 ======
 
+.. automodule:: django_typer.shells
+    :members: DjangoTyperShellCompleter, register_completion_class
+
 .. autoclass:: django_typer.shells.bash.BashComplete
     :members: name, template, color, supports_scripts
 

doc/source/shell_completion.rst

@@ -512,6 +512,38 @@ parameter and the :class:`~django_typer.parsers.model.ReturnType` enumeration:
             ...
 
 
+Fields with Choices
+~~~~~~~~~~~~~~~~~~~
+
+The above examples using :func:`~django_typer.utils.model_parser_completer` will work for fields
+with choices. You may however want to avoid the database lookup given that the choice list is
+readily available. To do this you could use :func:`~django_typer.completers.these_strings` in
+combination with the :class:`~django_typer.parsers.model.ModelObjectParser`:
+
+.. code-block:: python
+
+    from django_typer.parsers.model import ModelObjectParser, ReturnType
+
+    class Command(TyperCommand):
+        def handle(
+            self,
+            query: Annotated[
+                QuerySet[ModelClass],
+                typer.Option(
+                    parser=ModelObjectParser(
+                        ModelClass,
+                        "choice_field,
+                        return_type=ReturnType.QUERY_SET,
+                    ),
+                    shell_complete=these_strings(
+                        ModelClass.FIELD_CHOICES,
+                        allow_duplicates=False,
+                    ),
+                    help="Fetch objects by their choices for field choice_field.",
+                ),
+            ] = ModelClass.objects.none(),
+        ):
+            ...
 
 Completer Chains
 ----------------
@@ -542,6 +574,14 @@ be returned, or only the first completer that generates matches.
         ]
     )
 
+Settings
+--------
+
+A number of completers are provided that complete values involving settings. These include:
+
+* setting: :func:`~django_typer.completers.settings.setting`
+* languages: :func:`~django_typer.completers.settings.languages`
+
 
 Customizing/Adding Shells
 ==========================

src/django_typer/completers/__init__.py

@@ -17,16 +17,20 @@
   :func:`~django_typer.completers.cmd.commands`.
 - **databases**: Complete Django database names using
   :func:`~django_typer.completers.db.databases`.
-- **import paths**: Complete Django database names using
+- **import paths**: Complete python import paths using
   :func:`~django_typer.completers.path.import_paths`.
-- **paths**: Complete Django database names using
+- **paths**: Complete file and directory paths using
   :func:`~django_typer.completers.path.paths`.
-- **directories**: Complete Django database names using
+- **directories**: Complete directories using
   :func:`~django_typer.completers.path.directories`.
 - **media paths**: Complete Django media paths using
   :func:`~django_typer.completers.path.media_paths`.
 - **static paths**: Complete Django static paths using
   :func:`~django_typer.completers.path.static_paths`.
+- **languages**: Complete Django language names using
+  :func:`~django_typer.completers.settings.languages`.
+- **settings**: Complete Django settings variable names using
+  :func:`~django_typer.completers.settings.setting`.
 """
 
 import typing as t
@@ -36,7 +40,15 @@
 from click.shell_completion import CompletionItem
 
 Completer = t.Callable[[Context, Parameter, str], t.List[CompletionItem]]
-Strings = t.Union[t.Sequence[str], t.KeysView[str], t.Generator[str, None, None]]
+
+ItemTuple = t.Union[t.Any, t.Tuple[t.Any, t.Any]]
+Strings = t.Union[
+    t.Sequence[ItemTuple],
+    t.KeysView[t.Any],
+    t.ValuesView[t.Any],
+    t.ItemsView[t.Any, t.Any],
+    t.Generator[ItemTuple, None, None],
+]
 
 
 def these_strings(
@@ -47,25 +59,30 @@ def these_strings(
     Get a completer that provides completion logic that matches the allowed strings.
 
     :param strings: A sequence of allowed strings or a callable that generates a
-        sequence of allowed strings.
+        sequence of allowed strings. If the sequence contains 2-tuples the second
+        element is used as the help text for the completion item.
     :param allow_duplicates: Whether or not to allow duplicate values. Defaults to
         False.
     :return: A completer function.
     """
 
     def complete(ctx: Context, param: Parameter, incomplete: str):
         present = []
+        items = []
         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 [])]
-        return [
-            CompletionItem(item)
-            for item in (strings() if callable(strings) else strings)
-            if item.startswith(incomplete) and item not in present
-        ]
+
+        for item in strings() if callable(strings) else strings:
+            help = None
+            if isinstance(item, tuple):
+                item, help = str(item[0]), str(item[1])
+            if item.startswith(incomplete) and item not in present:
+                items.append(CompletionItem(item, help=help))
+        return items
 
     return complete
 

src/django_typer/completers/settings.py

@@ -0,0 +1,23 @@
+"""
+Completers that complete items involving Django's settings.
+"""
+
+from django.conf import settings
+
+from . import these_strings
+
+setting = these_strings(
+    lambda: (setting for setting in dir(settings) if setting.isupper()),
+    allow_duplicates=False,
+)
+"""
+Completes Django :ref:`ref/settings:settings` names. Duplicates are not allowed.
+"""
+
+languages = these_strings(
+    lambda: getattr(settings, "LANGUAGES", []) or [],
+    allow_duplicates=False,
+)
+"""
+Completes Django language codes using :setting:`LANGUAGES`. Duplicates are not allowed.
+"""

src/django_typer/shells/__init__.py

@@ -15,6 +15,8 @@
 from django.template.loader import TemplateDoesNotExist, get_template
 from django.utils.translation import gettext as _
 
+__all__ = ["DjangoTyperShellCompleter", "register_completion_class"]
+
 if t.TYPE_CHECKING:  # pragma: no cover
     from django_typer.management.commands.shellcompletion import (
         Command as ShellCompletion,

tests/apps/completion/management/commands/completion.py

@@ -18,6 +18,7 @@
     static_paths,
     media_paths,
 )
+from django_typer.completers.settings import setting, languages
 from django_typer.completers.db import databases
 from django_typer.completers.cmd import commands
 from django_typer.completers import these_strings, chain
@@ -158,6 +159,22 @@ def handle(
                 show_default=False,
             ),
         ] = "",
+        languages: Annotated[
+            t.List[str],
+            typer.Option(
+                "--lang",
+                help=t.cast(str, _("One or more languages.")),
+                shell_complete=languages,
+            ),
+        ] = [],
+        setting: Annotated[
+            t.List[str],
+            typer.Option(
+                "--setting",
+                help=t.cast(str, _("One or more Django setting variables.")),
+                shell_complete=setting,
+            ),
+        ] = [],
     ):
         assert self.__class__ is Command
         for app in django_apps: