Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 126 lines (102 sloc) 6.377 kb
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
1 .. index::
2 single: request processing
3 single: request
c5f24b2 Prep for b1
Chris McDonough authored
4 single: router
6ce1e0c Chris McDonough add more index markers
mcdonc authored
5 single: request lifecycle
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
6
57ec0ec - Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter
Chris McDonough authored
7 .. _router_chapter:
65697f3 Add a router chapter.
Chris McDonough authored
8
878328b Latex rendering.
Chris McDonough authored
9 Request Processing
10 ==================
da6ed19 - Add a diagram which explains the operation of the BFG router to the
Chris McDonough authored
11
99520ee Chris McDonough update router document
mcdonc authored
12 Once a :app:`Pyramid` application is up and running, it is ready to accept
13 requests and return responses. What happens from the time a :term:`WSGI`
14 request enters a :app:`Pyramid` application through to the point that
15 :app:`Pyramid` hands off a response back to WSGI for upstream processing?
65697f3 Add a router chapter.
Chris McDonough authored
16
99520ee Chris McDonough update router document
mcdonc authored
17 #. A user initiates a request from his browser to the hostname and port
18 number of the WSGI server used by the :app:`Pyramid` application.
65697f3 Add a router chapter.
Chris McDonough authored
19
99520ee Chris McDonough update router document
mcdonc authored
20 #. The WSGI server used by the :app:`Pyramid` application passes the WSGI
21 environment to the ``__call__`` method of the :app:`Pyramid`
22 :term:`router` object.
65697f3 Add a router chapter.
Chris McDonough authored
23
acc7765 - The ``__call__`` of a plugin "traverser" implementation (registered
Chris McDonough authored
24 #. A :term:`request` object is created based on the WSGI environment.
25
99520ee Chris McDonough update router document
mcdonc authored
26 #. The :term:`application registry` and the :term:`request` object created in
27 the last step are pushed on to the :term:`thread local` stack that
28 :app:`Pyramid` uses to allow the functions named
70acd25 Chris McDonough module name contractions
mcdonc authored
29 :func:`~pyramid.threadlocal.get_current_request` and
30 :func:`~pyramid.threadlocal.get_current_registry` to work.
81d3b54 Features
Chris McDonough authored
31
70acd25 Chris McDonough module name contractions
mcdonc authored
32 #. A :class:`~pyramid.events.NewRequest` :term:`event` is sent to any
6067de3 Chris McDonough - All references to events by interface
mcdonc authored
33 subscribers.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
34
99520ee Chris McDonough update router document
mcdonc authored
35 #. If any :term:`route` has been defined within application configuration,
36 the :app:`Pyramid` :term:`router` calls a :term:`URL dispatch` "route
37 mapper." The job of the mapper is to examine the request to determine
38 whether any user-defined :term:`route` matches the current WSGI
39 environment. The :term:`router` passes the request as an argument to the
40 mapper.
41
42 #. If any route matches, the route mapper adds attributes to the request:
43 ``matchdict`` and ``matched_route`` attributes are added to the request
44 object. The former contains a dictionary representing the matched dynamic
45 elements of the request's ``PATH_INFO`` value, the latter contains the
46 :class:`~pyramid.interfaces.IRoute` object representing the route which
47 matched. The root object associated with the route found is also
48 generated: if the :term:`route configuration` which matched has an
49 associated a ``factory`` argument, this factory is used to generate the
50 root object, otherwise a default :term:`root factory` is used.
51
52 #. If a route match was *not* found, and a ``root_factory`` argument was
53 passed to the :term:`Configurator` constructor, that callable is used to
54 generate the root object. If the ``root_factory`` argument passed to the
55 Configurator constructor was ``None``, a default root factory is used to
56 generate a root object.
57
58 #. The :app:`Pyramid` router calls a "traverser" function with the root
59 object and the request. The traverser function attempts to traverse the
60 root object (using any existing ``__getitem__`` on the root object and
61 subobjects) to find a :term:`context`. If the root object has no
62 ``__getitem__`` method, the root itself is assumed to be the context. The
63 exact traversal algorithm is described in :ref:`traversal_chapter`. The
64 traverser function returns a dictionary, which contains a :term:`context`
65 and a :term:`view name` as well as other ancillary information.
66
67 #. The request is decorated with various names returned from the traverser
68 (such as ``context``, ``view_name``, and so forth), so they can be
69 accessed via e.g. ``request.context`` within :term:`view` code.
70
71 #. A :class:`~pyramid.events.ContextFound` :term:`event` is sent to any
72 subscribers.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
73
a7e6257 Chris McDonough the canonical import location for HTTP exceptions/responses is now pyram...
mcdonc authored
74 #. :app:`Pyramid` looks up a :term:`view` callable using the context, the
75 request, and the view name. If a view callable doesn't exist for this
76 combination of objects (based on the type of the context, the type of the
77 request, and the value of the view name, and any :term:`predicate`
78 attributes applied to the view configuration), :app:`Pyramid` raises a
99edc51 Chris McDonough - Pyramid now expects Response objects to have a __call__
mcdonc authored
79 :class:`~pyramid.httpexceptions.HTTPNotFound` exception, which is meant to
80 be caught by a surrounding :term:`exception view`.
65697f3 Add a router chapter.
Chris McDonough authored
81
99520ee Chris McDonough update router document
mcdonc authored
82 #. If a view callable was found, :app:`Pyramid` attempts to call it. If an
83 :term:`authorization policy` is in use, and the view configuration is
84 protected by a :term:`permission`, :app:`Pyramid` determines whether the
85 view callable being asked for can be executed by the requesting user based
86 on credential information in the request and security information attached
87 to the context. If the view execution is allowed, :app:`Pyramid` calls
88 the view callable to obtain a response. If view execution is forbidden,
89 :app:`Pyramid` raises a :class:`~pyramid.httpexceptions.HTTPForbidden`
90 exception.
91
92 #. If any exception is raised within a :term:`root factory`, by
a7e6257 Chris McDonough the canonical import location for HTTP exceptions/responses is now pyram...
mcdonc authored
93 :term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself
99edc51 Chris McDonough - Pyramid now expects Response objects to have a __call__
mcdonc authored
94 (such as when it raises :class:`~pyramid.httpexceptions.HTTPNotFound` or
95 :class:`~pyramid.httpexceptions.HTTPForbidden`), the router catches the
a7e6257 Chris McDonough the canonical import location for HTTP exceptions/responses is now pyram...
mcdonc authored
96 exception, and attaches it to the request as the ``exception`` attribute.
97 It then attempts to find a :term:`exception view` for the exception that
98 was caught. If it finds an exception view callable, that callable is
99 called, and is presumed to generate a response. If an :term:`exception
100 view` that matches the exception cannot be found, the exception is
101 reraised.
81d3b54 Features
Chris McDonough authored
102
103 #. The following steps occur only when a :term:`response` could be
104 successfully generated by a normal :term:`view callable` or an
fd5ae92 Chris McDonough - All references to Pyramid-the-application were changed from :mod:`pyra...
mcdonc authored
105 :term:`exception view` callable. :app:`Pyramid` will attempt to execute
6067de3 Chris McDonough - All references to events by interface
mcdonc authored
106 any :term:`response callback` functions attached via
70acd25 Chris McDonough module name contractions
mcdonc authored
107 :meth:`~pyramid.request.Request.add_response_callback`. A
108 :class:`~pyramid.events.NewResponse` :term:`event` is then sent to any
d868fff Chris McDonough - Remove IResponder abstraction in favor of more general IResponse
mcdonc authored
109 subscribers. The response object's ``__call__`` method is then used to
110 generate a WSGI response. The response is sent back to the upstream WSGI
111 server.
81d3b54 Features
Chris McDonough authored
112
fd5ae92 Chris McDonough - All references to Pyramid-the-application were changed from :mod:`pyra...
mcdonc authored
113 #. :app:`Pyramid` will attempt to execute any :term:`finished
81d3b54 Features
Chris McDonough authored
114 callback` functions attached via
70acd25 Chris McDonough module name contractions
mcdonc authored
115 :meth:`~pyramid.request.Request.add_finished_callback`.
81d3b54 Features
Chris McDonough authored
116
117 #. The :term:`thread local` stack is popped.
65697f3 Add a router chapter.
Chris McDonough authored
118
878328b Latex rendering.
Chris McDonough authored
119 .. image:: router.png
120
99520ee Chris McDonough update router document
mcdonc authored
121 This is a very high-level overview that leaves out various details. For more
122 detail about subsystems invoked by the :app:`Pyramid` router such as
123 traversal, URL dispatch, views, and event processing, see
124 :ref:`urldispatch_chapter`, :ref:`views_chapter`, and :ref:`events_chapter`.
878328b Latex rendering.
Chris McDonough authored
125
Something went wrong with that request. Please try again.