From 73d3a8ebde31f14f538e3fe63e85c3985fb4f9f3 Mon Sep 17 00:00:00 2001 From: Paul Winkler Date: Mon, 30 Jan 2012 14:20:08 -0500 Subject: clarify that there's no technical restriction on the value of request_method --- docs/narr/viewconfig.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index d1188eaec..763c0e131 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -280,8 +280,8 @@ configured view. *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. -- cgit v1.2.3 From ada151234b6533f3f46ceedada45ad210cbaed99 Mon Sep 17 00:00:00 2001 From: Paul Winkler Date: Mon, 30 Jan 2012 16:45:00 -0500 Subject: incorrect use of 'whom' --- docs/narr/muchadoabouttraversal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 4a249ed0d..4ce8cacfe 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/docs/narr/muchadoabouttraversal.rst @@ -15,7 +15,7 @@ Traversal is an alternative to :term:`URL dispatch` which allows .. 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 -- cgit v1.2.3 From 97b64d3b736f6abf0d78126c75d5e56e774bd234 Mon Sep 17 00:00:00 2001 From: Paul Winkler Date: Mon, 30 Jan 2012 17:34:51 -0500 Subject: Hello world with traversal, linked from various places; plus some 'what this chapter is for' notes on the other traversal chapters. Hope this helps. --- docs/index.rst | 4 ++- docs/narr/hellotraversal.py | 22 ++++++++++++++ docs/narr/hellotraversal.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++ docs/narr/introduction.rst | 2 +- docs/narr/traversal.rst | 7 +++++ 5 files changed, 102 insertions(+), 2 deletions(-) create mode 100644 docs/narr/hellotraversal.py create mode 100644 docs/narr/hellotraversal.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index be03448c9..cb632d5b2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,6 +83,7 @@ Narrative documentation in chapter form explaining how to use narr/vhosting narr/testing narr/resources + narr/hellotraversal narr/muchadoabouttraversal narr/traversal narr/security @@ -152,7 +153,8 @@ application. Check this application out via: `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 `_ website. Check this application out via: diff --git a/docs/narr/hellotraversal.py b/docs/narr/hellotraversal.py new file mode 100644 index 000000000..1ef7525e6 --- /dev/null +++ b/docs/narr/hellotraversal.py @@ -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() + + diff --git a/docs/narr/hellotraversal.rst b/docs/narr/hellotraversal.rst new file mode 100644 index 000000000..142c24f54 --- /dev/null +++ b/docs/narr/hellotraversal.rst @@ -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`. + diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 7c6ad00f3..92955aafd 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -597,7 +597,7 @@ content management systems and document management systems. Traversal also lend 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 ~~~~~~ diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index ef875c8f0..8c5d950c1 100644 --- a/docs/narr/traversal.rst +++ b/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 -- cgit v1.2.3 From 3f8e72a2412866ca937d5e95679813c00367ed0a Mon Sep 17 00:00:00 2001 From: Paul Winkler Date: Mon, 30 Jan 2012 17:40:22 -0500 Subject: another 'what is this chapter' note --- docs/narr/muchadoabouttraversal.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 4ce8cacfe..40d498391 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/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 -- cgit v1.2.3