Tutorial: Building Commands

Using the TyperCommand class is very similar to using the BaseCommand class. The main difference is that we use Typer’s decorators, classes and type annotations to define the command’s command line interface instead of argparse as BaseCommand expects.

Upstream Libraries

django-typer merges the Django BaseCommand interface with the Typer interface and Typer itself is built on top of click. This means when using django-typer you will encounter interfaces and concepts from all three of these upstream libraries:

• BaseCommand

  Django has a good tutorial for understanding how commands are organized and built in Django. If you are unfamiliar with using BaseCommand please first work through the polls Tutorial in the Django documentation.

• Typer

  This tutorial can be completed without working through the Typer tutorials, but familiarizing yourself with Typer will make this easier and will also be helpful when you want to define CLIs outside of Django! We use the Typer interface to define Arguments and Options so please refer to the Typer documentation for any questions about how to define these.

• click

  Click interfaces and concepts are relatively hidden by Typer, but occasionally you may need to refer to the click documentation when you want to implement more complex behaviors like passing context parameters. It is not necessary to familiarize yourself with click to use django-typer, but you should know that it exists and is the engine behind much of this functionality.

Install django-typer

1. Install the latest release off PyPI :

   pip install "django-typer[rich]"
   

   rich is a powerful library for rich text and beautiful formatting in the terminal. It is not required, but highly recommended for the best experience:

2. Add django_typer to your INSTALLED_APPS setting:

   INSTALLED_APPS = [
       ...
       'django_typer',
   ]
   

   Note

   Adding django_typer to INSTALLED_APPS is not strictly necessary if you do not wish to use shell tab completions or configure rich traceback rendering. Refer to the how-to if you would like to disable it.

Convert the closepoll command to a TyperCommand

Recall our closepoll command from the polls Tutorial in the Django documentation looks like this:

from django.core.management.base import BaseCommand, CommandError

from polls.models import Question as Poll


class Command(BaseCommand):
    help = "Closes the specified poll for voting"

    def add_arguments(self, parser):
        parser.add_argument("poll_ids", nargs="+", type=int)

        # Named (optional) arguments
        parser.add_argument(
            "--delete",
            action="store_true",
            help="Delete poll instead of closing it",
        )

    def handle(self, *args, **options):
        for poll_id in options["poll_ids"]:
            try:
                poll = Poll.objects.get(pk=poll_id)
            except Poll.DoesNotExist:
                raise CommandError('Poll "%s" does not exist' % poll_id)

            poll.opened = False
            poll.save()

            self.stdout.write(
                self.style.SUCCESS('Successfully closed poll "%s"' % poll_id)
            )

            if options["delete"]:
                poll.delete()

Inherit from TyperCommand

We first need to change the inheritance to TyperCommand and then move the argument and option definitions from add_arguments into the method signature of handle. A minimal conversion may look like this:

Django-styleTyper-style

import typing as t

from django.core.management.base import CommandError

from django_typer.management import TyperCommand
from polls.models import Question as Poll


class Command(TyperCommand):
    help = "Closes the specified poll for voting"

    def handle(
        self,
        poll_ids: t.List[int],
        delete: bool = False,
    ):
        for poll_id in poll_ids:
            try:
                poll = Poll.objects.get(pk=poll_id)
            except Poll.DoesNotExist:
                raise CommandError(f'Poll "{poll_id}" does not exist')

            poll.opened = False
            poll.save()

            self.stdout.write(
                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
            )

            if delete:
                poll.delete()

You’ll note that we’ve removed add_arguments entirely and specified the arguments and options as parameters to the handle method. django-typer will interpret the parameters on the handle() method as the command line interface for the command. If we have rich installed the help for our new closepoll command will look like this:

Note

TyperCommand adds the standard set of default options to the command line interface, with the exception of verbosity.

Add Helps with Type annotations

Typer allows us to use Annotated types to add additional controls to how the command line interface behaves. The most common use case for this is to add help text to the command line interface. We will annotate our parameter type hints with one of two Typer parameter types, either Argument or Option. Arguments are positional parameters and Options are named parameters (i.e. –delete). In our polls example, the poll_ids are arguments and the delete flag is an option. Here is what that would look like:

Django-styleTyper-style

