flush out performance page

Author: bckohan

CONTRIBUTING.md

@@ -94,6 +94,7 @@ just release x.x.x
 ## Just Recipes
 
 ```bash
+benchmark                # generate and document benchmarks
 build                    # build src package and wheel
 build-docs               # build the docs
 build-docs-html          # build html documentation

doc/source/_static/img/minimal_profile.svg

@@ -4,9 +4,10 @@
 Change Log
 ==========
 
-v3.3 (2025-08-31)
+v3.3.0 (2025-08-31)
 ===================
 
+* Documented `Add note on startup performance to docs. <https://github.com/django-commons/django-typer/issues/227>`_
 * Fixed `Support typer 0.17 <https://github.com/django-commons/django-typer/issues/225>`_
 
 v3.2.2 (2025-07-17)

doc/source/_static/img/polls_profile.svg

@@ -108,15 +108,24 @@
 }
 
 
+def pypi_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    from docutils import nodes
+
+    url = f"https://pypi.org/project/{text}/"
+    node = nodes.reference(rawtext, text, refuri=url, **options)
+    return [node], []
+
+
 def setup(app):
+    from docutils.parsers.rst import roles
     # Register a sphinx.ext.autodoc.between listener to ignore everything
     # between lines that contain the word IGNORE
     app.connect(
         'autodoc-process-docstring',
         between('^.*[*]{79}.*$', exclude=True)
     )
     # app.connect('html-page-context', add_page_class)
-
+    roles.register_local_role("pypi", pypi_role)
     app.add_directive("literalinclude", ExtendedLiteralInclude)
     app.add_crossref_type(directivename="django-admin", rolename="django-admin")
     # https://sphinxcontrib-typer.readthedocs.io/en/latest/howto.html#build-to-multiple-formats

doc/source/changelog.rst

@@ -4,13 +4,45 @@
 Performance
 ===========
 
-Django management command startup time can be noticeably slow, especially for large projects with
-many models. We can perceive time at roughly 100 ms, bare
+Django management command startup time has the potential to be noticeably slow, especially for large
+projects with many apps and models. Django must be fully bootstrapped before management commands can
+run. This can make the CLI feel sluggish and presents particular challenges for shell completion as
+this delay is incurred each time ``<tab>`` is pressed.
 
-----------------
+If you are experiencing difficulty with shell completion we recommend:
+
+1. Enabling menu based completion navigation in your terminal. This can reduce the number of calls
+   to :django-admin:`shellcompletion`. For z-shell this would look like:
+
+   .. code-block:: bash
+
+       zstyle ':completion:*' menu select
+
+2. Use import and performance analysis tools to determine if there are import bottle necks that can
+   be lazily loaded.
+
+The following benchmarks show total module loads, import and runtimes. All times are in seconds.
+
+The first benchmark is for a minimal project that uses the settings file generated by
+:django-admin:`startproject`. You can see that when :pypi:`rich` is installed several hundred extra
+modules must be imported. This adds a few 10s of milliseconds to the import time. To avoid this,
+uninstall :pypi:`rich`. As of :pypi:`Typer` 0.17, :pypi:`rich` is lazily loaded, but until certain
+improvements are made to :pypi:`Typer`, the import time penalty is still incurred by
+:pypi:`django-typer`.
 
 .. raw:: html
     :file: _static/img/minimal_profile.svg
 
+The second benchmark shows the same stats for the :ref:`polls example code <building_commands>`.
+These benchmarks compare the :class:`~django.core.management.BaseCommand` native implementation
+to the :class:`~django_typer.management.TyperCommand` implementation. They show that the overhead of
+using :pypi:`django-typer` is minimal. On the order of a few 10s of milliseconds. Adding
+:pypi:`rich` increases this overhead slightly, but the impact is still barely noticeable.
+
 .. raw:: html
-    :file: _static/img/polls_profile.svg
+    :file: _static/img/polls_profile.svg
+
+
+.. success::
+
+    These benchmarks illustrate that adding

doc/source/conf.py

@@ -340,6 +340,12 @@ run +ARGS:
 translate: install-translate
     @just manage translate --settings tests.settings.translate
 
+# generate and document benchmarks
+benchmark:
+    @just run --no-dev --no-extra rich --exact ./profiling/profile.py generate
+    @just run --no-dev --extra rich --exact ./profiling/profile.py generate
+    @just run --group profiling ./profiling/profile.py document
+
 # validate the given version string against the lib version
 [script]
 validate_version VERSION:

doc/source/performance.rst

@@ -3,8 +3,8 @@
         "env": {
             "django_typer": [
                 3,
-                2,
-                2
+                3,
+                0
             ],
             "python": [
                 3,
@@ -28,8 +28,8 @@
                     "rich": false,
                     "help": false
                 },
-                "time": 0.13760000000000003,
-                "import_time": 0.126537,
+                "time": 0.1598,
+                "import_time": 0.10276,
                 "modules": 550
             },
             "156897129890272181": {
@@ -40,8 +40,8 @@
                     "rich": false,
                     "help": false
                 },
-                "time": 0.1502,
-                "import_time": 0.109779,
+                "time": 0.1642,
+                "import_time": 0.118827,
                 "modules": 592
             },
             "2176052577945945477": {
@@ -52,8 +52,8 @@
                     "rich": false,
                     "help": false
                 },
