From b3e608bac815a7d3fc639d78ec38edc5f97df859 Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Sat, 17 Mar 2012 09:27:13 -0700 Subject: Improve text of SQLAlchemy wiki tutorial. A mixture of typo fixes and wording improvements. --- docs/tutorials/wiki2/authorization.rst | 68 +++++++++++++++++----------------- 1 file changed, 35 insertions(+), 33 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index b76fd9a6c..338ec54be 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -7,8 +7,8 @@ Adding Authorization :app:`Pyramid` provides facilities for :term:`authentication` and :term:`authorization`. We'll make use of both features to provide security to our application. Our application currently allows anyone with access to -the server to view, edit, and add pages to our wiki. We'll change our -application to allow only people whom possess a specific username (`editor`) +the server to view, edit, and add pages to our wiki. We'll change that +to allow only people who possess a specific username (`editor`) to add and edit wiki pages but we'll continue allowing anyone with access to the server to view pages. @@ -41,13 +41,12 @@ Open ``models.py`` and add the following statements: :language: python We're going to start to use a custom :term:`root factory` within our -``__init__.py`` file. The objects generated by the root factory will be used -as the :term:`context` of each request to our application. We do this to -allow :app:`Pyramid` declarative security to work properly. The context -object generated by the root factory during a request will be decorated with -security declarations. When we begin to use a custom root factory to generate -our contexts, we can begin to make use of the declarative security features -of :app:`Pyramid`. +``__init__.py`` file. The objects generated by the root factory will +be used as the :term:`context` of each request to our application. +Those context objects will be decorated with security +declarations. When we use a custom root factory to generate +our contexts, we can begin to make use of the declarative security +features of :app:`Pyramid`. We'll modify our ``__init__.py``, passing in a :term:`root factory` to our :term:`Configurator` constructor. We'll point it at the new class we created @@ -65,7 +64,7 @@ to a context is interpreted specially by :app:`Pyramid` as an access control list during view callable execution. See :ref:`assigning_acls` for more information about what an :term:`ACL` represents. -.. note: Although we don't use the functionality here, the ``factory`` used +.. note:: Although we don't use the functionality here, the ``factory`` used to create route contexts may differ per-route as opposed to globally. See the ``factory`` argument to :meth:`pyramid.config.Configurator.add_route` for more info. @@ -147,9 +146,10 @@ We've given the ``editor`` user membership to the ``group:editors`` by mapping him to this group in the ``GROUPS`` data structure (``GROUPS = {'editor':['group:editors']}``). Since the ``groupfinder`` function consults the ``GROUPS`` data structure, this will mean that, as a -result of the ACL attached to the root returned by the root factory, -and the permission associated with the ``add_page`` and ``edit_page`` -views, the ``editor`` user should be able to add and edit pages. +result of the ACL attached to the :term:`context` object returned by +the root factory, and the permission associated with the ``add_page`` +and ``edit_page`` views, the ``editor`` user should be able to add and +edit pages. Adding Login and Logout Views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -176,20 +176,20 @@ The ``logout`` view callable will look something like this: :language: python The ``login`` view callable is decorated with two decorators, a -``@view_config`` decorators, which associates it with the ``login`` route, -the other a ``@forbidden_view_config`` decorator which turns it in to an -:term:`exception view` when Pyramid raises a -:class:`pyramid.httpexceptions.HTTPForbidden` exception. The one which -associates it with the ``login`` route makes it visible when we visit -``/login``. The other one makes it a :term:`forbidden view`. The forbidden -view is displayed whenever Pyramid or your application raises an -HTTPForbidden exception. In this case, we'll be relying on the forbidden -view to show the login form whenver someone attempts to execute an action -which they're not yet authorized to perform. +``@view_config`` decorator, which associates it with the ``login`` +route, and a ``@forbidden_view_config`` decorator which turns it in to +an :term:`exception view`. The one which associates it with the +``login`` route makes it visible when we visit ``/login``. The other +one makes it a :term:`forbidden view`. The forbidden view is +displayed whenever Pyramid or your application raises an +:class:`pyramid.httpexceptions.HTTPForbidden` exception. In this +case, we'll be relying on the forbidden view to show the login form +whenver someone attempts to execute an action which they're not yet +authorized to perform. The ``logout`` view callable is decorated with a ``@view_config`` decorator which associates it with the ``logout`` route. This makes it visible when we -visit ``/login``. +visit ``/logout``. We'll need to import some stuff to service the needs of these two functions: the ``pyramid.view.forbidden_view_config`` class, a number of values from the @@ -222,8 +222,8 @@ something like this to each view body: Return a logged_in flag to the renderer --------------------------------------- -We'll then change the return value of these views to pass the `resulting -`logged_in`` value to the template, e.g.: +We'll then change the return value of these views to pass the resulting +``logged_in`` value to the template, e.g.: .. code-block:: python :linenos: @@ -248,12 +248,14 @@ callables which these views reference cannot be invoked without the authenticated user possessing the ``edit`` permission with respect to the current :term:`context`. -Adding these ``permission`` arguments causes Pyramid to make the assertion -that only users who possess the effective ``edit`` permission at the time of -the request may invoke those two views. We've granted the ``group:editors`` -principal the ``edit`` permission at the root model via its ACL, so only the -a user whom is a member of the group named ``group:editors`` will able to -invoke the views associated with the ``add_page`` or ``edit_page`` routes. +Adding these ``permission`` arguments causes Pyramid to make the +assertion that only users who possess the effective ``edit`` +permission at the time of the request may invoke those two views. +We've granted the ``group:editors`` :term:`principal` the ``edit`` +permission in the :term:`root factory` via its ACL, so only a user who +is a member of the group named ``group:editors`` will be able to +invoke the views associated with the ``add_page`` or ``edit_page`` +routes. Adding the ``login.pt`` Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -322,7 +324,7 @@ each of the following URLs, check that the result is as expected: - ``http://localhost:6543/FrontPage`` invokes the ``view_page`` view of the FrontPage page object. -- ``http://localhost:6543/edit_page/FrontPage`` +- ``http://localhost:6543/FrontPage/edit_page`` invokes the edit view for the FrontPage object. It is executable by only the ``editor`` user. If a different user (or the anonymous user) invokes it, a login form will be displayed. Supplying the -- cgit v1.2.3