PluginSQL renamed to PermissionSQL, closes #2524

datasette/app.py

@@ -115,7 +115,8 @@ from .tracer import AsgiTracer
 from .plugins import pm, DEFAULT_PLUGINS, get_plugins
 from .version import __version__
 
-from .utils.permissions import build_rules_union, PluginSQL
+from .permissions import PermissionSQL
+from .utils.permissions import build_rules_union
 
 app_root = Path(__file__).parent.parent
 
@@ -1067,11 +1068,11 @@ class Datasette:
     async def allowed_resources_sql(
         self, actor: dict | None, action: str
     ) -> tuple[str, dict]:
-        """Combine permission_resources_sql PluginSQL blocks into a UNION query.
+        """Combine permission_resources_sql PermissionSQL blocks into a UNION query.
 
         Returns a (sql, params) tuple suitable for execution against SQLite.
         """
-        plugin_blocks: List[PluginSQL] = []
+        plugin_blocks: List[PermissionSQL] = []
         for block in pm.hook.permission_resources_sql(
             datasette=self,
             actor=actor,
@@ -1087,7 +1088,7 @@ class Datasette:
             for candidate in candidates:
                 if candidate is None:
                     continue
-                if not isinstance(candidate, PluginSQL):
+                if not isinstance(candidate, PermissionSQL):
                     continue
                 plugin_blocks.append(candidate)
 

datasette/default_permissions.py

@@ -1,5 +1,5 @@
 from datasette import hookimpl, Permission
-from datasette.utils.permissions import PluginSQL
+from datasette.permissions import PermissionSQL
 from datasette.utils import actor_matches_allow
 import itsdangerous
 import time
@@ -174,7 +174,7 @@ def permission_allowed_default(datasette, actor, action, resource):
 
 @hookimpl
 async def permission_resources_sql(datasette, actor, action):
-    rules: list[PluginSQL] = []
+    rules: list[PermissionSQL] = []
 
     config_rules = await _config_permission_rules(datasette, actor, action)
     rules.extend(config_rules)
@@ -191,7 +191,7 @@ async def permission_resources_sql(datasette, actor, action):
             "SELECT NULL AS parent, NULL AS child, 1 AS allow, " f"'{reason}' AS reason"
         )
         rules.append(
-            PluginSQL(
+            PermissionSQL(
                 source="default_permissions",
                 sql=sql,
                 params={},
@@ -205,7 +205,7 @@ async def permission_resources_sql(datasette, actor, action):
     return rules
 
 
-async def _config_permission_rules(datasette, actor, action) -> list[PluginSQL]:
+async def _config_permission_rules(datasette, actor, action) -> list[PermissionSQL]:
     config = datasette.config or {}
 
     if actor is None:
@@ -332,7 +332,7 @@ async def _config_permission_rules(datasette, actor, action) -> list[PluginSQL]:
         params[f"{key}_reason"] = reason
 
     sql = "\nUNION ALL\n".join(parts)
-    return [PluginSQL(source="config_permissions", sql=sql, params=params)]
+    return [PermissionSQL(source="config_permissions", sql=sql, params=params)]
 
 
 async def _resolve_config_permissions_blocks(datasette, actor, action, resource):

datasette/hookspecs.py

@@ -124,8 +124,8 @@ def permission_allowed(datasette, actor, action, resource):
 def permission_resources_sql(datasette, actor, action):
     """Return SQL query fragments for permission checks on resources.
 
-    Returns None, a PluginSQL object, or a list of PluginSQL objects.
-    Each PluginSQL contains SQL that should return rows with columns:
+    Returns None, a PermissionSQL object, or a list of PermissionSQL objects.
+    Each PermissionSQL contains SQL that should return rows with columns:
     parent (str|None), child (str|None), allow (int), reason (str).
 
     Used to efficiently check permissions across multiple resources at once.

datasette/permissions.py

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Optional, NamedTuple
+from typing import Any, Dict, Optional, NamedTuple
 
 
 class Resource(ABC):
@@ -86,6 +86,21 @@ class Action:
     resource_class: type[Resource]
 
 
+@dataclass
+class PermissionSQL:
+    """
+    A plugin contributes SQL that yields:
+      parent TEXT NULL,
+      child  TEXT NULL,
+      allow  INTEGER,    -- 1 allow, 0 deny
+      reason TEXT
+    """
+
+    source: str  # identifier used for auditing (e.g., plugin name)
+    sql: str  # SQL that SELECTs the 4 columns above
+    params: Dict[str, Any]  # bound params for the SQL (values only; no ':' prefix)
+
+
 # This is obsolete, replaced by Action and ResourceType
 @dataclass
 class Permission:

datasette/utils/actions_sql.py

@@ -22,7 +22,7 @@ The core pattern is:
 from typing import Optional
 from datasette.plugins import pm
 from datasette.utils import await_me_maybe
