more reference doc work, move command help docs to reference and remove commands page

Author: bckohan

django_typer/completers.py

@@ -1,8 +1,21 @@
 """
-A collection of completer classes that can be used to quickly add shell completion
-for various kinds of django objects.
+Typer_ and click_ provide tab-completion hooks for individual parameters. As with
+:mod:`~django_typer.parsers` custom completion logic can be implemented for custom
+parameter types and added to the annotation of the parameter. Previous versions of
+Typer_ supporting click_ 7 used the autocompletion argument to provide completion
+logic, Typer_ still supports this, but passing ``shell_complete`` to the annotation is
+the preferred way to do this.
+
+This module provides some completer functions and classes that work with common Django_
+types:
+
+- **Model Objects**: Complete model object field strings using :class:`ModelObjectCompleter`.
+- **App Labels**: Complete app labels or names using :func:`complete_app_label`.
+
 """
 
+# pylint: disable=line-too-long
+
 import typing as t
 from types import MethodType
 from uuid import UUID
@@ -27,11 +40,59 @@
 class ModelObjectCompleter:
     """
     A completer for generic Django model objects. This completer will work
-    for any Django core model field where completion makes sense. For example,
-    it will work for IntegerField, CharField, TextField, and UUIDField, but
-    not for ForeignKey, ManyToManyField or BinaryField.
+    for most Django core model field types where completion makes sense.
+
+    This completer currently supports the following field types and their subclasses:
+
+        - `IntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#integerfield>`_
+            - `AutoField <https://docs.djangoproject.com/en/stable/ref/models/fields/#autofield>`_
+            - `BigAutoField <https://docs.djangoproject.com/en/stable/ref/models/fields/#bigautofield>`_
+            - `BigIntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#bigintegerfield>`_
+            - `SmallIntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#smallintegerfield>`_
+            - `PositiveIntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#positiveintegerfield>`_
+            - `PositiveSmallIntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield>`_
+            - `SmallAutoField <https://docs.djangoproject.com/en/stable/ref/models/fields/#smallautofield>`_
+        - `CharField <https://docs.djangoproject.com/en/stable/ref/models/fields/#charfield>`_
+            - `SlugField <https://docs.djangoproject.com/en/stable/ref/models/fields/#slugfield>`_
+            - `URLField <https://docs.djangoproject.com/en/stable/ref/models/fields/#urlfield>`_
+            - `EmailField <https://docs.djangoproject.com/en/stable/ref/models/fields/#emailfield>`_
+        - `TextField <https://docs.djangoproject.com/en/stable/ref/models/fields/#textfield>`_
+        - `UUIDField <https://docs.djangoproject.com/en/stable/ref/models/fields/#uuidfield>`_
+        - `FloatField <https://docs.djangoproject.com/en/stable/ref/models/fields/#floatfield>`_
+        - `DecimalField <https://docs.djangoproject.com/en/stable/ref/models/fields/#decimalfield>`_
+
+    The completer query logic is pluggable, but the defaults cover most use cases. The
+    limit field is important. It defaults to 50 meaning if more than 50 potential completions
+    are found only the first 50 will be returned and there will be no indication to the user
+    that there are more. This is to prevent the shell from becoming unresponsive when offering
+    completion for large tables.
+
+    To use this completer, pass an instance of this class to the `shell_complete`
+    argument of a typer.Option or typer.Argument:
+
+    .. code-block:: python
+
+        from django_typer.completers import ModelObjectCompleter
+
+        class Command(TyperCommand):
+
+            def handle(
+                self,
+                model_obj: Annotated[
+                    MyModel,
+                    typer.Argument(
+                        shell_complete=ModelObjectCompleter(MyModel, lookup_field="name"),
+                        help=_("The model object to use.")
+                    )
+                ]
+            ):
+                ...
+
+    .. note::
 
-    The completer query logic is pluggable, but the defaults cover most use cases.
+        See also :func:`~django_typer.model_parser_completer` for a convenience
+        function that returns a configured parser and completer for a model object
+        and helps reduce boilerplate.
 
     :param model_cls: The Django model class to query.
     :param lookup_field: The name of the model field to use for lookup.
@@ -274,7 +335,7 @@ def __call__(
 
 def complete_app_label(ctx: Context, param: Parameter, incomplete: str):
     """