class Command(TyperCommand):
    help = "Closes the specified poll for voting"

    def handle(
        self,
        poll_ids: t.Annotated[
            t.List[int],
            Argument(help=_("The database IDs of the poll(s) to close.")),
        ],
        delete: t.Annotated[
            bool, Option(help=_("Delete poll instead of closing it."))
        ] = False,
    ):

See that our help text now shows up in the command line interface. Also note, that lazy translations work for the help strings. Typer also allows us to specify our help text in the docstrings of the command function or class, in this case either Command or handle() - but docstrings are not available to the translation system. If translation is not necessary and your help text is extensive or contains markup the docstring may be the more appropriate place to put it.

Defining custom and reusable parameter types

We may have other commands that need to operate on Poll objects from given poll ids. We could duplicate our for loop that loads Poll objects from ids, but that wouldn’t be very DRY. Instead, Typer allows us to define custom parsers for arbitrary parameter types. Lets see what that would look like if we used the Poll class as our type hint:

Django-styleTyper-style

def get_poll_from_id(poll: t.Union[str, Poll]) -> Poll:
    if isinstance(poll, Poll):
        return poll
    try:
        return Poll.objects.get(pk=int(poll))
    except Poll.DoesNotExist:
        raise CommandError(f'Poll "{poll}" does not exist')


class Command(TyperCommand, rich_markup_mode="markdown"):
    def handle(
        self,
        polls: t.Annotated[
            t.List[Poll],
            Argument(
                parser=get_poll_from_id,
                help=_("The database IDs of the poll(s) to close."),
            ),
        ],
        delete: t.Annotated[
            bool,
            Option(
                # we can also get rid of that unnecessary --no-delete flag
                "--delete",
                help=_("Delete poll instead of closing it."),
            ),
        ] = False,
    ):
        """
        :sparkles: As mentioned in the last section, helps can also be set in
        the docstring and rendered using either
        [rich](https://rich.readthedocs.io/en/stable/markup.html)
        or [markdown](https://www.markdownguide.org/) :sparkles:
        """
        for poll in polls:
            poll.opened = False
            poll.save()
            self.stdout.write(
                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
            )
            if delete:
                poll.delete()

django-typer offers some built-in parsers that can be used for common Django types. For example, the ModelObjectParser can be used to fetch a model object from a given field. By default it will use the primary key, so we could rewrite the relevant lines above like so:

from django_typer.parsers import ModelObjectParser

# ...

t.Annotated[
    t.List[Poll],
    Argument(
        parser=ModelObjectParser(Poll),
        help=_("The database IDs of the poll(s) to close.")
    )
]

# ...

Add shell tab-completion suggestions for polls

It’s very annoying to have to know the database primary key of the poll to close it. django-typer makes it easy to add tab completion suggestions! You can always implement your own completer functions, but as with, parsers, there are some out-of-the-box completers that make this easy. Let’s see what the relevant updates to our closepoll command would look like:

from django_typer.parsers import ModelObjectParser
from django_typer.completers import ModelObjectCompleter

# ...

t.Annotated[
    t.List[Poll],
    Argument(
        parser=ModelObjectParser(Poll),
        shell_complete=ModelObjectCompleter(Poll, help_field='question_text'),
        help=_("The database IDs of the poll(s) to close.")
    )
]

# ...

Note

For tab-completions to work you will need to install the shell completion scripts for your shell.

Putting it all together

When we’re using a ModelObjectParser and ModelObjectCompleter we can use the model_parser_completer() convenience function to reduce the amount of boiler plate. Let’s put everything together and see what our full-featured refactored closepoll command looks like:

Django-styleTyper-style

import typing as t

from django.utils.translation import gettext_lazy as _
from typer import Argument, Option

from django_typer.management import TyperCommand, model_parser_completer
from polls.models import Question as Poll


class Command(TyperCommand):
    help = _("Closes the specified poll for voting.")

    def handle(
        self,
        polls: t.Annotated[
            t.List[Poll],
            Argument(
                **model_parser_completer(Poll, help_field="question_text"),
                help=_("The database IDs of the poll(s) to close."),
            ),
        ],
        delete: t.Annotated[
            bool,
            Option(help=_("Delete poll instead of closing it.")),
        ] = False,
    ):
        for poll in polls:
            poll.opened = False
            poll.save()
            self.stdout.write(
                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
            )
            if delete:
                poll.delete()