From a0f73c85ebcbdd0b4569c65e2c243f5b218044d7 Mon Sep 17 00:00:00 2001
From: Andrew Svetlov <andrew.svetlov@gmail.com>
Date: Thu, 29 Oct 2015 10:31:24 +0200
Subject: [PATCH] More docs
---
aiohttp_security/api.py | 6 ++++++
docs/reference.rst | 22 +++++++++++++++++++++-
docs/usage.rst | 4 ++++
3 files changed, 31 insertions(+), 1 deletion(-)
create mode 100644 docs/usage.rst
diff --git a/aiohttp_security/api.py b/aiohttp_security/api.py
index 4ffea01..26cfdad 100644
--- a/aiohttp_security/api.py
+++ b/aiohttp_security/api.py
@@ -9,6 +9,12 @@ AUTZ_KEY = 'aiohttp_security_autz_policy'
@asyncio.coroutine
def remember(request, response, identity, **kwargs):
+ """Remember identity into response.
+
+ The action is performed by indentity_policy.remember()
+ Usually the idenity is stored in user cookies homehow.
+ """
+ assert isinstance(identity, str), identity
identity_policy = request.app.get(IDENTITY_KEY)
if identity_policy is None:
text = ("Security subsystem is not initialized, "
diff --git a/docs/reference.rst b/docs/reference.rst
index 492b92c..308e4b6 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -15,13 +15,33 @@ Public API functions
.. coroutine:: remember(request, response, identity, **kwargs)
- Remember identity
+ Remember identity into response.
+ The action is performed by registered
+ :coroutinemethod:`AbstractIdentityPolicy.remember`.
+
+ Usually the *idenity* is stored in user cookies homehow for using by
+ :coroutine:`authorized_userid` and :coroutine:`permits`.
+
+ :param request: :class:`aiohttp.web.Request` object.
+
+ :param response: :class:`aiohttp.web.StreamResponse` and
+ descendants like :class:`aiohttp.web.Response`.
+
+ :param str identity: :class:`aiohttp.web.Request` object.
.. function:: setup(app, identity_policy, autz_policy)
Setup :mod:`aiohttp` application with security policies.
+ :param app: aiohttp :class:`aiohttp.web.Application` instance.
+
+ :param identity_policy: indentification policy, an
+ :class:`AbstractIdentityPolicy` instance.
+
+ :param autz_policy: authorization policy, an
+ :class:`AbstractAuthorizationPolicy` instance.
+
Abstract policies
=================
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..d4ef6c2
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,4 @@
+identity is a string shared between browser and server.
+Thus it should not be database primary key etc.
+Random string like uuid or hash is better choice.
+