-                "time": 0.1494,
-                "import_time": 0.10648,
+                "time": 0.1728,
+                "import_time": 0.115422,
                 "modules": 592
             },
             "675072097072274051": {
@@ -64,8 +64,8 @@
                     "rich": false,
                     "help": false
                 },
-                "time": 0.18419999999999997,
-                "import_time": 0.108559,
+                "time": 0.19879999999999998,
+                "import_time": 0.122619,
                 "modules": 606
             },
             "2303909322008428434": {
@@ -76,8 +76,8 @@
                     "rich": false,
                     "help": false
                 },
-                "time": 0.1494,
-                "import_time": 0.100977,
+                "time": 0.15259999999999999,
+                "import_time": 0.106744,
                 "modules": 573
             },
             "274962866163047735": {
@@ -88,8 +88,8 @@
                     "rich": false,
                     "help": false
                 },
-                "time": 0.168,
-                "import_time": 0.109771,
+                "time": 0.1734,
+                "import_time": 0.115975,
                 "modules": 615
             },
             "942508120957984993": {
@@ -100,8 +100,8 @@
                     "rich": false,
                     "help": true
                 },
-                "time": 0.1382,
-                "import_time": 0.102393,
+                "time": 0.1482,
+                "import_time": 0.104318,
                 "modules": 550
             },
             "506589674454807823": {
@@ -112,8 +112,8 @@
                     "rich": false,
                     "help": true
                 },
-                "time": 0.1484,
-                "import_time": 0.108232,
+                "time": 0.159,
+                "import_time": 0.115199,
                 "modules": 593
             },
             "426905945237278128": {
@@ -124,8 +124,8 @@
                     "rich": false,
                     "help": true
                 },
-                "time": 0.1476,
-                "import_time": 0.109507,
+                "time": 0.16260000000000002,
+                "import_time": 0.122901,
                 "modules": 593
             },
             "174008683672669482": {
@@ -136,8 +136,8 @@
                     "rich": false,
                     "help": true
                 },
-                "time": 0.13520000000000001,
-                "import_time": 0.109942,
+                "time": 0.1508,
+                "import_time": 0.104901,
                 "modules": 551
             },
             "1942175217068420967": {
@@ -148,8 +148,8 @@
                     "rich": false,
                     "help": true
                 },
-                "time": 0.15039999999999998,
-                "import_time": 0.108588,
+                "time": 0.1636,
+                "import_time": 0.116833,
                 "modules": 594
             },
             "864373478621873697": {
@@ -160,8 +160,8 @@
                     "rich": true,
                     "help": false
                 },
-                "time": 0.1864,
-                "import_time": 0.141692,
+                "time": 0.214,
+                "import_time": 0.159158,
                 "modules": 744
             },
             "226255260169180632": {
@@ -172,8 +172,8 @@
                     "rich": true,
                     "help": false
                 },
-                "time": 0.1886,
-                "import_time": 0.138694,
+                "time": 0.2352,
+                "import_time": 0.163347,
                 "modules": 745
             },
             "428097589213665847": {
@@ -184,8 +184,8 @@
                     "rich": true,
                     "help": false
                 },
-                "time": 0.2218,
-                "import_time": 0.138445,
+                "time": 0.265,
+                "import_time": 0.149312,
                 "modules": 755
             },
             "2100452363596306712": {
@@ -196,8 +196,8 @@
                     "rich": true,
                     "help": false
                 },
-                "time": 0.2316,
-                "import_time": 0.143397,
+                "time": 0.2404,
+                "import_time": 0.156697,
                 "modules": 768
             },
             "1284199138412852409": {
@@ -208,8 +208,8 @@
                     "rich": true,
                     "help": true
                 },
-                "time": 0.22920000000000001,
-                "import_time": 0.153081,
+                "time": 0.2214,
+                "import_time": 0.153582,
                 "modules": 745
             },
             "2137499222435047482": {
@@ -220,8 +220,8 @@
                     "rich": true,
                     "help": true
                 },
-                "time": 0.195,
-                "import_time": 0.139081,
+                "time": 0.2194,
+                "import_time": 0.16577,
                 "modules": 746
             },
             "477819850357282012": {
@@ -232,8 +232,8 @@
                     "rich": true,
                     "help": true
                 },
-                "time": 0.2008,
-                "import_time": 0.138571,
+                "time": 0.217,
+                "import_time": 0.148613,
                 "modules": 747
             }
         },

justfile

@@ -1,3 +1,5 @@
+#!python
+
 import bisect
 import json
 import os
@@ -419,7 +421,7 @@ def minimal_table():
         ).write_text(svg, encoding="utf-8")
 
     def polls_table():
-        console = Console(record=True, width=80)
+        console = Console(record=True, width=100)
 
         # Top "header"
         console.print(
@@ -457,6 +459,16 @@ def polls_table():
                 "polls --help (tutorial)",
                 RunKey(cmd="polls", typer=False, app=False, rich=False, help=True),
             ),
+            (
+                "polls (typer)",
+                RunKey(cmd="polls", typer=True, app=True, rich=False, help=False),
+            ),
+            (
+                "shell completion",
+                RunKey(
+                    cmd="shellcompletion", typer=True, app=True, rich=False, help=False
+                ),
+            ),
         ]
         rich_cols = [
             (