django-typer 1.0.3

Installation

1. Clone django-typer from GitHub or install a release off PyPI:

   pip install django-typer

   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:

   pip install "django-typer[rich]"

2. Add django_typer to your INSTALLED_APPS setting:

   INSTALLED_APPS = [
       ...
       'django_typer',
   ]

   You only need to install django_typer as an app if you want to use the shellcompletion command to enable tab-completion or if you would like django-typer to install `rich traceback rendering <https://django-typer.readthedocs.io/en/latest/howto.html#configure-rich-stack-traces>`_ for you - which it does by default if rich is also installed.

Basic Example

For example TyperCommands can be a very simple drop in replacement for BaseCommands. All of the documented features of BaseCommand work!

from django_typer import TyperCommand


class Command(TyperCommand):

   def handle(self, arg1: str, arg2: str, arg3: float = 0.5, arg4: int = 1):
      """
      A basic command that uses Typer
      """

Multiple Subcommands Example

Or commands with multiple subcommands can be defined:

import typing as t

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

from django_typer import TyperCommand, command


class Command(TyperCommand):
   """
   A command that defines subcommands.
   """

   @command()
   def create(
      self,
      name: t.Annotated[str, Argument(help=_("The name of the object to create."))],
   ):
      """
      Create an object.
      """

   @command()
   def delete(
      self, id: t.Annotated[int, Argument(help=_("The id of the object to delete."))]
   ):
      """
      Delete an object.
      """

Grouping and Hierarchies Example

Or more complex groups and subcommand hierarchies can be defined. For example this command defines a group of commands called math, with subcommands divide and multiply. The group has a common initializer that optionally sets a float precision value. We would invoke this command like so:

./manage.py hierarchy math --precision 5 divide 10 2.1
4.76190
./manage.py hierarchy math multiply 10 2
20.00

Any number of groups and subcommands and subgroups of other groups can be defined allowing for arbitrarily complex command hierarchies.

import typing as t
from functools import reduce

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

from django_typer import TyperCommand, group


class Command(TyperCommand):

   help = _("A more complex command that defines a hierarchy of subcommands.")

   precision = 2

   @group(help=_("Do some math at the given precision."))
   def math(
      self,
      precision: t.Annotated[
         int, Option(help=_("The number of decimal places to output."))
      ] = precision,
   ):
      self.precision = precision

   @math.command(help=_("Multiply the given numbers."))
   def multiply(
      self,
      numbers: t.Annotated[
         t.List[float], Argument(help=_("The numbers to multiply"))
      ],
   ):
      return f"{reduce(lambda x, y: x * y, [1, *numbers]):.{self.precision}f}"

   @math.command()
   def divide(
      self,
      numerator: t.Annotated[float, Argument(help=_("The numerator"))],
      denominator: t.Annotated[float, Argument(help=_("The denominator"))],
      floor: t.Annotated[bool, Option(help=_("Use floor division"))] = False,
   ):
      """
      Divide the given numbers.
      """
      if floor:
            return str(numerator // denominator)
      return f"{numerator / denominator:.{self.precision}f}"