From d02faf69e7522f6365a28673ed691984d6e1e971 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Fri, 6 Nov 2015 22:45:20 +0800 Subject: [PATCH] Work on docs --- aiohttp_security/abc.py | 14 +++++++--- docs/aiohttp_doctools.py | 27 ++++++++++++++++++++ docs/conf.py | 2 ++ docs/reference.rst | 55 ++++++++++++++++++++++++++++++---------- 4 files changed, 81 insertions(+), 17 deletions(-) create mode 100644 docs/aiohttp_doctools.py diff --git a/aiohttp_security/abc.py b/aiohttp_security/abc.py index 8be05c0..b1f9f2a 100644 --- a/aiohttp_security/abc.py +++ b/aiohttp_security/abc.py @@ -38,13 +38,19 @@ class AbstractAuthorizationPolicy(metaclass=abc.ABCMeta): @asyncio.coroutine @abc.abstractmethod def permits(self, identity, permission, context=None): - """ Return True if the identity is allowed the permission in the - current context, else return False""" + """Check user permissions. + + Return True if the identity is allowed the permission in the + current context, else return False. + """ pass @asyncio.coroutine @abc.abstractmethod def authorized_userid(self, identity): - """ Return the user_id of the user identified by the identity - or 'None' if no user exists related to the identity """ + """Retrieve authorized user id. + + Return the user_id of the user identified by the identity + or 'None' if no user exists related to the identity. + """ pass diff --git a/docs/aiohttp_doctools.py b/docs/aiohttp_doctools.py new file mode 100644 index 0000000..fb21066 --- /dev/null +++ b/docs/aiohttp_doctools.py @@ -0,0 +1,27 @@ +from sphinx.domains.python import PyModulelevel, PyClassmember +from sphinx import addnodes + + +class PyCoroutineMixin(object): + def handle_signature(self, sig, signode): + ret = super(PyCoroutineMixin, self).handle_signature(sig, signode) + signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine ')) + return ret + + +class PyCoroutineFunction(PyCoroutineMixin, PyModulelevel): + def run(self): + self.name = 'py:function' + return PyModulelevel.run(self) + + +class PyCoroutineMethod(PyCoroutineMixin, PyClassmember): + def run(self): + self.name = 'py:method' + return PyClassmember.run(self) + + +def setup(app): + app.add_directive_to_domain('py', 'coroutinefunction', PyCoroutineFunction) + app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod) + return {'version': '1.0', 'parallel_read_safe': True} diff --git a/docs/conf.py b/docs/conf.py index b4cfef5..efd71f1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,7 @@ with codecs.open(_version_path, 'r', 'latin1') as fp: # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('.')) import alabaster @@ -54,6 +55,7 @@ extensions = [ 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', 'alabaster', + 'aiohttp_doctools', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/reference.rst b/docs/reference.rst index 4ef5f9a..d721cf3 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -13,16 +13,16 @@ Public API functions ==================== -.. coroutine:: remember(request, response, identity, **kwargs) +.. coroutinefunction:: remember(request, response, identity, **kwargs) Remember *identity* in *response*, e.g. by storing a cookie or saving info into session. The action is performed by registered - :coroutinemethod:`AbstractIdentityPolicy.remember`. + :meth:`AbstractIdentityPolicy.remember`. Usually the *idenity* is stored in user cookies homehow for using by - :coroutine:`authorized_userid` and :coroutine:`permits`. + :func:`authorized_userid` and :func:`permits`. :param request: :class:`aiohttp.web.Request` object. @@ -31,18 +31,18 @@ Public API functions :param str identity: :class:`aiohttp.web.Request` object. - :param **kwargs: additional arguments passed to - :coroutinemethod:`AbstractIdentityPolicy.remember`. + :param kwargs: additional arguments passed to + :meth:`AbstractIdentityPolicy.remember`. - They are policy-specific and may be used, e.g. for - specifiying cookie lifetime. + They are policy-specific and may be used, e.g. for + specifiying cookie lifetime. -.. coroutine:: forget(request, response) +.. coroutinefunction:: forget(request, response) Forget previously remembered :term:`identity`. The action is performed by registered - :coroutinemethod:`AbstractIdentityPolicy.forget`. + :meth:`AbstractIdentityPolicy.forget`. :param request: :class:`aiohttp.web.Request` object. @@ -50,11 +50,11 @@ Public API functions descendants like :class:`aiohttp.web.Response`. -.. coroutine:: authorized_userid(request) +.. coroutinefunction:: authorized_userid(request) Retrieve :term:`userid`. - The user should be registered by :coroutine:`remember` before the call. + The user should be registered by :func:`remember` before the call. :param request: :class:`aiohttp.web.Request` object. @@ -62,7 +62,7 @@ Public API functions without signed in user. -.. coroutine:: permits(request, permission, context=None) +.. coroutinefunction:: permits(request, permission, context=None) Check user's permission. @@ -74,7 +74,7 @@ Public API functions Actually it's a wrapper around :meth:`AbstractAuthorizationPolicy.permits` coroutine. - The user should be registered by :coroutine:`remember` before the call. + The user should be registered by :func:`remember` before the call. :param request: :class:`aiohttp.web.Request` object. @@ -177,3 +177,32 @@ Identification policy :param response: :class:`aiohttp.web.StreamResponse` object or derivative. + + +Authorization policy +--------------------- + +.. class:: AbstractAuthorizationPolicy + + .. coroutinemethod:: authorized_userid(identity) + + Retrieve authorized user id. + + Abstract method, should be overriden by descendant. + + :param identity: an :term:`identity` used for authorization. + + :return: the :term:`userid` of the user identified by the + *identity* or ``None`` if no user exists related to the + identity. + + .. coroutinemethod:: permits(identity, permission, context=None) + + Check user permissions. + + Abstract method, should be overriden by descendant. + + :param identity: an :term:`identity` used for authorization. + + :param permission: requested permission. The type of parameter + is not fixed and depends on implementation.