From c673ee981900284df078e5b6e933ef102e8c1008 Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Wed, 18 Mar 2026 15:07:07 -0700 Subject: [PATCH] Update docs for async def resources_sql(cls, datasette, actor=None) signature --- datasette/permissions.py | 2 +- docs/plugin_hooks.rst | 24 +++++++++++++++--------- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/datasette/permissions.py b/datasette/permissions.py index b868d025..917c58ab 100644 --- a/datasette/permissions.py +++ b/datasette/permissions.py @@ -105,7 +105,7 @@ class Resource(ABC): @classmethod @abstractmethod - def resources_sql(cls, datasette, actor=None) -> str: + async def resources_sql(cls, datasette, actor=None) -> str: """ Return SQL query that returns all resources of this type. diff --git a/docs/plugin_hooks.rst b/docs/plugin_hooks.rst index e375707d..fdc392cb 100644 --- a/docs/plugin_hooks.rst +++ b/docs/plugin_hooks.rst @@ -890,13 +890,15 @@ Actions define what operations can be performed on resources (like viewing a tab """A collection of documents.""" name = "document-collection" - parent_name = None + parent_class = None def __init__(self, collection: str): super().__init__(parent=collection, child=None) @classmethod - def resources_sql(cls) -> str: + async def resources_sql( + cls, datasette, actor=None + ) -> str: return """ SELECT collection_name AS parent, NULL AS child FROM document_collections @@ -907,13 +909,15 @@ Actions define what operations can be performed on resources (like viewing a tab """A document in a collection.""" name = "document" - parent_name = "document-collection" + parent_class = DocumentCollectionResource def __init__(self, collection: str, document: str): super().__init__(parent=collection, child=document) @classmethod - def resources_sql(cls) -> str: + async def resources_sql( + cls, datasette, actor=None + ) -> str: return """ SELECT collection_name AS parent, document_id AS child FROM documents @@ -959,13 +963,15 @@ The fields of the ``Action`` dataclass are as follows: - Define a ``name`` class attribute (e.g., ``"document"``) - Define a ``parent_class`` class attribute (``None`` for top-level resources like databases, or the parent ``Resource`` subclass for child resources) - - Implement a ``resources_sql()`` classmethod that returns SQL returning all resources as ``(parent, child)`` columns + - Implement an async ``resources_sql(cls, datasette, actor=None)`` classmethod that returns SQL returning all resources as ``(parent, child)`` columns - Have an ``__init__`` method that accepts appropriate parameters and calls ``super().__init__(parent=..., child=...)`` -The ``resources_sql()`` method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _plugin_resources_sql: -The ``resources_sql()`` classmethod returns a SQL query that lists all resources of that type that exist in the system. +The ``resources_sql(datasette, actor)`` method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``resources_sql()`` classmethod returns a SQL query that lists all resources of that type that exist in the system. It can be async because Datasette calls it with ``await``, and it receives the current ``datasette`` instance plus an optional ``actor`` argument. This query is used by Datasette to efficiently check permissions across multiple resources at once. When a user requests a list of resources (like tables, documents, or other entities), Datasette uses this SQL to: @@ -984,7 +990,7 @@ For example, if you're building a document management plugin with collections an .. code-block:: python @classmethod - def resources_sql(cls) -> str: + async def resources_sql(cls, datasette, actor=None) -> str: return """ SELECT collection_name AS parent, document_id AS child FROM documents