implement #81

Author: bckohan

django_typer/__init__.py

@@ -54,7 +54,7 @@
     completion_init,  # pyright: ignore[reportPrivateImportUsage]
 )
 
-from django_typer import TyperCommand, command, get_command
+from django_typer.management import TyperCommand, command, get_command
 from django_typer.utils import get_usage_script
 
 DETECTED_SHELL = None

django_typer/management/__init__.py

@@ -156,3 +156,42 @@ present. This is ok, the ones added last will be used.
   @grp2.command()
   def cmd2():
       pass
+
+
+Notes on BaseCommand_
+~~~~~~~~~~~~~~~~~~~~~
+
+There are a number of encumbrances in the Django management command design that make our
+implementation more difficult than it need be. We document them here mostly to keep track of them
+for potential future core Django work.
+
+  1) BaseCommand::execute() prints results to stdout without attempting to convert them
+     to strings. This means you've gotta do weird stuff to get a return object out of
+     call_command()
+
+  2) call_command() converts arguments to strings. There is no official way to pass
+     previously parsed arguments through call_command(). This makes it a bit awkward to
+     use management commands as callable functions in django code which you should be able
+     to easily do. django-typer allows you to invoke the command and group functions
+     directly so you can work around this, but it would be nice if call_command() supported
+     a general interface that all command libraries could easily implement to.
+
+  3) terminal autocompletion is not pluggable. As of this writing (Django<=5)
+     autocomplete is implemented for bash only and has no mechanism for passing the buck
+     down to command implementations. The result of this in django-typer is that we wrap
+     django's autocomplete and pass the buck to it instead of the other way around. This is
+     fine but it will be awkward if two django command line apps with their own autocomplete
+     infrastructure are used together. Django should be the central coordinating point for
+     this. This is the reason for the pluggable --fallback awkwardness in shellcompletion.
+
+  4) Too much of the BaseCommand implementation is built assuming argparse. A more
+     generalized abstraction of this interface is in order. Right now BaseCommand is doing
+     double duty both as a base class and a protocol.
+
+  5) There is an awkwardness to how parse_args flattens all the arguments and options
+     into a single dictionary. This means that when mapping a library like Typer onto the
+     BaseCommand interface you cannot allow arguments at different levels
+     (e.g. in initialize()) or group() functions above the command to have the same names as
+     the command's options. You can work around this by using a different name for the
+     option in the command and supplying the desired name in the annotation, but its an odd
+     quirk imposed by the base class for users to be aware of.

django_typer/management/commands/shellcompletion.py

@@ -6,6 +6,7 @@ v2.1.0
 ======
 
 * Implemented `Move tests into top level dir. <https://github.com/bckohan/django-typer/issues/87>`_
+* Implemented `Move core code out of __init__.py into management/__init__.py <https://github.com/bckohan/django-typer/issues/81>`_
 
 
 v2.0.2

doc/source/architecture.rst

@@ -14,20 +14,22 @@ django_typer
 ------------
 
 .. automodule:: django_typer
+
+.. automodule:: django_typer.management
    :members:
    :exclude-members: Typer, CommandGroup, TyperCommand, Context, CommandNode
    :show-inheritance:
 
-.. autoclass:: django_typer.Typer
+.. autoclass:: django_typer.management.Typer
     :members: callback, initialize, command, group, add_typer
 
-.. autoclass:: django_typer.TyperCommand
+.. autoclass:: django_typer.management.TyperCommand
     :members: initialize, callback, command, group, echo, secho, print_help, get_subcommand
 
-.. autoclass:: django_typer.CommandNode
+.. autoclass:: django_typer.management.CommandNode
     :members: name, click_command, context, children, get_command, print_help
 
-.. autoclass:: django_typer.TyperCommandMeta
+.. autoclass:: django_typer.management.TyperCommandMeta
 
 .. _types:
 

doc/source/changelog.rst

@@ -12,7 +12,7 @@
 
 class BasicTests(TestCase):
     def test_common_options_function(self):
-        from django_typer import _common_options
+        from django_typer.management import _common_options
 
         self.assertIsNone(_common_options())
 

doc/source/reference.rst

@@ -144,7 +144,7 @@ def test_initialize_interface_matches(self):
         self.assertTrue(initialize is callback)
 
     def test_typercommandmeta_interface_matches(self):
-        from django_typer import TyperCommandMeta
+        from django_typer.management import TyperCommandMeta
 
         typer_command_params = set(get_named_arguments(TyperCommandMeta.__new__))
         typer_params = set(get_named_arguments(typer.Typer.__init__))
@@ -282,7 +282,7 @@ def test_cmd_getattr(self):
             pass
 
     def test_proxied_property(self):
-        from django_typer import BoundProxy
+        from django_typer.management import BoundProxy
         from tests.apps.test_app.management.commands.basic import (
             Command as Basic,
         )
@@ -305,7 +305,7 @@ def sqrt(self):
                     pass
 
     def test_attribute_access_outside_of_definition(self):
-        from django_typer import TyperCommand, TyperCommandMeta
+        from django_typer.management import TyperCommand, TyperCommandMeta
         from tests.apps.test_app.management.commands.native import app
 
         with self.assertRaises(AttributeError):