diff options
Diffstat (limited to 'vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst')
-rw-r--r-- | vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst new file mode 100644 index 0000000..0811bb0 --- /dev/null +++ b/vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst @@ -0,0 +1,81 @@ +*************************** +Streaming the response body +*************************** + +CherryPy handles HTTP requests, packing and unpacking the low-level details, +then passing control to your application's :ref:`pagehandlers`, which produce +the body of the response. CherryPy allows you to return body content in a +variety of types: a string, a list of strings, a file. CherryPy also allows you +to *yield* content, rather than *return* content. When you use "yield", you also +have the option of streaming the output. + +**In general, it is safer and easier to not stream output.** Therefore, +streaming output is off by default. + +The "normal" CherryPy response process +====================================== + +When you provide content from your page handler, CherryPy manages the +conversation between the HTTP server and your code like this: + +.. image:: cpreturn.gif + +Notice that the HTTP server gathers all output first and then writes everything +to the client at once: status, headers, and body. This works well for static or +simple pages, since the entire response can be changed at any time, either in +your application code, or by the CherryPy framework. + +How "streaming output" works with CherryPy +========================================== + +When you set the config entry "response.stream" to True (and use "yield"), +CherryPy manages the conversation between the HTTP server and your code like this: + +.. image:: cpyield.gif + +When you stream, your application doesn't immediately pass raw body content +back to CherryPy or to the HTTP server. Instead, it passes back a generator. +At that point, CherryPy finalizes the status and headers, **before** the +generator has been consumed, or has produced any output. This is necessary to +allow the HTTP server to send the headers and pieces of the body as they become +available. + +Once CherryPy has set the status and headers, it sends them to the HTTP server, +which then writes them out to the client. From that point on, the CherryPy +ramework mostly steps out of the way, and the HTTP server essentially requests +content directly from your application code (your page handler method). + +Therefore, when streaming, if an error occurs within your page handler, +CherryPy will not catch it--the HTTP server will catch it. Because the headers +(and potentially some of the body) have already been written to the client, +the server *cannot* know a safe means of handling the error, and will therefore +simply close the connection (the current, builtin servers actually write out a +short error message in the body, but this may be changed, and is not guaranteed +behavior for all HTTP servers you might use with CherryPy). + +In addition, you cannot manually modify the status or headers within your page +handler if that handler method is a streaming generator, because the method will +not be iterated over until after the headers have been written to the client. +**This includes raising exceptions like HTTPError, NotFound, InternalRedirect +and HTTPRedirect.** To use a streaming generator while modifying headers, you +would have to return a generator that is separate from (or embedded in) your +page handler. For example:: + + class Root: + def thing(self): + cherrypy.response.headers['Content-Type'] = 'text/plain' + if not authorized(): + raise cherrypy.NotFound() + def content(): + yield "Hello, " + yield "world" + return content() + thing._cp_config = {'response.stream': True} + +Streaming generators are sexy, but they play havoc with HTTP. CherryPy allows +you to stream output for specific situations: pages which take many minutes to +produce, or pages which need a portion of their content immediately output to +the client. Because of the issues outlined above, **it is usually better to +flatten (buffer) content rather than stream content**. Do otherwise only when +the benefits of streaming outweigh the risks. + |