add typer versions of extensions tutorial

Author: bckohan

django_typer/tests/test_backup_example.py

@@ -16,6 +16,8 @@
 class TestBackupExample(SimpleTestCase):
     databases = {"default"}
 
+    typer = ""
+
     def setUp(self):
         if BACKUP_DIRECTORY.exists():
             shutil.rmtree(BACKUP_DIRECTORY)
@@ -28,7 +30,7 @@ def tearDown(self) -> None:
 
     def test_base_backup(self):
         stdout, stderr, retcode = run_command(
-            "backup",
+            f"backup{self.typer}",
             "--no-color",
             "--settings",
             "django_typer.tests.settings.backup",
@@ -43,7 +45,7 @@ def test_base_backup(self):
         )
 
         stdout, stderr, retcode = run_command(
-            "backup",
+            f"backup{self.typer}",
             "--settings",
             "django_typer.tests.settings.backup",
             "-o",
@@ -56,7 +58,7 @@ def test_base_backup(self):
 
     def test_inherit_backup(self):
         stdout, stderr, retcode = run_command(
-            "backup",
+            f"backup{self.typer}",
             "--no-color",
             "--settings",
             "django_typer.tests.settings.backup_inherit",
@@ -71,7 +73,7 @@ def test_inherit_backup(self):
         self.assertTrue("media(filename=media.tar.gz)" in lines)
 
         stdout, stderr, retcode = run_command(
-            "backup",
+            f"backup{self.typer}",
             "--settings",
             "django_typer.tests.settings.backup_inherit",
             "-o",
@@ -85,7 +87,7 @@ def test_inherit_backup(self):
 
     def test_extend_backup(self):
         stdout, stderr, retcode = run_command(
-            "backup",
+            f"backup{self.typer}",
             "--no-color",
             "--settings",
             "django_typer.tests.settings.backup_ext",
@@ -99,7 +101,7 @@ def test_extend_backup(self):
         self.assertTrue("media(filename=media.tar.gz)" in lines)
 
         stdout, stderr, retcode = run_command(
-            "backup",
+            f"backup{self.typer}",
             "--settings",
             "django_typer.tests.settings.backup_ext",
             "-o",
@@ -113,3 +115,8 @@ def test_extend_backup(self):
         self.assertTrue((BACKUP_DIRECTORY / "media.tar.gz").exists())
         self.assertTrue((BACKUP_DIRECTORY / "requirements.txt").exists())
         self.assertTrue(len(os.listdir(BACKUP_DIRECTORY)) == 3)
+
+
+@pytest.mark.skipif(sys.version_info < (3, 9), reason="requires python3.9 or higher")
+class TestBackupTyperExample(TestBackupExample):
+    typer = "_typer"

doc/source/extensions.rst

@@ -30,11 +30,26 @@ to determine if a subcommand was called in our root initializer callback and we
 subroutines added by extensions at runtime using :func:`~django_typer.TyperCommand.get_subcommand`.
 Our command might look like this:
 
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/backup/management/commands/backup.py
+            :language: python
+            :caption: backup/management/commands/backup.py
+            :linenos:
+            :replace:
+                django_typer.tests.apps.examples.extensions.backup : backup
+
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/backup/management/commands/backup_typer.py
+            :language: python
+            :caption: backup/management/commands/backup.py
+            :linenos:
+            :replace:
+                django_typer.tests.apps.examples.extensions.backup : backup
 
-.. literalinclude:: ../../django_typer/tests/apps/examples/extensions/backup/management/commands/backup.py
-   :language: python
-   :caption: Base Backup Command
-   :linenos:
 
 .. typer:: django_typer.tests.apps.examples.extensions.backup.management.commands.backup.Command:typer_app
     :prog: manage.py backup
@@ -92,11 +107,23 @@ Say our app tree looks like this:
 
 Our backup.py implementation in the media app might look like this:
 
-.. literalinclude:: ../../django_typer/tests/apps/examples/extensions/media1/management/commands/backup.py
-   :language: python
-   :caption: Media Backup Extension
-   :replace:
-        django_typer.tests.apps.examples.extensions.backup : media
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/media1/management/commands/backup.py
+            :language: python
+            :caption: media/management/commands/backup.py
+            :replace:
+                    django_typer.tests.apps.examples.extensions.media1 : media
+
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/media1/management/commands/backup_typer.py
+            :language: python
+            :caption: media/management/commands/backup.py
+            :replace:
+                    django_typer.tests.apps.examples.extensions.media1 : media
 
 Now you'll see we have another command called media available:
 
@@ -221,19 +248,45 @@ this:
 For plugins to work, we'll need to re-mplement media from above as a composed extension
 and that would look like this:
 
-.. literalinclude:: ../../django_typer/tests/apps/examples/extensions/media2/management/extensions/backup.py
-   :language: python
-   :caption: Media Backup Extension
-   :replace:
-        django_typer.tests.apps.examples.extensions.backup : backup
+.. tabs::
+
+    .. tab:: django-typer
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/media2/management/extensions/backup.py
+            :language: python
+            :caption: media/management/extensions/backup.py
+            :replace:
+                    django_typer.tests.apps.examples.extensions.media2 : media
+
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/media2/management/extensions/backup_typer.py
+            :language: python
+            :caption: media/management/extensions/backup.py
+            :replace:
+                    django_typer.tests.apps.examples.extensions.media2 : media
+
+
 
 And our my_app extension might look like this:
 
-.. literalinclude:: ../../django_typer/tests/apps/examples/extensions/my_app/management/extensions/backup.py
-   :language: python
-   :caption: MyApp Backup Extension
-   :replace:
-        django_typer.tests.apps.examples.extensions.backup : backup
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/my_app/management/extensions/backup.py
+            :language: python
+            :caption: my_app/management/extensions/backup.py
+            :replace:
+                    django_typer.tests.apps.examples.extensions.my_app : my_app
+
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/extensions/my_app/management/extensions/backup_typer.py
+            :language: python
+            :caption: my_app/management/extensions/backup.py
+            :replace:
+                    django_typer.tests.apps.examples.extensions.my_app : my_app
 
 Note that we now have a new environment command available:
 

doc/source/tutorial.rst

@@ -204,7 +204,7 @@ look like if we used the Poll class as our type hint:
 
         .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t3.py
             :language: python
-            :lines: 11-53
+            :lines: 11-52
 
     .. tab:: Typer-style
 

examples/extensions/backup/management/commands/backup_typer.py

@@ -0,0 +1,127 @@
+import inspect
+import os
+import typing as t
+from pathlib import Path
+
+import typer
+from django.conf import settings
+from django.core.management import CommandError, call_command
+
+from django_typer import CommandNode, Typer, completers
+
+app = Typer()
+
+Command.suppressed_base_arguments = {"verbosity", "skip_checks"}
+Command.requires_migrations_checks = False
+Command.requires_system_checks = []
+
+databases = [alias for alias in settings.DATABASES.keys()]
+
+
+@app.callback(invoke_without_command=True)
+def init_or_run_all(
+    self,
+    # if we add a context argument Typer will provide it
+    context: typer.Context,
+    output_directory: t.Annotated[
+        Path,
+        typer.Option(
+            "-o",
+            "--output",
+            shell_complete=completers.complete_directory,
+            help="The directory to write backup artifacts to.",
+        ),
+    ] = Path(os.getcwd()),
+):
+    """
+    Backup the website! This command groups backup routines together.
+    Each routine may be run individually, but if no routine is specified,
+    the default run of all routines will be executed.
+    """
+    self.output_directory = output_directory
+
+    if not self.output_directory.exists():
+        self.output_directory.mkdir(parents=True)
+
+    if not self.output_directory.is_dir():
+        raise CommandError(f"{self.output_directory} is not a directory.")
+
+    # here we use the context to determine if a subcommand was invoked and
+    # if it was not we run all the backup routines
+    if not context.invoked_subcommand:
+        for cmd in get_backup_routines(self):
+            cmd()
+
+
+@app.command()
+def list(self):
+    """
+    List the default backup routines in the order they will be run.
+    """
+    self.echo("Default backup routines:")
+    for cmd in get_backup_routines(self):
+        sig = {
+            name: param.default
+            for name, param in inspect.signature(
+                cmd.callback
+            ).parameters.items()
+            if not name == "self"
+        }
+        params = ", ".join([f"{k}={v}" for k, v in sig.items()])
+        self.secho(f"  {cmd.name}({params})", fg="green")
+
+
+@app.command()
+def database(
+    self,
+    filename: t.Annotated[
+        str,
+        typer.Option(
+            "-f",
+            "--filename",
+            help=(
+                "The name of the file to use for the backup fixture. The "
+                "filename may optionally contain a {database} formatting "
+                "placeholder."
+            ),
+        ),
+    ] = "{database}.json",
+    databases: t.Annotated[
+        t.Optional[t.List[str]],
+        typer.Option(
+            "-d",
+            "--database",
+            help=(
+                "The name of the database(s) to backup. If not provided, "
+                "all databases will be backed up."
+            ),
+            shell_complete=completers.databases,
+        ),
+    ] = databases,
+):
+    """
+    Backup database(s) to a json fixture file.
+    """
+    for db in databases or self.databases:
+        output = self.output_directory / filename.format(database=db)
+        self.echo(f"Backing up database [{db}] to: {output}")
+        call_command(
+            "dumpdata",
+            output=output,
+            database=db,
+            format="json",
+        )
+
+
+def get_backup_routines(command) -> t.List[CommandNode]:
+    """
+    Return the list of backup subcommands. This is every registered command
+    except for the list command.
+    """
+    # fetch all the command names at the top level of our command tree,
+    # except for list, which we know to not be a backup routine
+    return [
+        cmd
+        for name, cmd in command.get_subcommand().children.items()
+        if name != "list"
+    ]

examples/extensions/media1/management/commands/backup_typer.py

@@ -0,0 +1,37 @@
+import tarfile
+import typing as t
+from pathlib import Path
+
+import typer
+from django.conf import settings
+
+from django_typer import Typer
+from django_typer.tests.apps.examples.extensions.backup.management.commands import (
+    backup_typer,
+)
+
+app = Typer(backup_typer.app)
+
+
+@app.command()
+def media(
+    self,
+    filename: t.Annotated[
+        str,
+        typer.Option(
+            "-f",
+            "--filename",
+            help=("The name of the file to use for the media backup tar."),
+        ),
+    ] = "media.tar.gz",
+):
+    """
+    Backup the media files (i.e. those files in MEDIA_ROOT).
+    """
+    media_root = Path(settings.MEDIA_ROOT)
+    output_file = self.output_directory / filename
+
+    # backup the media directory into the output file as a gzipped tar
+    typer.echo(f"Backing up {media_root} to {output_file}")
+    with tarfile.open(output_file, "w:gz") as tar:
+        tar.add(media_root, arcname=media_root.name)

examples/extensions/media2/management/extensions/backup_typer.py

@@ -0,0 +1,36 @@
+import tarfile
+import typing as t
+from pathlib import Path
+
+import typer
+from django.conf import settings
+
+from django_typer.tests.apps.examples.extensions.backup.management.commands import (
+    backup_typer,
+)
+
+
+@backup_typer.app.command()
+def media(
+    # self is optional, but if you want to access the command instance, you
+    # can specify it
+    self,
+    filename: t.Annotated[
+        str,
+        typer.Option(
+            "-f",
+            "--filename",
+            help=("The name of the file to use for the media backup tar."),
+        ),
+    ] = "media.tar.gz",
+):
+    """
+    Backup the media files (i.e. those files in MEDIA_ROOT).
+    """
+    media_root = Path(settings.MEDIA_ROOT)
+    output_file = self.output_directory / filename
+
+    # backup the media directory into the output file as a gzipped tar
+    typer.echo(f"Backing up {media_root} to {output_file}")
+    with tarfile.open(output_file, "w:gz") as tar:
+        tar.add(media_root, arcname=media_root.name)