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

tests/test_dict_autz.py

@@ -1,10 +1,11 @@
 import asyncio
+import enum
 
 from aiohttp import web
-from aiohttp_security import (remember,
-                              authorized_userid, permits,
-                              AbstractAuthorizationPolicy)
 from aiohttp_security import setup as _setup
+from aiohttp_security import (AbstractAuthorizationPolicy, authorized_userid,
+                              forget, has_permission, is_anonymous,
+                              login_required, permits, remember)
 from aiohttp_security.cookies_identity import CookiesIdentityPolicy
 
 
@@ -73,7 +74,27 @@ def test_authorized_userid_not_authorized(loop, test_client):
 
 
 @asyncio.coroutine
-def test_permits(loop, test_client):
+def test_permits_enum_permission(loop, test_client):
+    class Permission(enum.Enum):
+        READ = '101'
+        WRITE = '102'
+        UNKNOWN = '103'
+
+    class Autz(AbstractAuthorizationPolicy):
+
+        @asyncio.coroutine
+        def permits(self, identity, permission, context=None):
+            if identity == 'UserID':
+                return permission in {Permission.READ, Permission.WRITE}
+            else:
+                return False
+
+        @asyncio.coroutine
+        def authorized_userid(self, identity):
+            if identity == 'UserID':
+                return 'Andrew'
+            else:
+                return None
 
     @asyncio.coroutine
     def login(request):
@@ -83,11 +104,11 @@ def test_permits(loop, test_client):
 
     @asyncio.coroutine
     def check(request):
-        ret = yield from permits(request, 'read')
+        ret = yield from permits(request, Permission.READ)
         assert ret
-        ret = yield from permits(request, 'write')
+        ret = yield from permits(request, Permission.WRITE)
         assert ret
-        ret = yield from permits(request, 'unknown')
+        ret = yield from permits(request, Permission.UNKNOWN)
         assert not ret
         return web.Response()
 
@@ -121,3 +142,143 @@ def test_permits_unauthorized(loop, test_client):
     resp = yield from client.get('/')
     assert 200 == resp.status
     yield from resp.release()
+
+
+@asyncio.coroutine
+def test_is_anonymous(loop, test_client):
+
+    @asyncio.coroutine
+    def index(request):
+        is_anon = yield from is_anonymous(request)
+        if is_anon:
+            return web.HTTPUnauthorized()
+        return web.HTTPOk()
+
+    @asyncio.coroutine
+    def login(request):
+        response = web.HTTPFound(location='/')
+        yield from remember(request, response, 'UserID')
+        return response
+
+    @asyncio.coroutine
+    def logout(request):
+        response = web.HTTPFound(location='/')
+        yield from forget(request, response)
+        return response
+
+    app = web.Application(loop=loop)
+    _setup(app, CookiesIdentityPolicy(), Autz())
+    app.router.add_route('GET', '/', index)
+    app.router.add_route('POST', '/login', login)
+    app.router.add_route('POST', '/logout', logout)
+    client = yield from test_client(app)
+    resp = yield from client.get('/')
+    assert web.HTTPUnauthorized.status_code == resp.status
+
+    yield from client.post('/login')
+    resp = yield from client.get('/')
+    assert web.HTTPOk.status_code == resp.status
+
+    yield from client.post('/logout')
+    resp = yield from client.get('/')
+    assert web.HTTPUnauthorized.status_code == resp.status
+
+
+@asyncio.coroutine
+def test_login_required(loop, test_client):
+    @login_required
+    @asyncio.coroutine
+    def index(request):
+        return web.HTTPOk()
+
+    @asyncio.coroutine
+    def login(request):
+        response = web.HTTPFound(location='/')
+        yield from remember(request, response, 'UserID')
+        return response
+
+    @asyncio.coroutine
+    def logout(request):
+        response = web.HTTPFound(location='/')
+        yield from forget(request, response)
+        return response
+
+    app = web.Application(loop=loop)
+    _setup(app, CookiesIdentityPolicy(), Autz())
+    app.router.add_route('GET', '/', index)
+    app.router.add_route('POST', '/login', login)
+    app.router.add_route('POST', '/logout', logout)
+    client = yield from test_client(app)
+    resp = yield from client.get('/')
+    assert web.HTTPUnauthorized.status_code == resp.status
+
+    yield from client.post('/login')
+    resp = yield from client.get('/')
+    assert web.HTTPOk.status_code == resp.status
+
+    yield from client.post('/logout')
+    resp = yield from client.get('/')
+    assert web.HTTPUnauthorized.status_code == resp.status
+
+
+@asyncio.coroutine
+def test_has_permission(loop, test_client):
+
+    @has_permission('read')
+    @asyncio.coroutine
+    def index_read(request):
+        return web.HTTPOk()
+
+    @has_permission('write')
+    @asyncio.coroutine
+    def index_write(request):
+        return web.HTTPOk()
+
+    @has_permission('forbid')
+    @asyncio.coroutine
+    def index_forbid(request):
+        return web.HTTPOk()
+
+    @asyncio.coroutine
+    def login(request):
+        response = web.HTTPFound(location='/')
+        yield from remember(request, response, 'UserID')
+        return response
+
+    @asyncio.coroutine
+    def logout(request):
+        response = web.HTTPFound(location='/')
+        yield from forget(request, response)
+        return response
+
+    app = web.Application(loop=loop)
+    _setup(app, CookiesIdentityPolicy(), Autz())
+    app.router.add_route('GET', '/permission/read', index_read)
+    app.router.add_route('GET', '/permission/write', index_write)
+    app.router.add_route('GET', '/permission/forbid', index_forbid)
+    app.router.add_route('POST', '/login', login)
+    app.router.add_route('POST', '/logout', logout)
+    client = yield from test_client(app)
+
+    resp = yield from client.get('/permission/read')
+    assert web.HTTPUnauthorized.status_code == resp.status
+    resp = yield from client.get('/permission/write')
+    assert web.HTTPUnauthorized.status_code == resp.status
+    resp = yield from client.get('/permission/forbid')
+    assert web.HTTPUnauthorized.status_code == resp.status
+
+    yield from client.post('/login')
+    resp = yield from client.get('/permission/read')
+    assert web.HTTPOk.status_code == resp.status
+    resp = yield from client.get('/permission/write')
+    assert web.HTTPOk.status_code == resp.status
+    resp = yield from client.get('/permission/forbid')
+    assert web.HTTPForbidden.status_code == resp.status
+
+    yield from client.post('/logout')
+    resp = yield from client.get('/permission/read')
+    assert web.HTTPUnauthorized.status_code == resp.status
+    resp = yield from client.get('/permission/write')
+    assert web.HTTPUnauthorized.status_code == resp.status
+    resp = yield from client.get('/permission/forbid')
+    assert web.HTTPUnauthorized.status_code == resp.status