more tutorial doc work

bckohan · bckohan · commit 181b7c7d26cd · 2024-02-25T00:35:56.000-08:00
diff --git a/django_typer/examples/tutorial/step1/closepoll.py b/django_typer/examples/tutorial/step1/closepoll.py
@@ -18,13 +18,13 @@ def handle(
             try:
                 poll = Poll.objects.get(pk=poll_id)
             except Poll.DoesNotExist:
-                raise CommandError('Poll "%s" does not exist' % poll_id)
+                raise CommandError(f'Poll "{poll_id}" does not exist')
 
             poll.opened = False
             poll.save()
 
             self.stdout.write(
-                self.style.SUCCESS('Successfully closed poll "%s"' % poll_id)
+                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
             )
 
             if delete:
diff --git a/django_typer/examples/tutorial/step2/closepoll.py b/django_typer/examples/tutorial/step2/closepoll.py
@@ -30,13 +30,13 @@ def handle(
             try:
                 poll = Poll.objects.get(pk=poll_id)
             except Poll.DoesNotExist:
-                raise CommandError('Poll "%s" does not exist' % poll_id)
+                raise CommandError(f'Poll "{poll_id}" does not exist')
 
             poll.opened = False
             poll.save()
 
             self.stdout.write(
-                self.style.SUCCESS('Successfully closed poll "%s"' % poll_id)
+                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
             )
 
             if delete:
diff --git a/django_typer/examples/tutorial/step3/closepoll.py b/django_typer/examples/tutorial/step3/closepoll.py
@@ -20,7 +20,7 @@ def get_poll_from_id(poll: t.Union[str, Poll]) -> Poll:
     try:
         return Poll.objects.get(pk=int(poll))
     except Poll.DoesNotExist:
-        raise CommandError('Poll "%s" does not exist' % poll)
+        raise CommandError(f'Poll "{poll}" does not exist')
 
 
 class Command(TyperCommand):
@@ -53,7 +53,7 @@ def handle(
             poll.opened = False
             poll.save()
             self.stdout.write(
-                self.style.SUCCESS('Successfully closed poll "%s"' % poll.question_text)
+                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
             )
             if delete:
                 poll.delete()
diff --git a/django_typer/examples/tutorial/step4/closepoll.py b/django_typer/examples/tutorial/step4/closepoll.py
@@ -0,0 +1,50 @@
+import sys
+import typing as t
+
+if sys.version_info < (3, 9):
+    from typing_extensions import Annotated
+else:
+    from typing import Annotated
+
+from django.utils.translation import gettext_lazy as _
+from typer import Argument, Option
+
+from django_typer import TyperCommand
+from django_typer.parsers import ModelObjectParser
+from django_typer.tests.polls.models import Question as Poll
+
+
+class Command(TyperCommand):
+
+    def handle(
+        self,
+        polls: Annotated[
+            t.List[Poll],
+            Argument(
+                parser=ModelObjectParser(Poll),
+                help=_("The database IDs of the poll(s) to close."),
+            ),
+        ],
+        delete: Annotated[
+            bool,
+            Option(
+                "--delete",  # we can also get rid of that unnecessary --no-delete flag
+                help=_("Delete poll instead of closing it."),
+            ),
+        ] = False,
+    ):
+        """
+        Closes the specified poll for voting.
+
+
+        As mentioned in the last section, helps can also
+        be set in the docstring
+        """
+        for poll in polls:
+            poll.opened = False
+            poll.save()
+            self.stdout.write(
+                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
+            )
+            if delete:
+                poll.delete()
diff --git a/django_typer/examples/tutorial/step5/closepoll.py b/django_typer/examples/tutorial/step5/closepoll.py
@@ -0,0 +1,52 @@
+import sys
+import typing as t
+
+if sys.version_info < (3, 9):
+    from typing_extensions import Annotated
+else:
+    from typing import Annotated
+
+from django.utils.translation import gettext_lazy as _
+from typer import Argument, Option
+
+from django_typer import TyperCommand
+from django_typer.completers import ModelObjectCompleter
+from django_typer.parsers import ModelObjectParser
+from django_typer.tests.polls.models import Question as Poll
+
+
+class Command(TyperCommand):
+
+    def handle(
+        self,
+        polls: Annotated[
+            t.List[Poll],
+            Argument(
+                parser=ModelObjectParser(Poll),
+                shell_complete=ModelObjectCompleter(Poll, help_field="question_text"),
+                help=_("The database IDs of the poll(s) to close."),
+            ),
+        ],
+        delete: Annotated[
+            bool,
+            Option(
+                "--delete",  # we can also get rid of that unnecessary --no-delete flag
+                help=_("Delete poll instead of closing it."),
+            ),
+        ] = False,
+    ):
+        """
+        Closes the specified poll for voting.
+
+
+        As mentioned in the last section, helps can also
+        be set in the docstring
+        """
+        for poll in polls:
+            poll.opened = False
+            poll.save()
+            self.stdout.write(
+                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
+            )
+            if delete:
+                poll.delete()
diff --git a/django_typer/examples/tutorial/step6/closepoll.py b/django_typer/examples/tutorial/step6/closepoll.py
@@ -0,0 +1,40 @@
+import sys
+import typing as t
+
+if sys.version_info < (3, 9):
+    from typing_extensions import Annotated
+else:
+    from typing import Annotated
+
+from django.utils.translation import gettext_lazy as _
+from typer import Argument, Option
+
+from django_typer import TyperCommand, model_parser_completer
+from django_typer.tests.polls.models import Question as Poll
+
+
+class Command(TyperCommand):
+    help = _("Closes the specified poll for voting.")
+
+    def handle(
+        self,
+        polls: Annotated[
+            t.List[Poll],
+            Argument(
+                **model_parser_completer(Poll, help_field="question_text"),
+                help=_("The database IDs of the poll(s) to close."),
+            ),
+        ],
+        delete: Annotated[
+            bool,
+            Option(help=_("Delete poll instead of closing it.")),
+        ] = False,
+    ):
+        for poll in polls:
+            poll.opened = False
+            poll.save()
+            self.stdout.write(
+                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
+            )
+            if delete:
+                poll.delete()
diff --git a/django_typer/tests/polls/management/commands/closepoll.py b/django_typer/tests/polls/management/commands/closepoll.py
@@ -29,7 +29,7 @@ def handle(
             poll.opened = False
             poll.save()
             self.stdout.write(
-                self.style.SUCCESS(f'Successfully closed poll "{{ poll.id }}"')
+                self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
             )
             if delete:
                 poll.delete()
diff --git a/django_typer/tests/polls/management/commands/closepoll_t4.py b/django_typer/tests/polls/management/commands/closepoll_t4.py
@@ -0,0 +1 @@
+../../../../examples/tutorial/step4/closepoll.py
diff --git a/django_typer/tests/polls/management/commands/closepoll_t5.py b/django_typer/tests/polls/management/commands/closepoll_t5.py
@@ -0,0 +1 @@
+../../../../examples/tutorial/step5/closepoll.py
diff --git a/django_typer/tests/polls/management/commands/closepoll_t6.py b/django_typer/tests/polls/management/commands/closepoll_t6.py
@@ -0,0 +1 @@
+../../../../examples/tutorial/step6/closepoll.py
diff --git a/doc/source/_static/img/closepoll_example.gif b/doc/source/_static/img/closepoll_example.gif
diff --git a/doc/source/shell_completion.rst b/doc/source/shell_completion.rst
@@ -6,6 +6,11 @@
 Shell Completions
 =================
 
+.. image:: /_static/img/closepoll_example.gif
+   :align: center
+
+|
+
 Shell completions are helpful suggestions that are displayed when you press the
 ``<TAB>`` key while typing a command in a shell.  They are especially useful
 when you are not sure about the exact name of a command, its options, its arguments
diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst
@@ -105,13 +105,13 @@ looks like this:
                 try:
                     poll = Poll.objects.get(pk=poll_id)
                 except Poll.DoesNotExist:
-                    raise CommandError('Poll "%s" does not exist' % poll_id)
+                    raise CommandError(f'Poll "{poll_id}" does not exist')
 
                 poll.opened = False
                 poll.save()
 
                 self.stdout.write(
-                    self.style.SUCCESS('Successfully closed poll "%s"' % poll_id)
+                    self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
                 )
 
                 if options["delete"]:
@@ -145,13 +145,13 @@ conversion may look like this:
                 try:
                     poll = Poll.objects.get(pk=poll_id)
                 except Poll.DoesNotExist:
-                    raise CommandError('Poll "%s" does not exist' % poll_id)
+                    raise CommandError(f'Poll "{poll_id}" does not exist')
 
                 poll.opened = False
                 poll.save()
 
                 self.stdout.write(
-                    self.style.SUCCESS('Successfully closed poll "%s"' % poll_id)
+                    self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
                 )
 
                 if delete:
@@ -259,7 +259,7 @@ look like if we used the Poll class as our type hint:
         try:
             return Poll.objects.get(pk=int(poll))
         except Poll.DoesNotExist:
-            raise CommandError('Poll "%s" does not exist' % poll)
+            raise CommandError(f'Poll "{poll_id}" does not exist')
 
 
     class Command(TyperCommand):
@@ -287,7 +287,15 @@ look like if we used the Poll class as our type hint:
             As mentioned in the last section, helps can also
             be set in the docstring
             """
-            # ...
+            for poll in polls:
+                poll.opened = False
+                poll.save()
+                self.stdout.write(
+                    self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
+                )
+                if delete:
+                    poll.delete()
+
 
 
 .. typer:: django_typer.examples.tutorial.step3.closepoll.Command:typer_app
@@ -299,9 +307,106 @@ look like if we used the Poll class as our type hint:
 
 |
 
+django-typer_ offers some built-in :mod:`~django_typer.parsers` that can be used for
+common Django_ types. For example, the :class:`~django_typer.parsers.ModelObjectParser` can
+be used to fetch a model object from a given field. By default it will use the primary key,
+so we could rewrite the relevant lines above like so:
+
+.. code-block:: python
+
+    from django_typer.parsers import ModelObjectParser
+
+    # ...
+
+    t.Annotated[
+        t.List[Poll],
+        Argument(
+            parser=ModelObjectParser(Poll),
+            help=_("The database IDs of the poll(s) to close.")
+        )
+    ]
+
+    # ...
+
 Add shell tab-completion suggestions for polls
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It's very annoying to have to know the database primary key of the poll to close it. django-typer_ makes it
-easy to add tab completion suggestions! Let's see wha that would look like:
+easy to add tab completion suggestions! You can always
+`implement your own completer functions <https://click.palletsprojects.com/en/8.1.x/shell-completion/#custom-type-completion>`_,
+but as with, :mod:`~django_typer.parsers`, there are some out-of-the-box :mod:`~django_typer.completers` that
+make this easy. Let's see what the relevant updates to our closepoll command would look like:
+
+.. code-block:: python
+
+    from django_typer.parsers import ModelObjectParser
+    from django_typer.completers import ModelObjectCompleter
+
+    # ... 
+
+    t.Annotated[
+        t.List[Poll],
+        Argument(
+            parser=ModelObjectParser(Poll),
+            shell_complete=ModelObjectCompleter(Poll, help_field='question_text'),
+            help=_("The database IDs of the poll(s) to close.")
+        )
+    ]
+
+    # ...
+
+.. note::
+    
+    For tab-completions to work you will need to 
+    :ref:`install the shell completion scripts for your shell <shellcompletions>`.
+
+
+Putting it all together
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When we're using a :class:`~django_typer.parsers.ModelObjectParser` and
+:class:`~django_typer.completers.ModelObjectCompleter` we can use the
+:func:`~django_typer.model_parser_completer` convenience function to reduce the amount
+of boiler plate. Let's put everything together and see what our full-featured refactored
+closepoll command looks like:
+
+.. code-block:: python
+    :linenos:
+
+    import typing as t
+
+    from django.utils.translation import gettext_lazy as _
+    from typer import Argument, Option
+
+    from django_typer import TyperCommand, model_parser_completer
+    from polls.models import Question as Poll
+
+
+    class Command(TyperCommand):
+        help = _("Closes the specified poll for voting.")
+
+        def handle(
+            self,
+            polls: Annotated[
+                t.List[Poll],
+                Argument(
+                    **model_parser_completer(Poll, help_field="question_text"),
+                    help=_("The database IDs of the poll(s) to close."),
+                ),
+            ],
+            delete: Annotated[
+                bool, Option(help=_("Delete poll instead of closing it.")),
+            ] = False,
+        ):
+            for poll in polls:
+                poll.opened = False
+                poll.save()
+                self.stdout.write(
+                    self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')
+                )
+                if delete:
+                    poll.delete()
+
 
+.. image:: /_static/img/closepoll_example.gif
+   :align: center

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ def handle(`
`29`	`29`	`poll.opened = False`
`30`	`30`	`poll.save()`
`31`	`31`	`self.stdout.write(`
`32`		`- self.style.SUCCESS(f'Successfully closed poll "{{ poll.id }}"')`
	`32`	`+ self.style.SUCCESS(f'Successfully closed poll "{poll.id}"')`
`33`	`33`	`)`
`34`	`34`	`if delete:`
`35`	`35`	`poll.delete()`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../examples/tutorial/step4/closepoll.py`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../examples/tutorial/step5/closepoll.py`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../examples/tutorial/step6/closepoll.py`