Django Typer
Use Typer to define the CLI for your Django management commands. Provides a TyperCommand class that inherits from BaseCommand and allows typer-style annotated parameter types. All of the BaseCommand functionality is preserved, so that TyperCommand can be a drop in replacement.
django-typer makes it easy to:
Define your command CLI interface in a clear, DRY and safe way using type hints
Create subcommand and group command hierarchies.
Use the full power of Typer’s parameter types to validate and parse command line inputs.
Create beautiful and information dense help outputs.
Configure the rendering of exception stack traces using rich.
Install shell tab-completion support for TyperCommands and normal Django commands for bash, zsh, fish and powershell.
Create custom and portable shell tab-completions for your CLI parameters.
Refactor existing management commands into TyperCommands because TyperCommand is interface compatible with BaseCommand.
Installation
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]"
Add
django_typer
to yourINSTALLED_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 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!
1from django_typer import TyperCommand
2
3
4class Command(TyperCommand):
5 def handle(self, arg1: str, arg2: str, arg3: float = 0.5, arg4: int = 1):
6 """
7 A basic command that uses Typer
8 """
Multiple Subcommands Example
Or commands with multiple subcommands can be defined:
1import typing as t
2
3from django.utils.translation import gettext_lazy as _
4from typer import Argument
5
6from django_typer import TyperCommand, command
7
8
9class Command(TyperCommand):
10 """
11 A command that defines subcommands.
12 """
13
14 @command()
15 def create(
16 self,
17 name: t.Annotated[str, Argument(help=_("The name of the object to create."))],
18 ):
19 """
20 Create an object.
21 """
22
23 @command()
24 def delete(
25 self, id: t.Annotated[int, Argument(help=_("The id of the object to delete."))]
26 ):
27 """
28 Delete an object.
29 """
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.
1import typing as t
2from functools import reduce
3
4from django.utils.translation import gettext_lazy as _
5from typer import Argument, Option
6
7from django_typer import TyperCommand, group
8
9
10class Command(TyperCommand):
11
12 help = _("A more complex command that defines a hierarchy of subcommands.")
13
14 precision = 2
15
16 @group(help=_("Do some math at the given precision."))
17 def math(
18 self,
19 precision: t.Annotated[
20 int, Option(help=_("The number of decimal places to output."))
21 ] = precision,
22 ):
23 self.precision = precision
24
25 @math.command(help=_("Multiply the given numbers."))
26 def multiply(
27 self,
28 numbers: t.Annotated[
29 t.List[float], Argument(help=_("The numbers to multiply"))
30 ],
31 ):
32 return f"{reduce(lambda x, y: x * y, [1, *numbers]):.{self.precision}f}"
33
34 @math.command()
35 def divide(
36 self,
37 numerator: t.Annotated[float, Argument(help=_("The numerator"))],
38 denominator: t.Annotated[float, Argument(help=_("The denominator"))],
39 floor: t.Annotated[bool, Option(help=_("Use floor division"))] = False,
40 ):
41 """
42 Divide the given numbers.
43 """
44 if floor:
45 return str(numerator // denominator)
46 return f"{numerator / denominator:.{self.precision}f}"
- Tutorial
- How-To
- Define an Argument
- Define an Option
- Define Multiple Subcommands
- Define Multiple Subcommands w/ a Default
- Define Groups of Commands
- Define an Initialization Callback
- Call TyperCommands from Code
- Change Default Django Options
- Configure the Typer Application
- Define Shell Tab Completions for Parameters
- Debug Shell Tab Completers
- Extend/Override TyperCommands
- Configure rich Stack Traces
- Add Help Text to Commands
- Document Commands w/Sphinx
- Shell Tab-Completions
- Reference
- Change Log