-from datasette.utils.permissions import PluginSQL
+from datasette.permissions import PermissionSQL
 
 
 async def build_allowed_resources_sql(
@@ -80,10 +80,10 @@ async def build_allowed_resources_sql(
             continue
         if isinstance(result, list):
             for plugin_sql in result:
-                if isinstance(plugin_sql, PluginSQL):
+                if isinstance(plugin_sql, PermissionSQL):
                     rule_sqls.append(plugin_sql.sql)
                     all_params.update(plugin_sql.params)
-        elif isinstance(result, PluginSQL):
+        elif isinstance(result, PermissionSQL):
             rule_sqls.append(result.sql)
             all_params.update(result.params)
 
@@ -211,10 +211,10 @@ async def check_permission_for_resource(
             continue
         if isinstance(result, list):
             for plugin_sql in result:
-                if isinstance(plugin_sql, PluginSQL):
+                if isinstance(plugin_sql, PermissionSQL):
                     rule_sqls.append(plugin_sql.sql)
                     all_params.update(plugin_sql.params)
-        elif isinstance(result, PluginSQL):
+        elif isinstance(result, PermissionSQL):
             rule_sqls.append(result.sql)
             all_params.update(result.params)
 

datasette/utils/permissions.py

@@ -1,31 +1,17 @@
 # perm_utils.py
 from __future__ import annotations
 
-from dataclasses import dataclass
 from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, Union
 import sqlite3
 
+from datasette.permissions import PermissionSQL
+
 
 # -----------------------------
 # Plugin interface & utilities
 # -----------------------------
 
 
-@dataclass
-class PluginSQL:
-    """
-    A plugin contributes SQL that yields:
-      parent TEXT NULL,
-      child  TEXT NULL,
-      allow  INTEGER,    -- 1 allow, 0 deny
-      reason TEXT
-    """
-
-    source: str  # identifier used for auditing (e.g., plugin name)
-    sql: str  # SQL that SELECTs the 4 columns above
-    params: Dict[str, Any]  # bound params for the SQL (values only; no ':' prefix)
-
-
 def _namespace_params(i: int, params: Dict[str, Any]) -> Tuple[str, Dict[str, Any]]:
     """
     Rewrite parameter placeholders to distinct names per plugin block.
@@ -45,12 +31,12 @@ def _namespace_params(i: int, params: Dict[str, Any]) -> Tuple[str, Dict[str, An
     return rewrite, namespaced
 
 
-PluginProvider = Callable[[str], PluginSQL]
-PluginOrFactory = Union[PluginSQL, PluginProvider]
+PluginProvider = Callable[[str], PermissionSQL]
+PluginOrFactory = Union[PermissionSQL, PluginProvider]
 
 
 def build_rules_union(
-    actor: str, plugins: Sequence[PluginSQL]
+    actor: str, plugins: Sequence[PermissionSQL]
 ) -> Tuple[str, Dict[str, Any]]:
     """
     Compose plugin SQL into a UNION ALL with namespaced parameters.
@@ -107,8 +93,8 @@ async def resolve_permissions_from_catalog(
         (Use child=NULL for parent-scoped actions like "execute-sql".)
       - *db* exposes: rows = await db.execute(sql, params)
         where rows is an iterable of sqlite3.Row
-      - plugins are either PluginSQL objects or callables accepting (action: str)
-        and returning PluginSQL instances selecting (parent, child, allow, reason)
+      - plugins are either PermissionSQL objects or callables accepting (action: str)
+        and returning PermissionSQL instances selecting (parent, child, allow, reason)
 
     Decision policy:
       1) Specificity first: child (depth=2) > parent (depth=1) > root (depth=0)
@@ -121,14 +107,14 @@ async def resolve_permissions_from_catalog(
       - parent, child, allow, reason, source_plugin, depth
       - resource (rendered "/parent/child" or "/parent" or "/")
     """
-    resolved_plugins: List[PluginSQL] = []
+    resolved_plugins: List[PermissionSQL] = []
     for plugin in plugins:
-        if callable(plugin) and not isinstance(plugin, PluginSQL):
+        if callable(plugin) and not isinstance(plugin, PermissionSQL):
             resolved = plugin(action)  # type: ignore[arg-type]
         else:
             resolved = plugin  # type: ignore[assignment]
-        if not isinstance(resolved, PluginSQL):
-            raise TypeError("Plugin providers must return PluginSQL instances")
+        if not isinstance(resolved, PermissionSQL):
+            raise TypeError("Plugin providers must return PermissionSQL instances")
         resolved_plugins.append(resolved)
 
     union_sql, rule_params = build_rules_union(actor, resolved_plugins)

datasette/views/special.py

@@ -9,7 +9,8 @@ from datasette.utils import (
     tilde_encode,
     tilde_decode,
 )
-from datasette.utils.permissions import PluginSQL, resolve_permissions_from_catalog
+from datasette.permissions import PermissionSQL
+from datasette.utils.permissions import resolve_permissions_from_catalog
 from datasette.plugins import pm
 from .base import BaseView, View
 import secrets
@@ -303,9 +304,9 @@ class AllowedResourcesView(BaseView):
             for candidate in candidates:
                 if candidate is None:
                     continue
-                if not isinstance(candidate, PluginSQL):
+                if not isinstance(candidate, PermissionSQL):
                     logger.warning(
-                        "Skipping permission_resources_sql result %r from plugin; expected PluginSQL",
+                        "Skipping permission_resources_sql result %r from plugin; expected PermissionSQL",
                         candidate,
                     )
                     continue