-    A case-insensitive completer for Django app labels or names. The completer
+    A case-sensitive completer for Django app labels or names. The completer
     prefers labels but names will also work.
 
     .. code-block:: python

django_typer/management/commands/shellcompletion.py

@@ -1,20 +1,27 @@
 """
-The shellcompletion command is a Django management command that installs and removes
+The shellcompletion command is a Django_ management command that installs and removes
 shellcompletion scripts for supported shells (bash, fish, zsh, powershell). This
 command is also the entry point for running the completion logic and can be used to
 debug completer code.
 
-It invokes typer's shell completion installation logic, but does have to patch the
-installed scripts. This is because there is only one installation for all django
-management commands, not each individual command. The completion logic here will
-failover to django's builtin autocomplete if the command in question is not a
-TyperCommand. To promote compatibility with other management command libraries or
-custom completion logic, a fallback completion function can also be specified. A
-needed refactoring here would be to provide root hooks for completion logic in django
-that base classes can register for. This would provide a coordinated way for libraries
-like django-typer to plug in their own completion logic.
+.. typer:: django_typer.management.commands.shellcompletion.Command:typer_app
+    :prog: manage.py shellcompletion
+    :width: 80
+    :convert-png: latex
+
+:func:`~django_typer.management.commands.shellcompletion.Command.install` invokes typer's shell
+completion installation logic, but does have to patch the installed scripts. This is because
+there is only one installation for all Django_ management commands, not each individual command.
+The completion logic here will failover to Django_'s builtin autocomplete if the command in
+question is not a :class:`~django_typer.TyperCommand`. To promote compatibility with other
+management command libraries or custom completion logic, a fallback completion function can also
+be specified.
 """
 
+# A needed refactoring here would be to provide root hooks for completion logic in Django core that
+# base classes can register for. This would provide a coordinated way for libraries like
+# django-typer to plug in their own completion logic.
+
 import contextlib
 import inspect
 import io
@@ -62,9 +69,9 @@ class Command(TyperCommand):
     This command installs autocompletion for the current shell. This command uses the typer/click
     autocompletion scripts to generate the autocompletion items, but monkey patches the scripts
     to invoke our bundled shell complete script which fails over to the django autocomplete
-    function when the command being completed is not a TyperCommand. When the django autocomplete
-    function is used we also wrap it so that it works for any supported click/typer shell, not just
-    bash.
+    function when the command being completed is not a :class:`~django_typer.TyperCommand`. When
+    the django autocomplete function is used we also wrap it so that it works for any supported
+    click/typer shell, not just bash.
 
     We also provide a remove command to easily remove the installed script.
 
