From c0c5a5a1e3aaf5e4793fc0681e4fe55b83e03eb2 Mon Sep 17 00:00:00 2001 From: Brian Kohan Date: Wed, 3 Apr 2024 14:46:14 -0700 Subject: [PATCH] convert readme to make docs, fixes #48 --- README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..558356b --- /dev/null +++ b/README.md @@ -0,0 +1,135 @@ +# django-typer + +![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)(https://lbesson.mit-license.org/) +![PyPI version](https://badge.fury.io/py/django-typer.svg)(https://pypi.python.org/pypi/django-typer/) +![PyPI pyversions](https://img.shields.io/pypi/pyversions/django-typer.svg)(https://pypi.python.org/pypi/django-typer/) +![PyPI djversions](https://img.shields.io/pypi/djversions/django-typer.svg)(https://pypi.org/project/django-typer/) +![PyPI status](https://img.shields.io/pypi/status/django-typer.svg)(https://pypi.python.org/pypi/django-typer) +![Documentation Status](https://readthedocs.org/projects/django-typer/badge/?version=latest)(http://django-typer.readthedocs.io/?badge=latest/) +![Code Cov](https://codecov.io/gh/bckohan/django-typer/branch/main/graph/badge.svg?token=0IZOKN2DYL)(https://codecov.io/gh/bckohan/django-typer) +![Test Status](https://github.com/bckohan/django-typer/workflows/test/badge.svg)(https://github.com/bckohan/django-typer/actions/workflows/test.yml) +![Lint Status](https://github.com/bckohan/django-typer/workflows/lint/badge.svg)(https://github.com/bckohan/django-typer/actions/workflows/lint.yml) +![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)(https://github.com/psf/black) + +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. + +Please refer to the [full documentation](https://django-typer.readthedocs.io/) for more information. + +![django-typer example](https://raw.githubusercontent.com/bckohan/django-typer/main/doc/source/_static/img/closepoll_example.gif) + +## Installation + +1. Clone django-typer from GitHub or install a release off [PyPI](https://pypi.org/project/django-typer/): + + ```bash + pip install django-typer + ``` + + [rich](https://rich.readthedocs.io/en/latest/) is a powerful library for rich text and beautiful formatting in the terminal. It is not required but highly recommended for the best experience: + + ```bash + pip install "django-typer[rich]" + ``` + +2. Add `django_typer` to your `INSTALLED_APPS` setting: + + ```python + 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 + +For example, TyperCommands can be a very simple drop-in replacement for BaseCommands. All of the documented features of BaseCommand work! + +```python +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 + """ +``` + +![Basic Example](https://raw.githubusercontent.com/bckohan/django-typer/main/django_typer/examples/helps/basic.svg) + +## Multiple Subcommands Example + + + +Commands with multiple subcommands can be defined: + +```python +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): + @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. + """ +``` + +![Multiple Subcommands Example](https://raw.githubusercontent.com/bckohan/django-typer/main/django_typer/examples/helps/multi.svg) + +## 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: + +```bash +./manage.py hierarchy math --precision 5 divide 10 2.1 +./manage.py hierarchy math multiply 10 2 +``` + +```python +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): + @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."))] = 2): + 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: float, denominator: float, floor: bool = False): + """ + Divide the given numbers. + """ + if floor: + return str(numerator // denominator) + return f"{numerator / denominator:.{self.precision}f}" +``` + +![Grouping and Hierarchies Example](https://raw.githubusercontent.com/bckohan/django-typer/main/django_typer/examples/helps/hierarchy.svg)