is_anonymous, login_required, has_permission helpers (#114)

* add is_anonymous helper function and login_required, has_permission decorators

* add docs for `is_anonymous`, `login_required` and `has_permission` functions

* permission can be `enum.Enum` object; cover with tests

* isort fix

aiohttp_security/__init__.py

@@ -1,13 +1,14 @@
-from .abc import AbstractIdentityPolicy, AbstractAuthorizationPolicy
-from .api import remember, forget, setup, authorized_userid, permits
+from .abc import AbstractAuthorizationPolicy, AbstractIdentityPolicy
+from .api import (authorized_userid, forget, has_permission, is_anonymous,
+                  login_required, permits, remember, setup)
 from .cookies_identity import CookiesIdentityPolicy
 from .session_identity import SessionIdentityPolicy
 
-
 __version__ = '0.1.2'
 
 
 __all__ = ('AbstractIdentityPolicy', 'AbstractAuthorizationPolicy',
            'CookiesIdentityPolicy', 'SessionIdentityPolicy',
            'remember', 'forget', 'authorized_userid',
-           'permits', 'setup')
+           'permits', 'setup', 'is_anonymous',
+           'login_required', 'has_permission')

aiohttp_security/api.py

@@ -1,7 +1,9 @@
 import asyncio
+import enum
 from aiohttp import web
 from aiohttp_security.abc import (AbstractIdentityPolicy,
                                   AbstractAuthorizationPolicy)
+from functools import wraps
 
 IDENTITY_KEY = 'aiohttp_security_identity_policy'
 AUTZ_KEY = 'aiohttp_security_autz_policy'
@@ -62,7 +64,7 @@ def authorized_userid(request):
 
 @asyncio.coroutine
 def permits(request, permission, context=None):
-    assert isinstance(permission, str), permission
+    assert isinstance(permission, (str, enum.Enum)), permission
     assert permission
     identity_policy = request.app.get(IDENTITY_KEY)
     autz_policy = request.app.get(AUTZ_KEY)
@@ -74,6 +76,85 @@ def permits(request, permission, context=None):
     return access
 
 
+@asyncio.coroutine
+def is_anonymous(request):
+    """Check if user is anonymous.
+
+    User is considered anonymous if there is not identity
+    in request.
+    """
+    identity_policy = request.app.get(IDENTITY_KEY)
+    if identity_policy is None:
+        return True
+    identity = yield from identity_policy.identify(request)
+    if identity is None:
+        return True
+    return False
+
+
+def login_required(fn):
+    """Decorator that restrict access only for authorized users.
+
+    User is considered authorized if authorized_userid
+    returns some value.
+    """
+    @asyncio.coroutine
+    @wraps(fn)
+    def wrapped(*args, **kwargs):
+        request = args[-1]
+        if not isinstance(request, web.BaseRequest):
+            msg = ("Incorrect decorator usage. "
+                   "Expecting `def handler(request)` "
+                   "or `def handler(self, request)`.")
+            raise RuntimeError(msg)
+
+        userid = yield from authorized_userid(request)
+        if userid is None:
+            raise web.HTTPUnauthorized
+
+        ret = yield from fn(*args, **kwargs)
+        return ret
+
+    return wrapped
+
+
+def has_permission(
+    permission,
+    context=None,
+):
+    """Decorator that restrict access only for authorized users
+    with correct permissions.
+
+    If user is not authorized - raises HTTPUnauthorized,
+    if user is authorized and does not have permission -
+    raises HTTPForbidden.
+    """
+    def wrapper(fn):
+        @asyncio.coroutine
+        @wraps(fn)
+        def wrapped(*args, **kwargs):
+            request = args[-1]
+            if not isinstance(request, web.BaseRequest):
+                msg = ("Incorrect decorator usage. "
+                       "Expecting `def handler(request)` "
+                       "or `def handler(self, request)`.")
+                raise RuntimeError(msg)
+
+            userid = yield from authorized_userid(request)
+            if userid is None:
+                raise web.HTTPUnauthorized
+
+            allowed = yield from permits(request, permission, context)
+            if not allowed:
+                raise web.HTTPForbidden
+            ret = yield from fn(*args, **kwargs)
+            return ret
+
+        return wrapped
+
+    return wrapper
+
+
 def setup(app, identity_policy, autz_policy):
     assert isinstance(identity_policy, AbstractIdentityPolicy), identity_policy
     assert isinstance(autz_policy, AbstractAuthorizationPolicy), autz_policy