Allow extra_template_vars to resolve to None

Closes #2005

datasette/app.py

@@ -2587,6 +2587,8 @@ ORDER BY allowed.parent, allowed.child
             datasette=self,
         ):
             extra_vars = await await_me_maybe(extra_vars)
+            if extra_vars is None:
+                continue
             assert isinstance(
                 extra_vars, dict
             ), f"extra_vars is of type {type(extra_vars)}"

datasette/hookspecs.py

@@ -50,7 +50,7 @@ def extra_body_script(
 def extra_template_vars(
     template, database, table, columns, view_name, request, datasette
 ):
-    """Extra template variables to be made available to the template - can return dict or callable or awaitable"""
+    """Extra template variables to be made available to the template - can return dict, None, callable or awaitable"""
 
 
 @hookspec

docs/changelog.rst

@@ -26,6 +26,7 @@ Datasette plugins can now use **background tasks** to run code independent of th
 Bug fixes
 ~~~~~~~~~
 
+- The :ref:`extra_template_vars() <plugin_hook_extra_template_vars>` plugin hook can now return a function or awaitable that resolves to ``None`` when no extra variables are needed. (:issue:`2005`)
 - :ref:`request.headers <internals_request>` now supports case-insensitive header lookups, so ``request.headers.get("Content-Type")`` works as well as ``request.headers.get("content-type")``. (:issue:`1861`)
 - CSV endpoints now return plain-text error messages for SQL errors. (:issue:`2129`)
 - The :ref:`render_cell() <plugin_hook_render_cell>` plugin hook now receives an empty ``pks`` list when rendering SQL views in HTML, matching the JSON ``?_extra=render_cell`` behavior. (:issue:`2639`)

docs/plugin_hooks.rst

@@ -217,7 +217,7 @@ Extra template variables that should be made available in the rendered template
 ``datasette`` - :ref:`internals_datasette`
     You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
 
-This hook can return one of three different types:
+This hook supports the following return values:
 
 Dictionary
     If you return a dictionary its keys and values will be merged into the template context.
@@ -228,6 +228,9 @@ Function that returns a dictionary
 Function that returns an awaitable function that returns a dictionary
     You can also return a function which returns an awaitable function which returns a dictionary.
 
+``None``
+    The hook itself, or a function or awaitable it returns, can return ``None`` when no extra variables are needed. Variables returned by other plugins are still included.
+
 Datasette runs Jinja2 in `async mode <https://jinja.palletsprojects.com/en/2.10.x/api/#async-support>`__, which means you can add awaitable functions to the template scope and they will be automatically awaited when they are rendered by the template.
 
 .. warning::
@@ -254,8 +257,6 @@ This example returns an awaitable function which adds a list of ``hidden_table_n
                 return {
                     "hidden_table_names": await db.hidden_table_names()
                 }
-            else:
-                return {}
 
         return hidden_table_names
 

tests/test_plugins.py

@@ -429,6 +429,72 @@ def test_hook_extra_template_vars(restore_working_directory):
         } == extra_template_vars_from_awaitable
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "return_style", ["direct", "callable", "async_callable", "awaitable"]
+)
+async def test_hook_extra_template_vars_none(ds_client, return_style):
+    class OtherPlugin:
+        @hookimpl
+        def extra_template_vars(self):
+            return {"other": "present"}
+
+    class ConditionalPlugin:
+        @hookimpl
+        def extra_template_vars(self, view_name):
+            def inner():
+                if view_name == "database":
+                    return {"conditional": "database"}
+
+            async def async_inner():
+                return inner()
+
+            if return_style == "direct":
+                return inner()
+            elif return_style == "callable":
+                return inner
+            elif return_style == "async_callable":
+                return async_inner
+            else:
+                return async_inner()
+
+    other_plugin = OtherPlugin()
+    conditional_plugin = ConditionalPlugin()
+    pm.register(other_plugin)
+    pm.register(conditional_plugin)
+    try:
+        template = ds_client.ds.get_jinja_environment().from_string(
+            "{{ other }}:{{ conditional|default('missing') }}"
+        )
+        for view_name, expected in (
+            ("database", "present:database"),
+            ("index", "present:missing"),
+        ):
+            rendered = await ds_client.ds.render_template(template, view_name=view_name)
+            assert rendered == expected
+    finally:
+        pm.unregister(conditional_plugin)
+        pm.unregister(other_plugin)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("invalid_value", [False, 0, "", [], ()])
+async def test_hook_extra_template_vars_invalid(ds_client, invalid_value):
+    class InvalidPlugin:
+        @hookimpl
+        def extra_template_vars(self):
+            return lambda: invalid_value
+
+    plugin = InvalidPlugin()
+    pm.register(plugin)
+    try:
+        template = ds_client.ds.get_jinja_environment().from_string("test")
+        with pytest.raises(AssertionError, match="extra_vars is of type"):
+            await ds_client.ds.render_template(template)
+    finally:
+        pm.unregister(plugin)
+
+
 def test_plugins_async_template_function(restore_working_directory):
     with make_app_client(
         template_dir=str(pathlib.Path(__file__).parent / "test_templates")