Merge e82bf89fa5 into e78b8a2e6a

docs/plugin_hooks.rst

@@ -1419,6 +1419,8 @@ The arguments to the ``FilterArguments`` class constructor are as follows:
 ``extra_context`` - dictionary, optional
     Additional context variables that should be made available to the ``table.html`` template when it is rendered.
 
+The hook can also return an ``async def`` function, which Datasette will await. This is useful if you need to execute SQL queries or perform other asynchronous operations in order to build your filters. Datasette's own default implementations of this hook `use this pattern <https://github.com/simonw/datasette/blob/main/datasette/filters.py>`__.
+
 This example plugin causes 0 results to be returned if ``?_nothing=1`` is added to the URL:
 
 .. code-block:: python

tests/test_docs.py

@@ -59,6 +59,13 @@ def test_plugin_hooks_are_documented(plugin_hooks_content, subtests):
             ), f"Missing from plugin hook documentation: {expected}"
 
 
+def test_filters_from_request_async_function_documented(plugin_hooks_content):
+    section = plugin_hooks_content.split(".. _plugin_hook_filters_from_request:")[
+        -1
+    ].split(".. _plugin_hook_")[0]
+    assert "async def" in section
+
+
 @pytest.fixture(scope="session")
 def documented_views():
     view_labels = set()