minor grammar, rewrap to 79 columns

1 files changed, 206 insertions, 232 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 75f4dc7c5..7cbea113c 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -6,64 +6,59 @@
 Security
 ========
 
-:app:`Pyramid` provides an optional, declarative, security system.
-Security in :app:`Pyramid` is separated into authentication and
-authorization. The two systems communicate via :term:`principal`
-identifiers. Authentication is merely the mechanism by which credentials
-provided in the :term:`request` are resolved to one or more
-:term:`principal` identifiers. These identifiers represent the users and
-groups that are in effect during the request. Authorization then determines
-access based on the :term:`principal` identifiers, the requested
+:app:`Pyramid` provides an optional, declarative, security system. Security in
+:app:`Pyramid` is separated into authentication and authorization. The two
+systems communicate via :term:`principal` identifiers. Authentication is merely
+the mechanism by which credentials provided in the :term:`request` are resolved
+to one or more :term:`principal` identifiers. These identifiers represent the
+users and groups that are in effect during the request. Authorization then
+determines access based on the :term:`principal` identifiers, the requested
 :term:`permission`, and a :term:`context`.
 
-The :app:`Pyramid` authorization system
-can prevent a :term:`view` from being invoked based on an
-:term:`authorization policy`. Before a view is invoked, the
-authorization system can use the credentials in the :term:`request`
-along with the :term:`context` resource to determine if access will be
-allowed.  Here's how it works at a high level:
+The :app:`Pyramid` authorization system can prevent a :term:`view` from being
+invoked based on an :term:`authorization policy`. Before a view is invoked, the
+authorization system can use the credentials in the :term:`request` along with
+the :term:`context` resource to determine if access will be allowed.  Here's
+how it works at a high level:
 
-- A user may or may not have previously visited the application and
-  supplied authentication credentials, including a :term:`userid`.  If
-  so, the application may have called
-  :func:`pyramid.security.remember` to remember these.
+- A user may or may not have previously visited the application and supplied
+  authentication credentials, including a :term:`userid`.  If so, the
+  application may have called :func:`pyramid.security.remember` to remember
+  these.
 
 - A :term:`request` is generated when a user visits the application.
 
 - Based on the request, a :term:`context` resource is located through
   :term:`resource location`.  A context is located differently depending on
-  whether the application uses :term:`traversal` or :term:`URL dispatch`, but
-  a context is ultimately found in either case.  See
-  the :ref:`urldispatch_chapter` chapter for more information.
+  whether the application uses :term:`traversal` or :term:`URL dispatch`, but a
+  context is ultimately found in either case.  See the
+  :ref:`urldispatch_chapter` chapter for more information.
 
-- A :term:`view callable` is located by :term:`view lookup` using the
-  context as well as other attributes of the request.
+- A :term:`view callable` is located by :term:`view lookup` using the context
+  as well as other attributes of the request.
 
