Security docs.

2 files changed, 44 insertions, 0 deletions

diff --git a/repoze/bfg/router.py b/repoze/bfg/router.py
index becf3e3e4..e9e0f175a 100644
--- a/repoze/bfg/router.py
+++ b/repoze/bfg/router.py
@@ -17,6 +17,8 @@ from repoze.bfg.interfaces import IRequest
 from repoze.bfg.registry import registry_manager
 
 class Router:
+    """ WSGI application which routes requests to 'view' code based on
+    a view registry"""
     def __init__(self, root_policy, registry):
         self.root_policy = root_policy
         self.registry = registry
@@ -51,6 +53,12 @@ class Router:
         return app(environ, start_response)
 
 def make_app(root_policy, package=None, filename='configure.zcml'):
+    """ Create a view registry based on the application's ZCML.  and
+    return a Router object, representing a repoze.bfg WSGI
+    application.  'root_policy' must be a callable that accepts an
+    environ and returns a graph root object.  'package' is the
+    dotted-Python-path packagename of the application, 'filename' is
+    the ZCML file that should be parsed to create the view registry."""
     from repoze.bfg.registry import makeRegistry
     registry = makeRegistry(filename, package)
     return Router(root_policy, registry)
diff --git a/repoze/bfg/security.py b/repoze/bfg/security.py
index 21a0a3f2a..6ee2d7d95 100644
--- a/repoze/bfg/security.py
+++ b/repoze/bfg/security.py
@@ -14,6 +14,13 @@ Allow = 'Allow'
 Deny = 'Deny'
 
 def has_permission(permission, context, request):
+    """ Provided a permission (a string or unicode object), a context
+    (a model instance) and a request object, return ``Allowed`` if the
+    permission is granted in this context to the user implied by the
+    request. Return ``Denied`` if this permission is not granted in
+    this context to this user.  This delegates to the current security
+    policy.  Return True unconditionally if no security policy has
+    been configured in this application."""
     policy = queryUtility(ISecurityPolicy)
     if policy is None:
         return True
@@ -55,6 +62,23 @@ class ACLAuthorizer(object):
         
 
 class RemoteUserACLSecurityPolicy(object):
+    """ A security policy which:
+
+    - examines the request.environ for the REMOTE_USER variable and
+      uses any non-false value as a principal id for this request.
+
+    - uses an ACL-based authorization model which attempts to find an
+      ACL on the context, and which returns ``Allowed`` from its
+      'permits' method if the ACL found grants access to the current
+      principal.  It returns ``Denied`` if permission was not granted
+      (either explicitly via a deny or implicitly by not finding a
+      matching ACE action).  An ACL is an ordered sequence of ACE
+      tuples, e.g.  ``[(Allow, Everyone, 'read'), (Deny, 'george',
+      'write')]``.  ACLs stored on model instance objects as their
+      __acl__ attribute will be used by the security machinery to
+      grant or deny access.
+
+    """
     implements(ISecurityPolicy)
     authorizer_factory = ACLAuthorizer
     
@@ -62,6 +86,8 @@ class RemoteUserACLSecurityPolicy(object):
         self.logger = logger
 
     def permits(self, context, request, permission):
+        """ Return ``Allowed`` if the policy permits access,
+        ``Denied`` if not."""
         userid = request.environ.get('REMOTE_USER', None)
         effective_principals = [Everyone]
 
@@ -94,6 +120,11 @@ class PermitsResult:
         return msg
 
 class Denied(PermitsResult):
+    """ The value type returned by an ACL denial.  It evaluates equal
+    to all boolean false types.  It also has attributes which indicate
+    which acl, ace, permission, principals, and context were involved
+    in the request.  Its __str__ method prints a summary of these
+    attributes for debugging purposes. """
     def __nonzero__(self):
         return False
 
@@ -102,6 +133,11 @@ class Denied(PermitsResult):
             return True
 
 class Allowed(PermitsResult):
+    """ The value type returned by an ACL denial.  It evaluates equal
+    to all boolean true types.  It also has attributes which indicate
+    which acl, ace, permission, principals, and context were involved
+    in the request.  Its __str__ method prints a summary of these
+    attributes for debugging purposes. """
     def __nonzero__(self):
         return True