Permalink
Browse files

Merge remote-tracking branch 'upstream/master' into shentonfreude/bug…

….sqltut-test-populate-settings
  • Loading branch information...
2 parents 1e5ba8a + 3ea3ec0 commit 3484f0c0fdbfc05ff9a289255c294379348beba5 Chris Shenton committed Mar 13, 2012
@@ -88,7 +88,8 @@ View the Application in a Browser
We can't. At this point, our system is in a "non-runnable" state; we'll need
to change view-related files in the next chapter to be able to start the
-application successfully. If you try to start the application, you'll wind
+application successfully. If you try to start the application (See
+:ref:`wiki-start-the-application`), you'll wind
up with a Python traceback on your console that ends with this exception:
.. code-block:: text
@@ -301,8 +301,8 @@ subdirectories) and are just referred to by URL.
Viewing the Application in a Browser
====================================
-We can finally examine our application in a
-browser. The views we'll try are as follows:
+We can finally examine our application in a browser (See
+:ref:`wiki-start-the-application`). The views we'll try are as follows:
- Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki``
view. This always redirects to the ``view_page`` view of the ``FrontPage``
@@ -0,0 +1,134 @@
+==========
+Design
+==========
+
+Following is a quick overview of our wiki application, to help
+us understand the changes that we will be doing next in our
+default files generated by the paster scafffold.
+
+Overall
+-------
+
+We choose to use ``reStructuredText`` markup in the wiki text.
+Translation from reStructuredText to HTML is provided by the
+widely used docutils Python module. We will add this module
+in the dependency list on the project ``setup.py`` file.
+
+Models
+------
+
+The root resource, named *Wiki*, will be a mapping of wiki page
+names to page resources. The page resources will be instances
+of a *Page* class and they store the text content.
+
+URLs like ``/PageName`` will be traversed using Wiki[
+*PageName* ] => page, and the context that results is the page
+resource of an existing page.
+
+To add a page to the wiki, a new instance of the page resource
+is created and its name and reference are added to the Wiki
+mapping.
+
+A page named *FrontPage* containing the text *This is the front
+page*, will be created when the storage is initialized, and will
+be used as the wiki home page.
+
+Views
+-----
+
+There will be four views to handle the normal operations of
+viewing, editing and adding wiki pages. Two additional views
+will handle the login and logout tasks related to security.
+
+Security
+--------
+
+- USERS, a dictionary mapping users names to their
+ corresponding passwords.
+- GROUPS, a dictionary mapping user names to a
+ list of groups they belong to.
+- *groupfinder*, an *authorization callback* that looks up
+ USERS and GROUPS. It will be provided in a new
+ *security.py* file.
+- An :term:`ACL` is attached to the root resource. Each
+ row below details an :term:`ACE`:
+
+ +----------+----------------+----------------+
+ | Action | Principal | Permission |
+ +==========+================+================+
+ | Allow | Everyone | View |
+ +----------+----------------+----------------+
+ | Allow | group:editors | Edit |
+ +----------+----------------+----------------+
+
+- Permission declarations for the views.
+
+
+Summary
+-------
+
+The URL, context, actions, template and permission associated to each view are
+listed in the following table:
+
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| URL | View | Context | Action | Template | Permission |
+| | | | | | |
++======================+=============+=================+=======================+============+============+
+| / | view_wiki | Wiki | Redirect to | | |
+| | | | /FrontPage | | |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName | view_page | Page | Display existing | view.pt | view |
+| | [1]_ | | page [2]_ | | |
+| | | | | | |
+| | | | | | |
+| | | | | | |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName/edit_page | edit_page | Page | Display edit form | edit.pt | edit |
+| | | | with existing | | |
+| | | | content. | | |
+| | | | | | |
+| | | | If the form was | | |
+| | | | submitted, redirect | | |
+| | | | to /PageName | | |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /add_page/PageName | add_page | Wiki | Create the page | edit.pt | edit |
+| | | | *PageName* in | | |
+| | | | storage, display | | |
+| | | | the edit form | | |
+| | | | without content. | | |
+| | | | | | |
+| | | | If the form was | | |
+| | | | submitted, | | |
+| | | | redirect to | | |
+| | | | /PageName | | |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /login | login | Wiki, | Display login form. | login.pt | |
+| | | Forbidden [3]_ | | | |
+| | | | If the form was | | |
+| | | | submitted, | | |
+| | | | authenticate. | | |
+| | | | | | |
+| | | | - If authentication | | |
+| | | | successful, | | |
+| | | | redirect to the | | |
+| | | | page that we | | |
+| | | | came from. | | |
+| | | | | | |
+| | | | - If authentication | | |
+| | | | fails, display | | |
+| | | | login form with | | |
+| | | | "login failed" | | |
+| | | | message. | | |
+| | | | | | |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /logout | logout | Wiki | Redirect to | | |
+| | | | /FrontPage | | |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+
+.. [1] This is the default view for a Page context
+ when there is no view name.
+.. [2] Pyramid will return a default 404 Not Found page
+ if the page *PageName* does not exist yet.
+.. [3] pyramid.exceptions.Forbidden is reached when a
+ user tries to invoke a view that is
+ not authorized by the authorization policy.
@@ -18,6 +18,7 @@ tutorial can be browsed at
:maxdepth: 2
background
+ design
installation
basiclayout
definingmodels
@@ -228,6 +228,8 @@ Looks like the code in the ``zodb`` scaffold for ZODB projects is
missing some test coverage, particularly in the file named
``models.py``.
+.. _wiki-start-the-application:
+
Start the Application
=====================
@@ -189,7 +189,13 @@ visit ``/login``.
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
``pyramid.security`` module, and a value from our newly added
-``tutorial.security`` package.
+``tutorial.security`` package. Add the following import statements to the
+head of the ``views.py`` file:
+
+.. literalinclude:: src/authorization/tutorial/views.py
+ :lines: 9-18,24-25
+ :linenos:
+ :language: python
Changing Existing Views
-----------------------
@@ -16,8 +16,10 @@ Application Configuration with ``__init__.py``
A directory on disk can be turned into a Python :term:`package` by containing
an ``__init__.py`` file. Even if empty, this marks a directory as a Python
package. We use ``__init__.py`` both as a marker indicating the directory
-it's contained within is a package, and to contain configuration code. Our
-``__init__.py`` file will look like this:
+it's contained within is a package, and to contain configuration code.
+
+Open ``tutorial/tutorial/__init__.py``. It should already contain
+the following:
.. literalinclude:: src/basiclayout/tutorial/__init__.py
:linenos:
@@ -41,9 +43,7 @@ the ``main`` function we've defined in our ``__init__.py``:
When you invoke the ``pserve development.ini`` command, the ``main`` function
above is executed. It accepts some settings and returns a :term:`WSGI`
-application. You can read :ref:`startup_chapter` for details about *how*
-this function is found and called when you run ``pserve``, but for purposes
-of brevity, we'll elide the details here.
+application. (See :ref:`startup_chapter` for more about ``pserve``.)
The main function first creates a SQLAlchemy database engine using
``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the
@@ -128,30 +128,27 @@ pattern matches is done by registering a :term:`view configuration`. Our
application uses the :meth:`pyramid.view.view_config` decorator to map view
callables to each route, thereby mapping URL patterns to code.
-Here is the entirety of code in the ``views.py`` file within our package:
+Open ``tutorial/tutorial/views.py``. It should already contain the following:
.. literalinclude:: src/basiclayout/tutorial/views.py
:linenos:
:language: py
-The important part to point out here is the ``@view_config`` decorator which
-sits atop the ``my_view`` function. In fact, ``@view_config`` is so
-important that we're going to ignore the rest of the code in the module at
-this point just to explain it. The ``@view_config`` decorator associates the
-function it decorates with a :term:`view configuration`. The view
-configuration names a ``route_name`` (``home``), and names a ``renderer``,
-which is a template which lives in the ``templates`` subdirectory of the
-package.
+The important part here is that the ``@view_config`` decorator associates the
+function it decorates (``my_view``) with a :term:`view configuration`,
+consisting of:
+
+ * a ``route_name`` (``home``)
+ * a ``renderer``, which is a template from the ``templates`` subdirectory
+ of the package.
-As the result of this view configuration, when the pattern associated with
-the view named ``home`` is matched during a request, the function named
-``my_view`` will be executed. The function named ``my_view`` returns a
-dictionary; the renderer will use the ``templates/mytemplate.pt`` template to
-create a response based on the values in the dictionary.
+When the pattern associated with the ``home`` view is matched during a request,
+``my_view()`` will be executed. ``my_view()`` returns a dictionary; the
+renderer will use the ``templates/mytemplate.pt`` template to create a response
+based on the values in the dictionary.
-Note that the decorated function named ``my_view`` accepts a single argument
-named ``request``. This is the standard call signature for a Pyramid
-:term:`view callable`.
+Note that ``my_view()`` accepts a single argument named ``request``. This is
+the standard call signature for a Pyramid :term:`view callable`.
Remember in our ``__init__.py`` when we executed the
:meth:`pyramid.config.Configurator.scan` method, e.g. ``config.scan()``? The
@@ -168,13 +165,13 @@ In a SQLAlchemy-based application, a *model* object is an object composed by
querying the SQL database. The ``models.py`` file is where the ``alchemy``
scaffold put the classes that implement our models.
-Here is the complete source for ``models.py``:
+Open ``tutorial/tutorial/models.py``. It should already contain the following:
.. literalinclude:: src/basiclayout/tutorial/models.py
:linenos:
:language: py
-Let's take a look. First, we need some imports to support later code.
+Let's examine this in detail. First, we need some imports to support later code:
.. literalinclude:: src/basiclayout/tutorial/models.py
:end-before: DBSession
@@ -21,11 +21,15 @@ Making Edits to ``models.py``
(or they may live in a Python subpackage of your application package named
``models``) , but this is only by convention.
-Here's what our ``models.py`` file should look like after this step:
+Open ``tutorial/tutorial/models.py`` file and edit it to look like the
+following:
.. literalinclude:: src/models/tutorial/models.py
:linenos:
:language: py
+ :emphasize-lines: 19-21,24,26,28
+
+(The highlighted lines are the ones that need to be changed.)
The first thing we've done is to do is remove the stock ``MyModel`` class
from the generated ``models.py`` file. The ``MyModel`` class is only a
@@ -63,12 +67,15 @@ script. In particular, we'll replace our import of ``MyModel`` with one of
``Page`` and we'll change the very end of the script to create a ``Page``
rather than a ``MyModel`` and add it to our ``DBSession``.
-The result of all of our edits to ``populate.py`` will end up looking
-something like this:
+Open ``tutorial/tutorial/scripts/populate.py`` and edit it to look like the
+following:
.. literalinclude:: src/models/tutorial/scripts/populate.py
:linenos:
:language: python
+ :emphasize-lines: 14,34
+
+(Only the highlighted lines need to be changed.)
Repopulating the Database
-------------------------
@@ -122,7 +129,8 @@ Viewing the Application in a Browser
We can't. At this point, our system is in a "non-runnable" state; we'll need
to change view-related files in the next chapter to be able to start the
-application successfully. If you try to start the application, you'll wind
+application successfully. If you try to start the application (See
+:ref:`wiki2-start-the-application`), you'll wind
up with a Python traceback on your console that ends with this exception:
.. code-block:: text
@@ -28,15 +28,18 @@ dependency of the original "tutorial" application. The original "tutorial"
application was generated by the ``pcreate`` command; it doesn't know
about our custom application requirements. We need to add a dependency on
the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by
-assigning this dependency to the ``install_requires`` parameter in the
+assigning this dependency to the ``requires`` parameter in the
``setup`` function.
-Our resulting ``setup.py`` should look like so:
+Open ``tutorial/setup.py`` and edit it to look like the following:
.. literalinclude:: src/views/setup.py
:linenos:
+ :emphasize-lines: 17
:language: python
+(Only the highlighted line needs to be added)
+
Running ``setup.py develop``
============================
@@ -323,7 +326,8 @@ something like so:
Viewing the Application in a Browser
====================================
-We can finally examine our application in a browser. The views we'll try are
+We can finally examine our application in a browser (See
+:ref:`wiki2-start-the-application`). The views we'll try are
as follows:
- Visiting ``http://localhost:6543`` in a browser invokes the
Oops, something went wrong.

0 comments on commit 3484f0c

Please sign in to comment.