Continue working on documentation

aiohttp_security/abc.py

@@ -21,7 +21,7 @@ def remember(self, request, response, identity, **kwargs):
         Modify response object by filling it's headers with remembered user.
 
         An individual identity policy and its consumers can decide on
-        the composition and meaning of **kw.
+        the composition and meaning of **kwargs.
         """
         pass
 

docs/glossary.rst

@@ -31,8 +31,8 @@
 
       Stored in local storage (client-side cookie or server-side storage).
 
-      Use :coroutine:`~aiohttp_session.remember` for saving *identity* (login)
-      and :coroutine:`~aiohttp_session.forget` for dropping it (logout).
+      Use :coroutine:`~aiohttp_session.remember` for saving *identity* (sign in)
+      and :coroutine:`~aiohttp_session.forget` for dropping it (sign out).
 
       *identity* is used for getting :term:`userid` and :term:`permissions`.
 

docs/reference.rst

@@ -58,13 +58,35 @@ Public API functions
 
    :param request: :class:`aiohttp.web.Request` object.
 
-   :return: :class:`str` :term:`userid` or ``None`` for not signed in users.
+   :return: :class:`str` :term:`userid` or ``None`` for session
+            without signed in user.
 
 
 .. coroutine:: permits(request, permission, context=None)
 
+   Check user's permission.
+
+   Return ``True`` if user remembered in *request* has specified *permission*.
+
+   Allowed permissions as well as *context* meaning are depends on
+   :class:`AbstractAuthorizationPolicy` implementation.
+
+   Actually it's a wrapper around
+   :meth:`AbstractAuthorizationPolicy.permits` coroutine.
+
+   The user should be registered by :coroutine:`remember` before the call.
+
    :param request: :class:`aiohttp.web.Request` object.
 
+   :param permission: requested permission. May be :class:`str` or
+                      more complex object -- see used
+                      :class:`AbstractAuthorizationPolicy`
+                      implementation.
+
+   :param context: additional object may be passed into
+                   :meth:`AbstractAuthorizationPolicy.permission`
+                   coroutine.
+
    :return: ``True`` if registered user has requested *permission*,
             ``False`` otherwise.
 
@@ -85,4 +107,73 @@ Public API functions
 Abstract policies
 =================
 
+*aiohttp_security* is built on top of two *abstract policies* --
+ :class:`AbstractIdentityPolicy` and
+ :class:`AbstractAuthorizationPolicy`.
+
+The first one responds on remembering, retrieving and forgetting
+:term:`identity` into some session storage, e.g. HTTP cookie or
+authorization token.
+
+The second is responsible to return persistent :term:`userid` for
+session-wide :term:`identity` and check user's permissions.
+
+Most likely sofware developer reuses one of pre-implemented *identity
+policies* from *aiohttp_security* but build *authorization policy*
+from scratch for every application/project.
+
+
+Identification policy
+---------------------
+
+.. class:: AbstractIdentityPolicy
+
+   .. coroutinemethod:: identify(request)
+
+      Extract :term:`identity` from *request*.
+
+      Abstract method, should be overriden by descendant.
+
+      :param request: :class:`aiohttp.web.Request` object.
+
+      :return: the claimed identity of the user associated request or
+               ``None`` if no identity can be found associated with
+               the request.
+
+   .. coroutinemethod:: remember(request, response, identity, **kwargs)
+
+      Remember *identity*.
+
+      May use *request* for accessing required data and *response* for
+      storing *identity* (e.g. updating HTTP response cookies).
+
+      *kwargs* may be used by concrete implementation for passing
+      additional data.
+
+      Abstract method, should be overriden by descendant.
+
+      :param request: :class:`aiohttp.web.Request` object.
+
+      :param response: :class:`aiohttp.web.StreamResponse` object or
+                       derivative.
+
+      :param identity: :term:`identity` to store.
+
+      :param kwargs: optional additional arguments. An individual
+                     identity policy and its consumers can decide on
+                     the composition and meaning of the parameter.
+
+
+   .. coroutinemethod:: forget(request, response)
+
+      Forget previously stored :term:`identity`.
+
+      May use *request* for accessing required data and *response* for
+      dropping *identity* (e.g. updating HTTP response cookies).
+
+      Abstract method, should be overriden by descendant.
+
+      :param request: :class:`aiohttp.web.Request` object.
 
+      :param response: :class:`aiohttp.web.StreamResponse` object or
+                       derivative.