Documented datasette.check_visibility() method, closes #1678

datasette/app.py

@@ -664,6 +664,24 @@ class Datasette:
                 else:
                     raise Forbidden(action)
 
+    async def check_visibility(self, actor, action, resource):
+        """Returns (visible, private) - visible = can you see it, private = can others see it too"""
+        visible = await self.permission_allowed(
+            actor,
+            action,
+            resource=resource,
+            default=True,
+        )
+        if not visible:
+            return False, False
+        private = not await self.permission_allowed(
+            None,
+            action,
+            resource=resource,
+            default=True,
+        )
+        return visible, private
+
     async def execute(
         self,
         db_name,

datasette/utils/__init__.py

@@ -1002,25 +1002,6 @@ def actor_matches_allow(actor, allow):
     return False
 
 
-async def check_visibility(datasette, actor, action, resource, default=True):
-    """Returns (visible, private) - visible = can you see it, private = can others see it too"""
-    visible = await datasette.permission_allowed(
-        actor,
-        action,
-        resource=resource,
-        default=default,
-    )
-    if not visible:
-        return False, False
-    private = not await datasette.permission_allowed(
-        None,
-        action,
-        resource=resource,
-        default=default,
-    )
-    return visible, private
-
-
 def resolve_env_secrets(config, environ):
     """Create copy that recursively replaces {"$env": "NAME"} with values from environ"""
     if isinstance(config, dict):

datasette/views/database.py

@@ -10,7 +10,6 @@ import markupsafe
 from datasette.utils import (
     add_cors_headers,
     await_me_maybe,
-    check_visibility,
     derive_named_parameters,
     tilde_decode,
     to_css_class,
@@ -62,8 +61,7 @@ class DatabaseView(DataView):
 
         views = []
         for view_name in await db.view_names():
-            visible, private = await check_visibility(
-                self.ds,
+            visible, private = await self.ds.check_visibility(
                 request.actor,
                 "view-table",
                 (database, view_name),
@@ -78,8 +76,7 @@ class DatabaseView(DataView):
 
         tables = []
         for table in table_counts:
-            visible, private = await check_visibility(
-                self.ds,
+            visible, private = await self.ds.check_visibility(
                 request.actor,
                 "view-table",
                 (database, table),
@@ -105,8 +102,7 @@ class DatabaseView(DataView):
         for query in (
             await self.ds.get_canned_queries(database, request.actor)
         ).values():
-            visible, private = await check_visibility(
-                self.ds,
+            visible, private = await self.ds.check_visibility(
                 request.actor,
                 "view-query",
                 (database, query["name"]),

datasette/views/index.py

@@ -1,7 +1,7 @@
 import hashlib
 import json
 
-from datasette.utils import add_cors_headers, check_visibility, CustomJSONEncoder
+from datasette.utils import add_cors_headers, CustomJSONEncoder
 from datasette.utils.asgi import Response
 from datasette.version import __version__
 
@@ -23,8 +23,7 @@ class IndexView(BaseView):
         await self.ds.ensure_permissions(request.actor, ["view-instance"])
         databases = []
         for name, db in self.ds.databases.items():
-            visible, database_private = await check_visibility(
-                self.ds,
+            visible, database_private = await self.ds.check_visibility(
                 request.actor,
                 "view-database",
                 name,
@@ -36,8 +35,7 @@ class IndexView(BaseView):
 
             views = []
             for view_name in await db.view_names():
-                visible, private = await check_visibility(
-                    self.ds,
+                visible, private = await self.ds.check_visibility(
                     request.actor,
                     "view-table",
                     (name, view_name),
@@ -55,8 +53,7 @@ class IndexView(BaseView):
 
             tables = {}
             for table in table_names:
-                visible, private = await check_visibility(
-                    self.ds,
+                visible, private = await self.ds.check_visibility(
                     request.actor,
                     "view-table",
                     (name, table),

docs/internals.rst

@@ -295,7 +295,7 @@ If neither ``metadata.json`` nor any of the plugins provide an answer to the per
 
 See :ref:`permissions` for a full list of permission actions included in Datasette core.
 
-.. _datasette_permission_allowed:
+.. _datasette_ensure_permissions:
 
 await .ensure_permissions(actor, permissions)
 ---------------------------------------------
@@ -321,6 +321,32 @@ This is useful when you need to check multiple permissions at once. For example,
         ]
     )
 
+.. _datasette_check_visibilty:
+
+await .check_visibility(actor, action, resource=None)
+-----------------------------------------------------
+
+``actor`` - dictionary
+    The authenticated actor. This is usually ``request.actor``.
+
+``action`` - string
+    The name of the action that is being permission checked.
+
+``resource`` - string or tuple, optional
+    The resource, e.g. the name of the database, or a tuple of two strings containing the name of the database and the name of the table. Only some permissions apply to a resource.
+
+This convenience method can be used to answer the question "should this item be considered private, in that it is visible to me but it is not visible to anonymous users?"
+
+It returns a tuple of two booleans, ``(visible, private)``. ``visible`` indicates if the actor can see this resource. ``private`` will be ``True`` if an anonymous user would not be able to view the resource.
+
+This example checks if the user can access a specific table, and sets ``private`` so that a padlock icon can later be displayed:
+
+.. code-block:: python
+
+    visible, private = await self.ds.check_visibility(
+        request.actor, "view-table", (database, table)
+    )
+
 .. _datasette_get_database:
 
 .get_database(name)