issue_comments

Updated documentation: https://github.com/simonw/datasette/blob/e627510b760198ccedba9e5af47a771e847785c9/docs/internals.rst#await-ensure_permissionsactor-permissions

This method allows multiple permissions to be checked at onced. It raises a datasette.Forbidden exception if any of the checks are denied before one of them is explicitly granted.

This is useful when you need to check multiple permissions at once. For example, an actor should be able to view a table if either one of the following checks returns True or not a single one of them returns False:

That's pretty hard to understand! I'm going to open a separate issue to reconsider if this is a useful enough abstraction given how confusing it is.

Also calling that function permissions_allowed() is confusing because there is a plugin hook with a similar name already: https://docs.datasette.io/en/stable/plugin_hooks.html#permission-allowed-datasette-actor-action-resource

Idea: ds.permission_allowed() continues to just return True or False.

A new ds.ensure_permissions(...) method is added which raises a Forbidden exception if a check fails (hence the different name)`.

One benefit of the current design of check_permissions that raises an exception is that the exception includes information on WHICH of the permission checks failed. Returning just True or False loses that information.

I could return an object which evaluates to False but also carries extra information? Bit weird, I've never seen anything like that in other Python code.

The other difference though is that ds.permission_allowed(...) works against an actor, while check_permission() works against a request (though just to access request.actor).

Though at that point check_permission is such a light wrapper around self.ds.permission_allowed() that there's little point in it existing at all.

So maybe check_permisions() becomes ds.permissions_allowed().

permission_allowed() v.s. permissions_allowed() is a bit of a subtle naming difference, but I think it works.

A slightly odd thing about these methods is that they either fail silently or they raise a Forbidden exception.

Maybe they should instead return True or False and the calling code could decide if it wants to raise the exception? That would make them more usable and a little less surprising.