-- If an :term:`authentication policy` is in effect, it is passed the
-  request. It will return some number of :term:`principal` identifiers.
-  To do this, the policy would need to determine the authenticated
-  :term:`userid` present in the request.
+- If an :term:`authentication policy` is in effect, it is passed the request.
+  It will return some number of :term:`principal` identifiers. To do this, the
+  policy would need to determine the authenticated :term:`userid` present in
+  the request.
 
 - If an :term:`authorization policy` is in effect and the :term:`view
-  configuration` associated with the view callable that was found has
-  a :term:`permission` associated with it, the authorization policy is
-  passed the :term:`context`, some number of :term:`principal`
-  identifiers returned by the authentication policy, and the
-  :term:`permission` associated with the view; it will allow or deny
-  access.
+  configuration` associated with the view callable that was found has a
+  :term:`permission` associated with it, the authorization policy is passed the
+  :term:`context`, some number of :term:`principal` identifiers returned by the
+  authentication policy, and the :term:`permission` associated with the view;
+  it will allow or deny access.
 
-- If the authorization policy allows access, the view callable is
-  invoked.
+- If the authorization policy allows access, the view callable is invoked.
 
-- If the authorization policy denies access, the view callable is not
-  invoked; instead the :term:`forbidden view` is invoked.
+- If the authorization policy denies access, the view callable is not invoked.
+  Instead the :term:`forbidden view` is invoked.
 
 Authorization is enabled by modifying your application to include an
-:term:`authentication policy` and :term:`authorization policy`.
-:app:`Pyramid` comes with a variety of implementations of these
-policies.  To provide maximal flexibility, :app:`Pyramid` also
-allows you to create custom authentication policies and authorization
-policies.
+:term:`authentication policy` and :term:`authorization policy`. :app:`Pyramid`
+comes with a variety of implementations of these policies.  To provide maximal
+flexibility, :app:`Pyramid` also allows you to create custom authentication
+policies and authorization policies.
 
 .. index::
    single: authorization policy
@@ -73,23 +68,22 @@ policies.
 Enabling an Authorization Policy
 --------------------------------
 
-:app:`Pyramid` does not enable any authorization policy by default.  All
-views are accessible by completely anonymous users.  In order to begin
-protecting views from execution based on security settings, you need
-to enable an authorization policy.
+:app:`Pyramid` does not enable any authorization policy by default.  All views
+are accessible by completely anonymous users.  In order to begin protecting
+views from execution based on security settings, you need to enable an
+authorization policy.
 
 Enabling an Authorization Policy Imperatively
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use the :meth:`~pyramid.config.Configurator.set_authorization_policy` method
-of the :class:`~pyramid.config.Configurator` to enable an authorization
-policy.
+Use the :meth:`~pyramid.config.Configurator.set_authorization_policy` method of
+the :class:`~pyramid.config.Configurator` to enable an authorization policy.
 
 You must also enable an :term:`authentication policy` in order to enable the
-authorization policy.  This is because authorization, in general, depends
-upon authentication.  Use the
-:meth:`~pyramid.config.Configurator.set_authentication_policy` method
-during application setup to specify the authentication policy.
+authorization policy.  This is because authorization, in general, depends upon
+authentication.  Use the
+:meth:`~pyramid.config.Configurator.set_authentication_policy` method during
+application setup to specify the authentication policy.
 
 For example:
 
@@ -105,28 +99,27 @@ For example:
    config.set_authentication_policy(authn_policy)
    config.set_authorization_policy(authz_policy)
 
-.. note:: The ``authentication_policy`` and ``authorization_policy``
-   arguments may also be passed to their respective methods mentioned above
-   as :term:`dotted Python name` values, each representing the dotted name
-   path to a suitable implementation global defined at Python module scope.
+.. note:: The ``authentication_policy`` and ``authorization_policy`` arguments
+   may also be passed to their respective methods mentioned above as
+   :term:`dotted Python name` values, each representing the dotted name path to
+   a suitable implementation global defined at Python module scope.
 
 The above configuration enables a policy which compares the value of an "auth
 ticket" cookie passed in the request's environment which contains a reference
-to a single :term:`userid` and matches that userid's
-:term:`principals <principal>` against the principals present in any
-:term:`ACL` found in the resource tree when attempting to call some
-:term:`view`.
+to a single :term:`userid`, and matches that userid's :term:`principals
+<principal>` against the principals present in any :term:`ACL` found in the
+resource tree when attempting to call some :term:`view`.
 
 While it is possible to mix and match different authentication and
-authorization policies, it is an error to configure a Pyramid application
-with an authentication policy but without the authorization policy or vice
-versa.  If you do this, you'll receive an error at application startup time.
+authorization policies, it is an error to configure a Pyramid application with
+an authentication policy but without the authorization policy or vice versa. If
+you do this, you'll receive an error at application startup time.
 
 .. seealso::
 
-    See also the :mod:`pyramid.authorization` and
-    :mod:`pyramid.authentication` modules for alternate implementations of
-    authorization and authentication policies.
+    See also the :mod:`pyramid.authorization` and :mod:`pyramid.authentication`
+    modules for alternative implementations of authorization and authentication
+    policies.
 
 .. index::
    single: permissions
@@ -139,14 +132,13 @@ Protecting Views with Permissions
 
 To protect a :term:`view callable` from invocation based on a user's security
 settings when a particular type of resource becomes the :term:`context`, you
-must pass a :term:`permission` to :term:`view configuration`.  Permissions
-are usually just strings, and they have no required composition: you can name
+must pass a :term:`permission` to :term:`view configuration`.  Permissions are
+usually just strings, and they have no required composition: you can name
 permissions whatever you like.
 
 For example, the following view declaration protects the view named
 ``add_entry.html`` when the context resource is of type ``Blog`` with the
-``add`` permission using the :meth:`pyramid.config.Configurator.add_view`
-API:
+``add`` permission using the :meth:`pyramid.config.Configurator.add_view` API:
 
 .. code-block:: python
    :linenos:
@@ -158,8 +150,8 @@ API:
                    context='mypackage.resources.Blog',
                    permission='add')
 
-The equivalent view registration including the ``add`` permission name
-may be performed via the ``@view_config`` decorator:
+The equivalent view registration including the ``add`` permission name may be
+performed via the ``@view_config`` decorator:
 
 .. code-block:: python
    :linenos:
@@ -173,11 +165,11 @@ may be performed via the ``@view_config`` decorator:
        pass
 
 As a result of any of these various view configuration statements, if an
-authorization policy is in place when the view callable is found during
-normal application operations, the requesting user will need to possess the
-``add`` permission against the :term:`context` resource in order to be able
-to invoke the ``blog_entry_add_view`` view.  If he does not, the
-:term:`Forbidden view` will be invoked.
+authorization policy is in place when the view callable is found during normal
+application operations, the requesting user will need to possess the ``add``
+permission against the :term:`context` resource in order to be able to invoke
+the ``blog_entry_add_view`` view.  If they do not, the :term:`Forbidden view`
+will be invoked.
 
 .. index::
    pair: permission; default
@@ -187,18 +179,17 @@ to invoke the ``blog_entry_add_view`` view.  If he does not, the
 Setting a Default Permission
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If a permission is not supplied to a view configuration, the registered
-view will always be executable by entirely anonymous users: any
-authorization policy in effect is ignored.
+If a permission is not supplied to a view configuration, the registered view
+will always be executable by entirely anonymous users: any authorization policy
+in effect is ignored.
 
-In support of making it easier to configure applications which are
-"secure by default", :app:`Pyramid` allows you to configure a
-*default* permission.  If supplied, the default permission is used as
-the permission string to all view registrations which don't otherwise
-name a ``permission`` argument.
+In support of making it easier to configure applications which are "secure by
+default", :app:`Pyramid` allows you to configure a *default* permission.  If
+supplied, the default permission is used as the permission string to all view
+registrations which don't otherwise name a ``permission`` argument.
 
-The :meth:`pyramid.config.Configurator.set_default_permission` method
-supports configuring a default permission for an application.
+The :meth:`pyramid.config.Configurator.set_default_permission` method supports
+configuring a default permission for an application.
 
 When a default permission is registered:
 
@@ -207,8 +198,8 @@ When a default permission is registered:
   view-configuration-named permission is used.
 
 - If a view configuration names the permission
-  :data:`pyramid.security.NO_PERMISSION_REQUIRED`, the default permission
-  is ignored, and the view is registered *without* a permission (making it
+  :data:`pyramid.security.NO_PERMISSION_REQUIRED`, the default permission is
+  ignored, and the view is registered *without* a permission (making it
   available to all callers regardless of their credentials).
 
 .. warning::
@@ -226,19 +217,18 @@ When a default permission is registered:
 
 .. _assigning_acls:
 
-Assigning ACLs to your Resource Objects
+Assigning ACLs to Your Resource Objects
 ---------------------------------------
 
-When the default :app:`Pyramid` :term:`authorization policy` determines
-whether a user possesses a particular permission with respect to a resource,
-it examines the :term:`ACL` associated with the resource.  An ACL is
-associated with a resource by adding an ``__acl__`` attribute to the resource
-object.  This attribute can be defined on the resource *instance* if you need
+When the default :app:`Pyramid` :term:`authorization policy` determines whether
+a user possesses a particular permission with respect to a resource, it
+examines the :term:`ACL` associated with the resource.  An ACL is associated
+with a resource by adding an ``__acl__`` attribute to the resource object.
+This attribute can be defined on the resource *instance* if you need
 instance-level security, or it can be defined on the resource *class* if you
 just need type-level security.
 
-For example, an ACL might be attached to the resource for a blog via its
-class:
+For example, an ACL might be attached to the resource for a blog via its class:
 
 .. code-block:: python
    :linenos:
@@ -273,11 +263,11 @@ Or, if your resources are persistent, an ACL might be specified via the
            (Allow, 'group:editors', 'edit'),
            ]
 
-Whether an ACL is attached to a resource's class or an instance of the
-resource itself, the effect is the same.  It is useful to decorate individual
-resource instances with an ACL (as opposed to just decorating their class) in
-applications such as "CMS" systems where fine-grained access is required on
-an object-by-object basis.
+Whether an ACL is attached to a resource's class or an instance of the resource
+itself, the effect is the same.  It is useful to decorate individual resource
+instances with an ACL (as opposed to just decorating their class) in
+applications such as content management systems where fine-grained access is
+required on an object-by-object basis.
 
 Dynamic ACLs are also possible by turning the ACL into a callable on the
 resource. This may allow the ACL to dynamically generate rules based on
@@ -321,30 +311,27 @@ Here's an example ACL:
            (Allow, 'group:editors', 'edit'),
            ]
 
-The example ACL indicates that the
-:data:`pyramid.security.Everyone` principal -- a special
-system-defined principal indicating, literally, everyone -- is allowed
-to view the blog, the ``group:editors`` principal is allowed to add to
-and edit the blog.
+The example ACL indicates that the :data:`pyramid.security.Everyone`
+principal—a special system-defined principal indicating, literally, everyone—is
+allowed to view the blog, and the ``group:editors`` principal is allowed to add
+to and edit the blog.
 
-Each element of an ACL is an :term:`ACE` or access control entry.
-For example, in the above code block, there are three ACEs: ``(Allow,
-Everyone, 'view')``, ``(Allow, 'group:editors', 'add')``, and
-``(Allow, 'group:editors', 'edit')``.
+Each element of an ACL is an :term:`ACE`, or access control entry. For example,
+in the above code block, there are three ACEs: ``(Allow, Everyone, 'view')``,
+``(Allow, 'group:editors', 'add')``, and ``(Allow, 'group:editors', 'edit')``.
 
-The first element of any ACE is either
-:data:`pyramid.security.Allow`, or
-:data:`pyramid.security.Deny`, representing the action to take when
-the ACE matches.  The second element is a :term:`principal`.  The
-third argument is a permission or sequence of permission names.
+The first element of any ACE is either :data:`pyramid.security.Allow`, or
+:data:`pyramid.security.Deny`, representing the action to take when the ACE
+matches.  The second element is a :term:`principal`.  The third argument is a
+permission or sequence of permission names.
 
 A principal is usually a user id, however it also may be a group id if your
 authentication system provides group information and the effective
 :term:`authentication policy` policy is written to respect group information.
 See :ref:`extending_default_authentication_policies`.
 
-Each ACE in an ACL is processed by an authorization policy *in the
-order dictated by the ACL*.  So if you have an ACL like this:
+Each ACE in an ACL is processed by an authorization policy *in the order
+dictated by the ACL*.  So if you have an ACL like this:
 
 .. code-block:: python
    :linenos:
@@ -358,10 +345,9 @@ order dictated by the ACL*.  So if you have an ACL like this:
        (Deny, Everyone, 'view'),
        ]
 
-The default authorization policy will *allow* everyone the view
-permission, even though later in the ACL you have an ACE that denies
-everyone the view permission.  On the other hand, if you have an ACL
-like this:
+The default authorization policy will *allow* everyone the view permission,
+even though later in the ACL you have an ACE that denies everyone the view
+permission.  On the other hand, if you have an ACL like this:
 
 .. code-block:: python
    :linenos:
@@ -375,14 +361,13 @@ like this:
        (Allow, Everyone, 'view'),
        ]
 
-The authorization policy will deny everyone the view permission, even
-though later in the ACL is an ACE that allows everyone.
+The authorization policy will deny everyone the view permission, even though
+later in the ACL, there is an ACE that allows everyone.
 
-The third argument in an ACE can also be a sequence of permission
-names instead of a single permission name.  So instead of creating
-multiple ACEs representing a number of different permission grants to
-a single ``group:editors`` group, we can collapse this into a single
-ACE, as below.
+The third argument in an ACE can also be a sequence of permission names instead
+of a single permission name.  So instead of creating multiple ACEs representing
+a number of different permission grants to a single ``group:editors`` group, we
+can collapse this into a single ACE, as below.
 
 .. code-block:: python
    :linenos:
@@ -403,23 +388,21 @@ ACE, as below.
 Special Principal Names
 -----------------------
 
-Special principal names exist in the :mod:`pyramid.security`
-module.  They can be imported for use in your own code to populate
-ACLs, e.g. :data:`pyramid.security.Everyone`.
+Special principal names exist in the :mod:`pyramid.security` module.  They can
+be imported for use in your own code to populate ACLs, e.g.,
+:data:`pyramid.security.Everyone`.
 
 :data:`pyramid.security.Everyone`
 
-  Literally, everyone, no matter what.  This object is actually a
-  string "under the hood" (``system.Everyone``).  Every user "is" the
-  principal named Everyone during every request, even if a security
-  policy is not in use.
+  Literally, everyone, no matter what.  This object is actually a string under
+  the hood (``system.Everyone``).  Every user *is* the principal named
+  "Everyone" during every request, even if a security policy is not in use.
 
 :data:`pyramid.security.Authenticated`
 
-  Any user with credentials as determined by the current security
-  policy.  You might think of it as any user that is "logged in".
-  This object is actually a string "under the hood"
-  (``system.Authenticated``).
+  Any user with credentials as determined by the current security policy.  You
+  might think of it as any user that is "logged in".  This object is actually a
+  string under the hood (``system.Authenticated``).
 
 .. index::
    single: permission names
@@ -428,19 +411,19 @@ ACLs, e.g. :data:`pyramid.security.Everyone`.
 Special Permissions
 -------------------
 
-Special permission names exist in the :mod:`pyramid.security`
-module.  These can be imported for use in ACLs.
+Special permission names exist in the :mod:`pyramid.security` module.  These
+can be imported for use in ACLs.
 
 .. _all_permissions:
 
 :data:`pyramid.security.ALL_PERMISSIONS`
 
-  An object representing, literally, *all* permissions.  Useful in an
-  ACL like so: ``(Allow, 'fred', ALL_PERMISSIONS)``.  The
-  ``ALL_PERMISSIONS`` object is actually a stand-in object that has a
-  ``__contains__`` method that always returns ``True``, which, for all
-  known authorization policies, has the effect of indicating that a
-  given principal "has" any permission asked for by the system.
+  An object representing, literally, *all* permissions.  Useful in an ACL like
+  so: ``(Allow, 'fred', ALL_PERMISSIONS)``.  The ``ALL_PERMISSIONS`` object is
+  actually a stand-in object that has a ``__contains__`` method that always
+  returns ``True``, which, for all known authorization policies, has the effect
+  of indicating that a given principal has any permission asked for by the
+  system.
 
 .. index::
    single: special ACE
@@ -451,11 +434,11 @@ Special ACEs
 
 A convenience :term:`ACE` is defined representing a deny to everyone of all
 permissions in :data:`pyramid.security.DENY_ALL`.  This ACE is often used as
-the *last* ACE of an ACL to explicitly cause inheriting authorization
-policies to "stop looking up the traversal tree" (effectively breaking any
-inheritance).  For example, an ACL which allows *only* ``fred`` the view
-permission for a particular resource despite what inherited ACLs may say when
-the default authorization policy is in effect might look like so:
+the *last* ACE of an ACL to explicitly cause inheriting authorization policies
+to "stop looking up the traversal tree" (effectively breaking any inheritance).
+For example, an ACL which allows *only* ``fred`` the view permission for a
+particular resource, despite what inherited ACLs may say when the default
+authorization policy is in effect, might look like so:
 
 .. code-block:: python
    :linenos:
@@ -465,8 +448,8 @@ the default authorization policy is in effect might look like so:
 
    __acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ]
 
-"Under the hood", the :data:`pyramid.security.DENY_ALL` ACE equals
-the following:
+Under the hood, the :data:`pyramid.security.DENY_ALL` ACE equals the
+following:
 
 .. code-block:: python
    :linenos:
@@ -483,14 +466,14 @@ ACL Inheritance and Location-Awareness
 
 While the default :term:`authorization policy` is in place, if a resource
 object does not have an ACL when it is the context, its *parent* is consulted
-for an ACL.  If that object does not have an ACL, *its* parent is consulted
-for an ACL, ad infinitum, until we've reached the root and there are no more
+for an ACL.  If that object does not have an ACL, *its* parent is consulted for
+an ACL, ad infinitum, until we've reached the root and there are no more
 parents left.
 
 In order to allow the security machinery to perform ACL inheritance, resource
 objects must provide *location-awareness*.  Providing *location-awareness*
-means two things: the root object in the resource tree must have a
-``__name__`` attribute and a ``__parent__`` attribute.
+means two things: the root object in the resource tree must have a ``__name__``
+attribute and a ``__parent__`` attribute.
 
 .. code-block:: python
    :linenos:
@@ -499,10 +482,10 @@ means two things: the root object in the resource tree must have a
        __name__ = ''
        __parent__ = None
 
-An object with a ``__parent__`` attribute and a ``__name__`` attribute
-is said to be *location-aware*.  Location-aware objects define an
-``__parent__`` attribute which points at their parent object.  The
-root object's ``__parent__`` is ``None``.
+An object with a ``__parent__`` attribute and a ``__name__`` attribute is said
+to be *location-aware*.  Location-aware objects define a ``__parent__``
+attribute which points at their parent object.  The root object's
+``__parent__`` is ``None``.
 
 .. seealso::
 
@@ -519,12 +502,11 @@ root object's ``__parent__`` is ``None``.
 Changing the Forbidden View
 ---------------------------
 
-When :app:`Pyramid` denies a view invocation due to an
-authorization denial, the special ``forbidden`` view is invoked.  "Out
-of the box", this forbidden view is very plain.  See
-:ref:`changing_the_forbidden_view` within :ref:`hooks_chapter` for
-instructions on how to create a custom forbidden view and arrange for
-it to be called when view authorization is denied.
+When :app:`Pyramid` denies a view invocation due to an authorization denial,
+the special ``forbidden`` view is invoked.  Out of the box, this forbidden view
+is very plain.  See :ref:`changing_the_forbidden_view` within
+:ref:`hooks_chapter` for instructions on how to create a custom forbidden view
+and arrange for it to be called when view authorization is denied.
 
 .. index::
    single: debugging authorization failures
@@ -534,8 +516,8 @@ it to be called when view authorization is denied.
 Debugging View Authorization Failures
 -------------------------------------
 
-If your application in your judgment is allowing or denying view
-access inappropriately, start your application under a shell using the
+If your application in your judgment is allowing or denying view access
+inappropriately, start your application under a shell using the
 ``PYRAMID_DEBUG_AUTHORIZATION`` environment variable set to ``1``.  For
 example:
 
@@ -543,14 +525,13 @@ example:
 
   $ PYRAMID_DEBUG_AUTHORIZATION=1 $VENV/bin/pserve myproject.ini
 
-When any authorization takes place during a top-level view rendering,
-a message will be logged to the console (to stderr) about what ACE in
-which ACL permitted or denied the authorization based on
-authentication information.
+When any authorization takes place during a top-level view rendering, a message
+will be logged to the console (to stderr) about what ACE in which ACL permitted
+or denied the authorization based on authentication information.
 
-This behavior can also be turned on in the application ``.ini`` file
-by setting the ``pyramid.debug_authorization`` key to ``true`` within the
-application's configuration section, e.g.:
+This behavior can also be turned on in the application ``.ini`` file by setting
+the ``pyramid.debug_authorization`` key to ``true`` within the application's
+configuration section, e.g.:
 
 .. code-block:: ini
   :linenos:
@@ -559,26 +540,24 @@ application's configuration section, e.g.:
   use = egg:MyProject
   pyramid.debug_authorization = true
 
-With this debug flag turned on, the response sent to the browser will
-also contain security debugging information in its body.
+With this debug flag turned on, the response sent to the browser will also
+contain security debugging information in its body.
 
 Debugging Imperative Authorization Failures
 -------------------------------------------
 
 The :meth:`pyramid.request.Request.has_permission` API is used to check
-security within view functions imperatively.  It returns instances of
-objects that are effectively booleans.  But these objects are not raw
-``True`` or ``False`` objects, and have information attached to them
-about why the permission was allowed or denied.  The object will be
-one of :data:`pyramid.security.ACLAllowed`,
-:data:`pyramid.security.ACLDenied`,
-:data:`pyramid.security.Allowed`, or
-:data:`pyramid.security.Denied`, as documented in
-:ref:`security_module`.  At the very minimum these objects will have a
-``msg`` attribute, which is a string indicating why the permission was
-denied or allowed.  Introspecting this information in the debugger or
-via print statements when a call to
-:meth:`~pyramid.request.Request.has_permission` fails is often useful.
+security within view functions imperatively.  It returns instances of objects
+that are effectively booleans.  But these objects are not raw ``True`` or
+``False`` objects, and have information attached to them about why the
+permission was allowed or denied.  The object will be one of
+:data:`pyramid.security.ACLAllowed`, :data:`pyramid.security.ACLDenied`,
+:data:`pyramid.security.Allowed`, or :data:`pyramid.security.Denied`, as
+documented in :ref:`security_module`.  At the very minimum, these objects will
+have a ``msg`` attribute, which is a string indicating why the permission was
+denied or allowed.  Introspecting this information in the debugger or via print
+statements when a call to :meth:`~pyramid.request.Request.has_permission` fails
+is often useful.
 
 .. index::
    single: authentication policy (extending)
@@ -588,27 +567,26 @@ via print statements when a call to
 Extending Default Authentication Policies
 -----------------------------------------
 
-Pyramid ships with some builtin authentication policies for use in your
-applications. See :mod:`pyramid.authentication` for the available
-policies. They differ on their mechanisms for tracking authentication
-credentials between requests, however they all interface with your
-application in mostly the same way.
+Pyramid ships with some built in authentication policies for use in your
+applications. See :mod:`pyramid.authentication` for the available policies.
+They differ on their mechanisms for tracking authentication credentials between
+requests, however they all interface with your application in mostly the same
+way.
 
-Above you learned about :ref:`assigning_acls`. Each :term:`principal` used
-in the :term:`ACL` is matched against the list returned from
+Above you learned about :ref:`assigning_acls`. Each :term:`principal` used in
+the :term:`ACL` is matched against the list returned from
 :meth:`pyramid.interfaces.IAuthenticationPolicy.effective_principals`.
 Similarly, :meth:`pyramid.request.Request.authenticated_userid` maps to
 :meth:`pyramid.interfaces.IAuthenticationPolicy.authenticated_userid`.
 
 You may control these values by subclassing the default authentication
 policies. For example, below we subclass the
-:class:`pyramid.authentication.AuthTktAuthenticationPolicy` and define
-extra functionality to query our database before confirming that the
-:term:`userid` is valid in order to avoid blindly trusting the value in the
-cookie (what if the cookie is still valid but the user has deleted their
-account?). We then use that :term:`userid` to augment the
-``effective_principals`` with information about groups and other state for
-that user.
+:class:`pyramid.authentication.AuthTktAuthenticationPolicy` and define extra
+functionality to query our database before confirming that the :term:`userid`
+is valid in order to avoid blindly trusting the value in the cookie (what if
+the cookie is still valid, but the user has deleted their account?).  We then
+use that :term:`userid` to augment the ``effective_principals`` with
+information about groups and other state for that user.
 
 .. code-block:: python
    :linenos:
@@ -630,8 +608,8 @@ that user.
            return principals
 
 In most instances ``authenticated_userid`` and ``effective_principals`` are
-application-specific whereas ``unauthenticated_userid``, ``remember`` and
-``forget`` are generic and focused on transport/serialization of data
+application-specific, whereas ``unauthenticated_userid``, ``remember``, and
+``forget`` are generic and focused on transport and serialization of data
 between consecutive requests.
 
 .. index::
@@ -642,12 +620,11 @@ between consecutive requests.
 Creating Your Own Authentication Policy
 ---------------------------------------
 
-:app:`Pyramid` ships with a number of useful out-of-the-box
-security policies (see :mod:`pyramid.authentication`).  However,
-creating your own authentication policy is often necessary when you
-want to control the "horizontal and vertical" of how your users
-authenticate.  Doing so is a matter of creating an instance of something
-that implements the following interface:
+:app:`Pyramid` ships with a number of useful out-of-the-box security policies
+(see :mod:`pyramid.authentication`).  However, creating your own authentication
+policy is often necessary when you want to control the "horizontal and
+vertical" of how your users authenticate.  Doing so is a matter of creating an
+instance of something that implements the following interface:
 
 .. code-block:: python
    :linenos:
@@ -717,21 +694,19 @@ Creating Your Own Authorization Policy
 --------------------------------------
 
 An authorization policy is a policy that allows or denies access after a user
-has been authenticated.  Most :app:`Pyramid` applications will use the
-default :class:`pyramid.authorization.ACLAuthorizationPolicy`.
-
-However, in some cases, it's useful to be able to use a different
-authorization policy than the default
-:class:`~pyramid.authorization.ACLAuthorizationPolicy`.  For example, it
-might be desirable to construct an alternate authorization policy which
-allows the application to use an authorization mechanism that does not
-involve :term:`ACL` objects.
-
-:app:`Pyramid` ships with only a single default authorization
-policy, so you'll need to create your own if you'd like to use a
-different one.  Creating and using your own authorization policy is a
-matter of creating an instance of an object that implements the
-following interface:
+has been authenticated.  Most :app:`Pyramid` applications will use the default
+:class:`pyramid.authorization.ACLAuthorizationPolicy`.
+
+However, in some cases, it's useful to be able to use a different authorization
+policy than the default :class:`~pyramid.authorization.ACLAuthorizationPolicy`.
+For example, it might be desirable to construct an alternate authorization
+policy which allows the application to use an authorization mechanism that does
+not involve :term:`ACL` objects.
+
+:app:`Pyramid` ships with only a single default authorization policy, so you'll
+need to create your own if you'd like to use a different one.  Creating and
+using your own authorization policy is a matter of creating an instance of an
+object that implements the following interface:
 
 .. code-block:: python
     :linenos:
@@ -782,4 +757,3 @@ which would allow the attacker to control the content of the payload.  Re-using
 a secret across two different subsystems might drop the security of signing to
 zero. Keys should not be re-used across different contexts where an attacker
 has the possibility of providing a chosen plaintext.
-