Merge branch 'master' of github.com:Pylons/pyramid

Chris McDonough

2012-01-31 a7496ad1a9dde89a9c656b59f8bcc0f2d8f29acf

Merge branch 'master' of github.com:Pylons/pyramid

 docs/index.rst

@@ -83,6 +83,7 @@
   narr/vhosting
   narr/testing
   narr/resources
   narr/hellotraversal
   narr/muchadoabouttraversal
   narr/traversal
   narr/security
@@ -152,7 +153,8 @@

`virginia <https://github.com/Pylons/virginia>`_ is a very simple dynamic
file rendering application.  It is willing to render structured text
documents, HTML documents, and images from a filesystem directory.  An
documents, HTML documents, and images from a filesystem directory.
It's also a good example of :term:`traversal`. An
earlier version of this application runs the `repoze.org
<http://repoze.org>`_ website.  Check this application out via:


 docs/narr/hellotraversal.py

New file
@@ -0,0 +1,22 @@
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response

class Resource(dict):
    pass

def get_root(request):
    return Resource({'a': Resource({'b': Resource({'c': Resource()})})})

def hello_world_of_resources(context, request):
    output = "Here's a resource and its children: %s" % context
    return Response(output)

if __name__ == '__main__':
    config = Configurator(root_factory=get_root)
    config.add_view(hello_world_of_resources, context=Resource)
    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()



 docs/narr/hellotraversal.rst

New file
@@ -0,0 +1,69 @@
.. _hello_traversal_chapter:

Hello Traversal World
======================


.. index::
   single: traversal quick example

Traversal is an alternative to URL dispatch which allows Pyramid
applications to map URLs to code.

If code speaks louder than words, maybe this will help. Here is a
single-file Pyramid application that uses traversal:

.. literalinclude:: hellotraversal.py
   :linenos:

You may notice that this application is intentionally very similar to
the "hello world" app from :doc:`firstapp`.

On lines 5-6, we create a trivial :term:`resource` class that's just a
dictionary subclass.

On lines 8-9, we hard-code a :term:`resource tree` in our :term:`root
factory` function.

On lines 11-13 we define a single :term:`view callable` that can
display a single instance of our Resource class, passed as the
``context`` argument.

The rest of the file sets up and serves our pyramid WSGI app.  Line 18
is where our view gets configured for use whenever the traversal ends
with an instance of our Resource class.

Interestingly, there are no URLs explicitly configured in this
application. Instead, the URL space is defined entirely by the keys in
the resource tree.

Example requests
----------------

If this example is running on http://localhost:8080, and the user
browses to http://localhost:8080/a/b, Pyramid will call
``get_root(request)`` to get the root resource, then traverse the tree
from there by key; starting from the root, it will find the child with
key ``"a"``, then its child with key ``"b"``; then use that as the
``context`` argument for calling ``hello_world_of_resources``.

Or, if the user browses to http://localhost:8080/ , Pyramid will
stop at the root - the outermost Resource instance, in this case - and
use that as the ``context`` argument to the same view.

Or, if the user browses to a key that doesn't exist in this resource
tree, like http://localhost:8080/xyz or
http://localhost:8080/a/b/c/d, the traversal will end by raising a
KeyError, and Pyramid will turn that into a 404 HTTP response.

A more complicated application could have many types of resources,
with different view callables defined for each type, and even multiple
views for each type.

See Also
---------

Full technical details may be found in :doc:`traversal`.

For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.


 docs/narr/introduction.rst

@@ -597,7 +597,7 @@
systems that require very granular security ("Bob can edit *this* document"
as opposed to "Bob can edit documents").

Example: :ref:`much_ado_about_traversal_chapter`.
Example: :ref:`hello_traversal_chapter` and :ref:`much_ado_about_traversal_chapter`.

Tweens
~~~~~~

 docs/narr/muchadoabouttraversal.rst

@@ -4,6 +4,8 @@
Much Ado About Traversal
========================

(Or, why you should care about it)

.. note::

   This chapter was adapted, with permission, from a blog post by `Rob
@@ -15,7 +17,7 @@

.. note::
   
   Ex-Zope users whom are already familiar with traversal and view lookup
   Ex-Zope users who are already familiar with traversal and view lookup
   conceptually may want to skip directly to the :ref:`traversal_chapter`
   chapter, which discusses technical details.  This chapter is mostly aimed
   at people who have previous :term:`Pylons` experience or experience in

 docs/narr/traversal.rst

@@ -3,6 +3,13 @@
Traversal
=========

This chapter explains the technical details of how traversal works in
Pyramid.

For a quick example, see :doc:`hellotraversal`.

For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.

A :term:`traversal` uses the URL (Universal Resource Locator) to find a
:term:`resource` located in a :term:`resource tree`, which is a set of
nested dictionary-like objects.  Traversal is done by using each segment

 docs/narr/viewconfig.rst

@@ -280,8 +280,8 @@
  *This is an advanced feature, not often used by "civilians"*.

``request_method``
  This value can be one of the strings ``GET``, ``POST``, ``PUT``,
  ``DELETE``, or ``HEAD`` representing an HTTP ``REQUEST_METHOD``.  A view
  This value can be a string (typically ``"GET"``, ``"POST"``, ``"PUT"``,
  ``"DELETE"``, or ``"HEAD"``) representing an HTTP ``REQUEST_METHOD``.  A view
  declaration with this argument ensures that the view will only be called
  when the request's ``method`` attribute (aka the ``REQUEST_METHOD`` of the
  WSGI environment) string matches the supplied value.