@@ -290,7 +297,11 @@ def install(
         Install autocompletion for the given shell. If the shell is not specified, it will
         try to detect the shell. If the shell is not detected, it will fail.
 
-        We run the upstream typer installation routines.
+        We run the upstream typer installation routines, with some augmentation.
+
+        .. typer:: django_typer.management.commands.shellcompletion.Command:typer_app:install
+            :width: 85
+            :convert-png: latex
         """
         # do not import this private stuff until we need it - avoids tanking the whole
         # library if these imports change
@@ -336,6 +347,12 @@ def remove(
 
         Since the installation routine is upstream we first run install to determine where the
         completion script is installed and then we remove it.
+
+        .. typer:: django_typer.management.commands.shellcompletion.Command:typer_app:remove
+            :prog: shellcompletion
+            :width: 80
+            :convert-png: latex
+
         """
         # do not import this private stuff until we need it - avoids tanking the whole
         # library if these imports change
@@ -436,7 +453,22 @@ def complete(
         """
         We implement the shell complete generation script as a Django command because the
         Django environment needs to be bootstrapped for it to work. This also allows
-        us to test autocompletions in a platform agnostic way.
+        us to test completion logic in a platform agnostic way.
+
+        .. tip::
+
+            This command is super useful for debugging shell_complete logic. For example to
+            enter into the debugger, we could set a breakpoint in our ``shell_complete`` function
+            for the option parameter and then run the following command:
+
+            .. code-block:: bash
+
+                $ ./manage.py shellcompletion complete "./manage.py your_command --option "
+
+        .. typer:: django_typer.management.commands.shellcompletion.Command:typer_app:complete
+            :prog: shellcompletion
+            :width: 80
+            :convert-png: latex
         """
         os.environ[self.COMPLETE_VAR] = (
             f"complete_{shell.value}"

django_typer/parsers.py

@@ -25,19 +25,44 @@
 import typing as t
 from uuid import UUID
 
-from click import Parameter, ParamType, Context
+from click import Context, Parameter, ParamType
 from django.apps import AppConfig, apps
 from django.core.exceptions import ObjectDoesNotExist
 from django.core.management import CommandError
 from django.db.models import Field, Model, UUIDField
 from django.utils.translation import gettext as _
 
+from django_typer.completers import ModelObjectCompleter
+
 
 class ModelObjectParser(ParamType):
     """
     A parser that will turn strings into model object instances based on the
     configured lookup field and model class.
 
+    .. code-block:: python
+
+        from django_typer.parsers import ModelObjectParser
+
+        class Command(TyperCommand):
+            def handle(
+                self,
+                django_apps: Annotated[
+                    t.List[MyModel],
+                    typer.Argument(
+                        parser=ModelObjectParser(MyModel, lookup_field="name"),
+                        help=_("One or more application labels."),
+                    ),
+                ],
+            ):
+
+    .. note::
+
+        Typer_ does not respect the shell_complete functions on ParamTypes passed as
+        parsers. To add shell_completion see :class:`~django_typer.completers.ModelObjectCompleter`
+        or the :func:`~django_typer.model_parser_completer` convenience
+        function.
+
     :param model_cls: The model class to use for lookup.
     :param lookup_field: The field to use for lookup. Defaults to 'pk'.
     :param on_error: A callable that will be called if the lookup fails.
@@ -55,6 +80,7 @@ class ModelObjectParser(ParamType):
 
     _lookup = ""
     _field: Field
+    _completer: ModelObjectCompleter
 
     __name__ = "ModelObjectParser"  # typer internals expect this
 

django_typer/patch.py

@@ -1,5 +1,5 @@
 """
-Stuffing the typer interface into the Django BaseCommand interface is an exercise
+Stuffing the typer interface into the Django BaseCommand_ interface is an exercise
 in fitting a square peg into a round hole. A small amount of upstream patching is
 required to make this work. All monkey patching is defined in this module to more
 easily keep track of it.

django_typer/utils.py

@@ -1,7 +1,5 @@
 """
-A context manager that can be used to determine if we're executing inside of
-a Typer command. This is analogous to click's get_current_context but for
-command execution.
+A collection of useful utilities.
 """
 
 import typing as t
@@ -40,6 +38,9 @@ def get_current_command() -> t.Optional["TyperCommand"]:  # type: ignore
 
     This function is thread safe.
 
+    This is analogous to click's get_current_context but for
+    command execution.
+
     :return: The current typer command or None if there is no active command.
     """
     try:

doc/source/commands.rst

@@ -128,6 +128,5 @@ for arbitrarily complex command hierarchies.
    tutorial
    howto
    shell_completion
-   commands
    reference
    changelog

doc/source/index.rst

@@ -40,7 +40,7 @@ for django commands we need to register our completion logic for Django manage s
 the shell. This process has two phases:
 
 1. Ensure that your shell is configured to support completions.
-2. Use the :ref:`shellcompletion <shellcompletion-command>` command to install the completion
+2. Use the :mod:`~django_typer.management.commands.shellcompletion` command to install the completion
    hook for your Django manage script.
 
 
@@ -89,7 +89,7 @@ had luck with the following:
 Install the Completion Hook
 ---------------------------
 
-django-typer_ comes with a management command called :ref:`shellcompletion <shellcompletion-command>`.
+django-typer_ comes with a management command called :mod:`~django_typer.management.commands.shellcompletion`.
 To install completions for your Django project simply run the install command:
 
 .. code-block:: bash
@@ -104,7 +104,8 @@ To install completions for your Django project simply run the install command:
 
 The installation script should be able to automatically detect your shell and install the appropriate
 scripts. If it is unable to do so you may force it to install for a specific shell by passing the
-shell name as an argument. Refer to the :ref:`command help <shellcompletion-command>` for details.
+shell name as an argument. Refer to the :mod:`~django_typer.management.commands.shellcompletion`
+for details.
 
 **After installation you will probably need to restart your shell or source the appropriate rc file.**