Extend permission-checking methods to return additional information

[atemate]

Extend async def check_permission(request, permission, context=None) -> bool to return back additional information.

Method check_permission() calls method async def permits(...) -> bool declared in AuthPolicy and defined in user-defined policies that inherit AuthPolicy. We need to have a general and unified way to return back information from permits() (and thus check_permission()).

Use case: check_permission is called on a bunch of permissions and the calling code wants to know which exactly permission check was failed.

Possible solutions:

1. More narrow approach. In order to preserve backward compatibility, we could add method check_permissions() -> PermissionCheckResult (in addition to permits() -> bool) that returns a general dataclass (or json object) that will consolidate information on the permission check, for example:

T = TypeVar('T')

@dataclass
class PermissionCheckResult:
    success: bool
    missing: Set[T]

async def check_permissions(...) -> PermissionCheckResult:
    ...

2. More general and more pythonic approach. Keep permits() -> bool, but allow it to raise a pre-defined exception for providing additional information:

class PermissionDeniedException(Exception):
    def __init__(self, missing_permissions):
        pass

[bitnom]

You mean to check multiple permissions?

[atemate]

Yes. To check multiple permissions and get the set of missing permissions in the answer.