« 97% of IT workers "feel traumatized" by their daily workSespe Wilderness Trip »

How CherryPy processes a request

06/15/06

Permalink 01:23:24 am, by admin Email , 753 words   English (US)
Categories: Python, CherryPy

How CherryPy processes a request

Inspired by James Bennett, here's a little treatise on how CherryPy processes a request. A couple of differences, though. First, Django is a "full-stack" web framework, with an ORM, built-in templating, etcetera, whereas CherryPy focuses on HTTP. Second, I'll be showing the process for CherryPy 2.2 (the current stable branch), but I'll try to point out along the way where CherryPy 3 (now in alpha) differs.

HTTP Server

Something must actually sit on a listening socket and receive requests from HTTP clients. CherryPy provides an HTTP server (_cpwsgiserver.py), or you can use Apache, lighttpd, or others.

Bridge from HTTP Server to CherryPy

The Web Server Gateway Interface spec came into being to connect various HTTP servers to various web frameworks (and gateways and middleware and...). If you want to use it to connect an HTTP server with CherryPy, feel free. CherryPy provides a "WSGI application callable" in _cpwsgi.py. Otherwise, you need a specific adapter at this stage to connect the two.

The CherryPy Engine

Whether you use WSGI or not for the Bridge, it calls Engine.request(), which creates the all-important objects cherrypy.request and cherrypy.response, returning the former. The Bridge then calls request.run(), passing it the incoming message stream.

The CherryPy Request

Several steps occur here to convert the incoming stream to more usable data structures, pass the request to the appropriate user code, and then convert outbound data. In-between the standard processing steps, users can define extra code to be run via filters (CP 2.2) or hooks (CP 3). Here's how CherryPy 2 does it:

  1. Request.processRequestLine() analyzes the first line of the request, turning "GET /path/to/resource?key=val HTTP/1.1" into a request method, path, query string, and version.
  2. Any on_start_resource filters are run.
  3. Request.processHeaders() turns the incoming HTTP request headers into a dictionary, and separates Cookie information.
  4. Any before_request_body filters are run.
  5. Request.processBody() turns the incoming HTTP request body into a dictionary if possible, otherwise, it's passed onward as a file-like object.
  6. Any before_main filters are run.
  7. The user-supplied page handler is looked up (see below).
  8. The user-supplied page handler is invoked. Its return value, which can be a string, a list, a file, or a generator object, will be used for the response body.
  9. Any before_finalize filters will be run.
  10. Response.finalize() checks for HTTP correctness of the response, and transforms user-friendly data structures into HTTP-server-friendly structures.
  11. Any on_end_resource filters are run.

CherryPy 3 performs the same steps as above, but in the order: 1, 3, 7, 2, 4, 5, 6, 8, 9, 10, 11. That is, it determines which bit of user code will respond to the request much earlier in the process. This also means that internal redirects can "start over" much earlier. In addition, CP 3 can collect configuration data once (at the same time that it looks up the page handler); CP 2 recollected config data every time it was used.

Page handlers

As mentioned (steps 7 and 8, above), CherryPy users write "page handlers", functions which receive the request parameters as arguments, and return the response body. CherryPy makes clever use of threadlocals, so all other data a developer needs is available in the global cherrypy.request and cherrypy.response objects (the parameters are as well, but it's awfully convenient to receive them as arguments to the page handler, and to return the body rather than setting it).

The URL is mapped to a page handler by traversing a tree of such handlers, so that the handler for "/a/b/c" is most likely root.a.b.c(). I say "most likely", because you can also define index() handlers and default() handlers.

The CherryPy Response

When the call to Request.run() returns, the Bridge uses the Response attributes status, header_list, and body to construct the outbound stream, and pass it to the HTTP server that made the request. CherryPy works hard to support both buffered and streaming output, so the body may be a generator object that is only iterated over at this point.

Exceptional circumstances

The page handler, or any of the filters/hooks, can decide that the response is complete, and that processing should be stopped. Most often, this is accomplished by raising an HTTPRedirect (3xx) exception, or an HTTPError (4xx or 5xx; NotFound (404) is so common it has its own subclass). Unanticipated errors are automatically converted into HTTPError(500). Users have some facility for modifying the actual error output with additional error filters/hooks.

That's it!

No feedback yet

Leave a comment


Your email address will not be revealed on this site.

Your URL will be displayed.

Please enter the phrase "I am a real human." in the textbox above.
(Line breaks become <br />)
(Name, email & website)
(Allow users to contact you through a message form (your email will not be revealed.)
September 2020
Sun Mon Tue Wed Thu Fri Sat
 << <   > >>
    1 2 3 4 5
6 7 8 9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30      

Search

The requested Blog doesn't exist any more!

XML Feeds

powered by b2evolution