diff options
| -rw-r--r-- | CHANGES.txt | 2 | ||||
| -rw-r--r-- | docs/narr/security.rst | 20 | ||||
| -rw-r--r-- | pyramid/interfaces.py | 13 |
3 files changed, 26 insertions, 9 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 33949f29e..1e68eafea 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -48,6 +48,8 @@ Documentation - Move content of "Forms" chapter back to "Views" chapter; I can't think of a better place to put it. +- Slightly improved interface docs for ``IAuthorizationPolicy``. + Deprecations ------------- diff --git a/docs/narr/security.rst b/docs/narr/security.rst index e395b15f1..783810734 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -566,10 +566,12 @@ that implements the following interface: authenticated userid can be found. """ def effective_principals(self, request): + """ Return a sequence representing the effective principals including the userid and any groups belonged to by the current - user, including 'system' groups such as Everyone and - Authenticated. """ + user, including 'system' groups such as + ``pyramid.security.Everyone`` and + ``pyramid.security.Authenticated``. """ def remember(self, request, principal, **kw): """ Return a set of headers suitable for 'remembering' the @@ -618,12 +620,18 @@ following interface: class IAuthorizationPolicy(object): """ An object representing a Pyramid authorization policy. """ def permits(self, context, principals, permission): - """ Return True if any of the principals is allowed the - permission in the current context, else return False """ + """ Return ``True`` if any of the ``principals`` is allowed the + ``permission`` in the current ``context``, else return ``False`` + """ def principals_allowed_by_permission(self, context, permission): - """ Return a set of principal identifiers allowed by the - permission """ + """ Return a set of principal identifiers allowed by the + ``permission`` in ``context``. This behavior is optional; if you + choose to not implement it you should define this method as + something which raises a ``NotImplementedError``. This method + will only be called when the + ``pyramid.security.principals_allowed_by_permission`` API is + used.""" After you do so, you can pass an instance of such a class into the :class:`pyramid.config.Configurator` class at configuration diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py index a9b686105..62dd0b5a6 100644 --- a/pyramid/interfaces.py +++ b/pyramid/interfaces.py @@ -188,11 +188,18 @@ class IAuthenticationPolicy(Interface): class IAuthorizationPolicy(Interface): """ An object representing a Pyramid authorization policy. """ def permits(context, principals, permission): - """ Return True if any of the principals is allowed the - permission in the current context, else return False """ + """ Return ``True`` if any of the ``principals`` is allowed the + ``permission`` in the current ``context``, else return ``False`` + """ def principals_allowed_by_permission(context, permission): - """ Return a set of principal identifiers allowed by the permission """ + """ Return a set of principal identifiers allowed by the + ``permission`` in ``context``. This behavior is optional; if you + choose to not implement it you should define this method as + something which raises a ``NotImplementedError``. This method + will only be called when the + ``pyramid.security.principals_allowed_by_permission`` API is + used.""" class IStaticURLInfo(Interface): """ A policy for generating URLs to static assets """ |