Skip to main content

Use Typer to define the CLI for your Django management commands.

Project description

django-typer

License: MIT Ruff PyPI version PyPI pyversions PyPI djversions PyPI status Documentation Status Code Cov Test Status Lint Status Published on Django Packages

Use static typing to define the CLI for your Django management commands with Typer. Optionally use the provided TyperCommand class that inherits from BaseCommand. This class maps the Typer interface onto a class based interface that Django developers will be familiar with. All of the BaseCommand functionality is inherited, so that TyperCommand can be a drop in replacement.

django-typer makes it easy to:

Please refer to the full documentation for more information.

django-typer example

🚨 Upgrade Notice

There are breaking changes between 2.x and 3.x, mostly involving shell tab completion. See the changelog for migration steps.

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. Optionally 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 shell completion 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

TyperCommand is a drop in extension to BaseCommand. All of the documented features of BaseCommand work the same way!

from django_typer.management 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
        """

Or, you may also use an interface identical to Typer's. Simply import Typer from django_typer instead of typer.

from django_typer.management import Typer

app = Typer()

@app.command()
def main(arg1: str, arg2: str, arg3: float = 0.5, arg4: int = 1):
   """
   A basic command that uses Typer
   """

Basic Example

Multiple Subcommands Example

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.management 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.
         """

Or using the typer-style interface this could be written:

from django_typer.management import Typer
import typing as t

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

app = Typer(help="A command that defines subcommands.")

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

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

Multiple Subcommands Example Multiple Subcommands Example - create Multiple Subcommands Example - delete

Grouping and Hierarchies Example

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
./manage.py hierarchy math multiply 10 2

Using the class-based interface we could define the command like this:

   import typing as t
   from functools import reduce

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

   from django_typer.management 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

      # helps can be passed to the decorators
      @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}"

      # or if no help is supplied to the decorators, the docstring if present
      # will be used!
      @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}"

The typer-style interface builds a TyperCommand class for us that allows you to optionally accept the self argument in your commands. We could define the above command using the typer interface like this:

import typing as t
from functools import reduce

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

from django_typer.management import Typer


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


math_grp = Typer(help=_("Do some math at the given precision."))

app.add_typer(math_grp, name="math")

@math_grp.callback()
def math(
   self,
   precision: t.Annotated[
      int, Option(help=_("The number of decimal places to output."))
   ] = 2,
):
   self.precision = precision


@math_grp.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_grp.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}"

Grouping and Hierarchies Example Grouping and Hierarchies Example - math Grouping and Hierarchies Example - math multiply Grouping and Hierarchies Example - math divide

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_typer-3.2.0.tar.gz (2.9 MB view details)

Uploaded Source

Built Distribution

django_typer-3.2.0-py3-none-any.whl (295.6 kB view details)

Uploaded Python 3

File details

Details for the file django_typer-3.2.0.tar.gz.

File metadata

  • Download URL: django_typer-3.2.0.tar.gz
  • Upload date:
  • Size: 2.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for django_typer-3.2.0.tar.gz
Algorithm Hash digest
SHA256 9c4bfb3b8fbc9f49c5e847994ce8ea2130052e4207f8b0e6edd2ebcf743a8cc3
MD5 a1cb6a4b02be5fd66484e987c5c8380c
BLAKE2b-256 f724606d027e7dab212eb5c27abaf3f1259eb6ecbb015eaa165d1aac2df1c167

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_typer-3.2.0.tar.gz:

Publisher: release.yml on django-commons/django-typer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file django_typer-3.2.0-py3-none-any.whl.

File metadata

  • Download URL: django_typer-3.2.0-py3-none-any.whl
  • Upload date:
  • Size: 295.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for django_typer-3.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 e9727ac3ffc24cc2fc954a3a4b1c710552240692cc3bb21f1b7725c45c3d6de7
MD5 cea8b736f9f9d5b68908619395e84d99
BLAKE2b-256 abf38d95ee14d4c5120584a45aadbcd3b93e32c52f2774c9f4fc1e134b82a561

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_typer-3.2.0-py3-none-any.whl:

Publisher: release.yml on django-commons/django-typer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page