add typer tabs to basic tutorial

Author: bckohan

django_typer/tests/test_poll_example.py

@@ -1,5 +1,7 @@
 import contextlib
 from io import StringIO
+import pytest
+import sys
 
 from django.core.management import call_command
 from django.test import SimpleTestCase
@@ -18,13 +20,16 @@
 ]
 
 
+@pytest.mark.skipif(sys.version_info < (3, 9), reason="requires python 3.9+")
 class TestPollExample(SimpleTestCase):
     q1 = None
     q2 = None
     q3 = None
 
     databases = {"default"}
 
+    typer = ""
+
     def setUp(self):
         self.q1 = Question.objects.create(
             question_text="Is Putin a war criminal?",
@@ -51,15 +56,18 @@ def test_poll_complete(self):
             result1 = StringIO()
             with contextlib.redirect_stdout(result1):
                 call_command(
-                    "shellcompletion", "complete", shell=shell, cmd_str="closepoll "
+                    "shellcompletion",
+                    "complete",
+                    shell=shell,
+                    cmd_str=f"closepoll{self.typer} ",
                 )
             result2 = StringIO()
             with contextlib.redirect_stdout(result2):
                 call_command(
                     "shellcompletion",
                     "complete",
                     shell=shell,
-                    cmd_str="./manage.py closepoll ",
+                    cmd_str=f"./manage.py closepoll{self.typer} ",
                 )
 
             result = result1.getvalue()
@@ -70,23 +78,23 @@ def test_poll_complete(self):
                     self.assertTrue(q.question_text in result)
 
     def test_tutorial1(self):
-        result = run_command("closepoll_t1", str(self.q2.id))
+        result = run_command(f"closepoll_t1{self.typer}", str(self.q2.id))
         self.assertFalse(result[1])
         self.assertTrue("Successfully closed poll" in result[0])
 
     def test_tutorial2(self):
-        result = run_command("closepoll_t2", str(self.q2.id))
+        result = run_command(f"closepoll_t2{self.typer}", str(self.q2.id))
         self.assertFalse(result[1])
         self.assertTrue("Successfully closed poll" in result[0])
 
     def test_tutorial_parser(self):
-        result = run_command("closepoll_t3", str(self.q1.id))
+        result = run_command(f"closepoll_t3{self.typer}", str(self.q1.id))
         self.assertFalse(result[1])
 
     def test_tutorial_parser_cmd(self):
         log = StringIO()
-        call_command("closepoll_t3", str(self.q1.id), stdout=log)
-        cmd = get_command("closepoll_t3", stdout=log)
+        call_command(f"closepoll_t3{self.typer}", str(self.q1.id), stdout=log)
+        cmd = get_command(f"closepoll_t3{self.typer}", stdout=log)
         cmd([self.q1])
         cmd(polls=[self.q1])
         # these don't work, maybe revisit in future?
@@ -96,13 +104,18 @@ def test_tutorial_parser_cmd(self):
 
     def test_tutorial_modelobjparser_cmd(self):
         log = StringIO()
-        call_command("closepoll_t6", str(self.q1.id), stdout=log)
-        cmd = get_command("closepoll_t6", stdout=log)
+        call_command(f"closepoll_t6{self.typer}", str(self.q1.id), stdout=log)
+        cmd = get_command(f"closepoll_t6{self.typer}", stdout=log)
         cmd([self.q1])
         cmd(polls=[self.q1])
         self.assertEqual(log.getvalue().count("Successfully"), 3)
 
     def test_poll_ex(self):
-        result = run_command("closepoll", str(self.q2.id))
+        result = run_command(f"closepoll{self.typer}", str(self.q2.id))
         self.assertFalse(result[1])
         self.assertTrue("Successfully closed poll" in result[0])
+
+
+@pytest.mark.skipif(sys.version_info < (3, 9), reason="requires python 3.9+")
+class TestPollExampleTyper(SimpleTestCase):
+    typer = "_typer"

doc/source/index.rst

@@ -5,7 +5,7 @@
 Django Typer
 ============
 
-Use Typer_ to define the CLI for your Django_ management commands using the typer interface.
+Use Typer_ to define the CLI for your Django_ management commands using Python's static typing.
 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 preserved, so that TyperCommand can be a drop in
@@ -25,6 +25,7 @@ replacement.
     * Refactor existing management commands into TyperCommands because TyperCommand is interface
       compatible with BaseCommand.
     * Use either a class-based interface or the basic Typer style interface to define commands.
+    * Add plugins to upstream commands.
 
 
 :big:`Installation`
@@ -59,9 +60,12 @@ replacement.
 
 .. note::
 
-    This documentation shows all examples using both the function orientied Typer-style interface
-    and the class based Django-style interface using tabs. Each interface is equivalent so the
-    choice of which to use is a matter of preference.
+    This documentation shows all examples using both the function oriented Typer-style interface
+    and the class based Django-style interface in separate tabs. Each interface is functionally
+    equivalent so the choice of which to use is a matter of preference and familiarity. All
+    django-typer commands are instances of :class:`~django_typer.TyperCommand`, including commands
+    defined in the Typer-style interface. **This means you may always specify a self argument to
+    receive the instance of the command in your functions.**
 
 :big:`Basic Example`
 
@@ -141,8 +145,7 @@ command like so:
 
 Any number of groups and subcommands and subgroups of other groups can be defined allowing for
 arbitrarily complex command hierarchies. The Typer-style interface builds a TyperCommand class for
-us. **This allows you to optionally accept the self argument in your commands.** We could define
-the above command using the typer interface like this:
+us **that allows you to optionally accept the self argument in your commands.**
 
 .. tabs::
 

doc/source/tutorial.rst

@@ -94,19 +94,30 @@ looks like this:
     :replace:
         django_typer.tests.apps.examples.polls.models : polls.models
 
-
 Inherit from :class:`~django_typer.TyperCommand`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We first need to change the inheritance to :class:`~django_typer.TyperCommand` and then move the
 argument and option definitions from add_arguments into the method signature of handle. A minimal
 conversion may look like this:
 
-.. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t1.py
-    :language: python
-    :linenos:
-    :replace:
-        django_typer.tests.apps.examples.polls.models : polls.models
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t1.py
+            :language: python
+            :linenos:
+            :replace:
+                django_typer.tests.apps.examples.polls.models : polls.models
+
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t1_typer.py
+            :language: python
+            :linenos:
+            :replace:
+                django_typer.tests.apps.examples.polls.models : polls.models
 
 You'll note that we've removed add_arguments entirely and specified the arguments and options as
 parameters to the handle method. django-typer_ will interpret the parameters on the handle() method
@@ -139,12 +150,23 @@ with one of two Typer_ parameter types, either Argument or Option. Arguments_ ar
 parameters and Options_ are named parameters (i.e. `--delete`). In our polls example, the poll_ids
 are arguments and the delete flag is an option. Here is what that would look like:
 
-.. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t2.py
-    :language: python
-    :lines: 17-29
-    :replace:
-        django_typer.tests.apps.examples.polls.models : polls.models
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t2.py
+            :language: python
+            :lines: 11-23
+            :replace:
+                django_typer.tests.apps.examples.polls.models : polls.models
+
+    .. tab:: Typer-style
 
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t2_typer.py
+            :language: python
+            :lines: 13-23
+            :replace:
+                django_typer.tests.apps.examples.polls.models : polls.models
 
 See that our help text now shows up in the command line interface. Also note, that
 `lazy translations <https://docs.djangoproject.com/en/stable/topics/i18n/translation/>`_ work for
@@ -176,11 +198,19 @@ duplicate our for loop that loads Poll objects from ids, but that wouldn't be ve
 Typer_ allows us to define custom parsers for arbitrary parameter types. Lets see what that would
 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
-    :linenos:
-    :lines: 17-58
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t3.py
+            :language: python
+            :lines: 11-53
 
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t3_typer.py
+            :language: python
+            :lines: 11-54
 
 .. typer:: django_typer.tests.apps.examples.polls.management.commands.closepoll_t3.Command:typer_app
     :prog: manage.py closepoll
@@ -254,11 +284,24 @@ When we're using a :class:`~django_typer.parsers.ModelObjectParser` and
 of boiler plate. Let's put everything together and see what our full-featured refactored
 closepoll command looks like:
 
-.. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t6.py
-    :language: python
-    :linenos:
-    :replace:
-        django_typer.tests.apps.examples.polls.models : polls.models
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t6.py
+            :language: python
+            :linenos:
+            :replace:
+                django_typer.tests.apps.examples.polls.models : polls.models
+
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../django_typer/tests/apps/examples/polls/management/commands/closepoll_t6_typer.py
+            :language: python
+            :linenos:
+            :replace:
+                django_typer.tests.apps.examples.polls.models : polls.models
+
 
 .. only:: html
 

examples/polls/management/commands/closepoll_t1_typer.py

@@ -0,0 +1,31 @@
+import typing as t
+
+from django.core.management.base import CommandError
+
+from django_typer import Typer
+from django_typer.tests.apps.examples.polls.models import Question as Poll
+
+app = Typer(help="Closes the specified poll for voting")
+
+
+@app.command()
+def handle(
+    self,
+    poll_ids: t.List[int],
+    delete: bool = False,
+):
+    for poll_id in poll_ids:
+        try:
+            poll = Poll.objects.get(pk=poll_id)
+        except Poll.DoesNotExist:
+            raise CommandError(f'Poll "{poll_id}" does not exist')
+
+        poll.opened = False
+        poll.save()
+
+        self.stdout.write(
+            self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
+        )
+
+        if delete:
+            poll.delete()

examples/polls/management/commands/closepoll_t2.py

@@ -1,11 +1,5 @@
-import sys
 import typing as t
 
-if sys.version_info < (3, 9):
-    from typing_extensions import Annotated
-else:
-    from typing import Annotated
-
 from django.core.management.base import CommandError
 from django.utils.translation import gettext_lazy as _
 from typer import Argument, Option
@@ -19,11 +13,11 @@ class Command(TyperCommand):
 
     def handle(
         self,
-        poll_ids: Annotated[
+        poll_ids: t.Annotated[
             t.List[int],
             Argument(help=_("The database IDs of the poll(s) to close.")),
         ],
-        delete: Annotated[
+        delete: t.Annotated[
             bool, Option(help=_("Delete poll instead of closing it."))
         ] = False,
     ):

examples/polls/management/commands/closepoll_t2_typer.py

@@ -0,0 +1,38 @@
+import typing as t
+
+from django.core.management.base import CommandError
+from django.utils.translation import gettext_lazy as _
+from typer import Argument, Option
+
+from django_typer import Typer
+from django_typer.tests.apps.examples.polls.models import Question as Poll
+
+app = Typer(help="Closes the specified poll for voting")
+
+
+@app.command()
+def handle(
+    self,
+    poll_ids: t.Annotated[
+        t.List[int],
+        Argument(help=_("The database IDs of the poll(s) to close.")),
+    ],
+    delete: t.Annotated[
+        bool, Option(help=_("Delete poll instead of closing it."))
+    ] = False,
+):
+    for poll_id in poll_ids:
+        try:
+            poll = Poll.objects.get(pk=poll_id)
+        except Poll.DoesNotExist:
+            raise CommandError(f'Poll "{poll_id}" does not exist')
+
+        poll.opened = False
+        poll.save()
+
+        self.stdout.write(
+            self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
+        )
+
+        if delete:
+            poll.delete()

examples/polls/management/commands/closepoll_t3.py

@@ -1,11 +1,5 @@
-import sys
 import typing as t
 
-if sys.version_info < (3, 9):
-    from typing_extensions import Annotated
-else:
-    from typing import Annotated
-
 from django.core.management.base import CommandError
 from django.utils.translation import gettext_lazy as _
 from typer import Argument, Option
@@ -26,14 +20,14 @@ def get_poll_from_id(poll: t.Union[str, Poll]) -> Poll:
 class Command(TyperCommand):
     def handle(
         self,
-        polls: Annotated[
+        polls: t.Annotated[
             t.List[Poll],
             Argument(
                 parser=get_poll_from_id,
                 help=_("The database IDs of the poll(s) to close."),
             ),
         ],
-        delete: Annotated[
+        delete: t.Annotated[
             bool,
             Option(
                 "--delete",  # we can also get rid of that unnecessary --no-delete flag