Changeset Navigation

← Previous Changeset
Next Changeset →

Changeset 853

Timestamp:

11/30/05 15:00:46

Author:

lawouach

Message:

added information about filters hooks

Files:

trunk/docs/book/xml/apireference.xml (modified) (2 diffs)

Legend:

: Unmodified
: Added
: Removed
: Modified
: Copied
: Moved

trunk/docs/book/xml/apireference.xml

r796	r853
1		<?xml version="1.0" encoding="UTF-8"?>
2		<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
3		xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="apireference">
4		<title>API reference</title>
5		<section id="cherrypy">
6		<title>cherrypy.threadData</title>
7		<para>This attribute holds attributes that map to this thread only.</para>
8		</section>
9		<section id="cherrypyrequest">
10		<title>cherrypy.request</title>
11		<para>The cherrypy.request object contains request-related objects. Pretty lame description,
12		but that's all it does; it's a big data dump. At the beginning of each HTTP request, the
13		existing request object is destroyed, and a new one is created, (one request object for each
14		thread). Therefore, CherryPy (and you yourself) can stick data into cherrypy.request and not
15		worry about it conflicting with other requests.</para>
16		<section>
17		<title>cherrypy.request.remoteAddr</title>
18		<para>This attribute is a string containing the IP address of the client. It will be an
19		empty string if it is not available.</para>
20		</section>
21		<section>
22		<title>cherrypy.request.remotePort</title>
23		<para>This attribute is an int containing the TCP port number of the client. It will be
24		-1 if it is not available.</para>
25		</section>
26		<section>
27		<title>cherrypy.request.remoteHost</title>
28		<para>This attribute is a string containing the remote hostname of the client.</para>
29		</section>
30		<section>
31		<title>cherrypy.request.headerMap</title>
32		<para>This attribute is a dictionary containing the received HTTP headers, with
33		automatically titled keys (e.g., "Content-Type"). As it's a dictionary, no duplicates are
34		allowed.</para>
35		</section>
36		<section>
37		<title>cherrypy.request.headers</title>
38		<para>This attribute is a list of (header, value) tuples containing the received HTTP
39		headers. In general, you probably want to use headerMap instead; this is only here in
40		case you need to inspect duplicates in the request headers.</para>
41		</section>
42		<section>
43		<title>cherrypy.request.requestLine</title>
44		<para>This attribute is a string containing the first line of the raw HTTP request; for
45		example, "GET /path/page HTTP/1.1".</para>
46		</section>
47		<section>
48		<title>cherrypy.request.simpleCookie</title>
49		<para>This attribute is a SimpleCookie instance from the standard library's Cookie module
50		which contains the incoming cookie values from the client.</para>
51		</section>
52		<section>
53		<title>cherrypy.request.rfile</title>
54		<para>This attribute is the input stream to the client, if applicable. See
55		cherrypy.request.processRequestBody for more information.</para>
56		</section>
57		<section>
58		<title>cherrypy.request.body</title>
59		<para>This attribute is the request entity body, if applicable. See
60		cherrypy.request.processRequestBody for more information.</para>
61		</section>
62		<section>
63		<title>cherrypy.request.processRequestBody</title>
64		<para>This attribute specifies whether or not the request's body (request.rfile, which is
65		POST or PUT data) will be handled by CherryPy. If True (the default for POST and PUT
66		requests), then request.rfile will be consumed by CherryPy (and unreadable after that).
67		If the request Content-Type is "application/x-www-form-urlencoded", then the rfile will
68		be parsed and placed into request.paramMap; otherwise, it will be available in
69		request.body. If cherrypy.request.processRequestBody is False, then the rfile is not
70		consumed, but will be readable by the exposed method.</para>
71		</section>
72		<section>
73		<title>cherrypy.request.method</title>
74		<para>This attribute is a string containing the HTTP request method, such as GET or
75		POST.</para>
76		</section>
77		<section>
78		<title>cherrypy.request.protocol</title>
79		<para>This attribute is a string containing the HTTP protocol of the request in the form
80		of HTTP/x.x</para>
81		</section>
82		<section>
83		<title>cherrypy.request.version</title>
84		<para>This attribute is a Version object which represents the HTTP protocol. It's the
85		same os request.protocol, but allows easy comparisons like <code>if
86		cherrypy.request.version >= "1.1": do_http_1_1_thing</code>.</para>
87		</section>
88		<section>
89		<title>cherrypy.request.queryString</title>
90		<para>This attribute is a string containing the query string of the request (the part of
91		the URL following '?').</para>
92		</section>
93		<section>
94		<title>cherrypy.request.path</title>
95		<para>This attribute is a string containing the path of the resource the client
96		requested.</para>
97		</section>
98		<section>
99		<title>cherrypy.request.paramMap</title>
100		<para>This attribute is a dictionary containing the query string and POST arguments of
101		this request.</para>
102		</section>
103		<section>
104		<title>cherrypy.request.base</title>
105		<para>This attribute is a string containing the root URL of the server. By default, it is
106		equal to request.scheme://request.headerMap['Host'].</para>
107		</section>
108		<section>
109		<title>cherrypy.request.browserUrl</title>
110		<para>This attribute is a string containing the URL the client requested. By default, it
111		is equal to <code>request.base + request.path</code>, plus the querystring, if
112		provided.</para>
113		</section>
114		<section>
115		<title>cherrypy.request.objectPath</title>
116		<para>This attribute is a string containing the path of the exposed method that will be
117		called to handle this request. This is usually the same as cherrypy.request.path, but can
118		be changed in a filter to change which method is actually called.</para>
119		</section>
120		<section>
121		<title>cherrypy.request.originalPath</title>
122		<para>This attribute is a string containing the original value of cherrypy.request.path,
123		in case it is modified by a filter during the request.</para>
124		</section>
125		<section>
126		<title>cherrypy.request.originalParamMap</title>
127		<para>This attribute is a string containing the original value of
128		cherrypy.request.paramMap, in case it is modified by a filter during the request.</para>
129		</section>
130		<section>
131		<title>cherrypy.request.scheme</title>
132		<para>This attribute is a string containing the URL scheme used in this request. It is
133		either "http" or "https".</para>
134		</section>
135		</section>
136		<!-- end cherrypy.request section -->
137		<section id="cherrypyresponse">
138		<title>cherrypy.response</title>
139		<para>The cherrypy.response object contains response-related objects. Pretty lame
140		description, but that's all it does; it's a big data dump. At the beginning of each HTTP
141		request, the existing response object is destroyed, and a new one is created, (one response
142		object for each thread). Therefore, CherryPy (and you yourself) can stick data into
143		cherrypy.response and not worry about it conflicting with other requests.</para>
144		<section>
145		<title>cherrypy.response.headerMap</title>
146		<para>This attribute is a dictionary with automatically titled keys (e.g.,
147		"Content-Length"). It holds all outgoing HTTP headers to the client.</para>
148		</section>
149		<section>
150		<title>cherrypy.response.headers</title>
151		<para>This attribute is a list of (header, value) tuples. It's not available until the
152		response has been finalized; it's really only there in the extremely rare cases when you
153		need duplicate response headers. In general, you should use request.headerMap
154		instead.</para>
155		</section>
156		<section>
157		<title>cherrypy.response.simpleCookie</title>
158		<para>This attribute is a SimpleCookie instance from the standard library's Cookie
159		module. It contains the outgoing cookie values.</para>
160		</section>
161		<section>
162		<title>cherrypy.response.body</title>
163		<para>This attribute is originally just the return value of the exposed method, but by
164		the end of the request it must be an iterable (usually a list or generator of strings)
165		which will be the content of the HTTP response.</para>
166		</section>
167		<section>
168		<title>cherrypy.response.status</title>
169		<para>This attribute is a string containing the HTTP response code in the form "###
170		Reason-Phrase", i.e. "200 OK". You may also set it to an int, in which case the response
171		finalization process will supply a Reason-Phrase for you.</para>
172		</section>
173		<section>
174		<title>cherrypy.response.version</title>
175		<para>This attribute is a Version object, representing the HTTP protocol version of the
176		response. This is not necessarily the value that will be written in the response!
177		Instead, it should be used to determine which features are <emphasis>available</emphasis>
178		for the response. For example, an HTTP server may send an HTTP/1.1 response even though
179		the client is known to only understand HTTP/1.0—the response.version will be set to
180		Version("1.0") to inform you of this, so that you (and CherryPy) can restrict the
181		response to HTTP/1.0 features only.</para>
182		</section>
183		</section>
184		<section id="cherrypyserver">
185		<title>cherrypy.server</title>
186		<section>
187		<title>cherrypy.server.start(initOnly=False, serverClass=_missing)</title>
188		<para>Start the CherryPy Server. Simple websites may call this without any arguments, to
189		run the default server. If initOnly is False (the default), this function will block
190		until KeyboardInterrupt or SystemExit is raised, so that the process will persist. When
191		using one of the built-in HTTP servers, you should leave this set to False. You should
192		only set it to True if you're running CherryPy as an extension to another HTTP server
193		(for example, when using Apache and mod_python with CherryPy), in which case the foreign
194		HTTP server should do its own process-management.</para>
195		<para>Use the serverClass argument to specify that you wish to use an HTTP server other
196		than the default, built-in WSGIServer. If missing, config.get("server.class") will be
197		checked for an alternate value; otherwise, the default is used. Possible alternate values
198		(you may pass the class names as a string if you wish):</para>
199		<itemizedlist>
200		<listitem>
201		<para><code>cherrypy._cphttpserver.CherryHTTPServer</code>: this will load the
202		old, single-threaded built-in HTTP server. This server is deprecated and will
203		probably be removed in CherryPy 2.2.</para>
204		</listitem>
205		<listitem>
206		<para><code>cherrypy._cphttpserver.PooledThreadServer</code>: this will load the
207		old, multi-threaded built-in HTTP server. This server is deprecated and will
208		probably be removed in CherryPy 2.2.</para>
209		</listitem>
210		<listitem>
211		<para><code>cherrypy._cphttpserver.embedded_server</code>: use this to
212		automatically select between the CherryHTTPServer and the PooledThreadServer
213		based on the value of config.get("server.threadPool") and
214		config.get("server.socketFile").</para>
215		</listitem>
216		<listitem>
217		<para><code>None</code>: this will not load any HTTP server. Note that this is
218		not the default; the default (if serverClass is not given) is to load the
219		WSGIServer.</para>
220		</listitem>
221		<listitem>
222		<para>Any other class (or dotted-name string): load a custom HTTP server.</para>
223		</listitem>
224		</itemizedlist>
225		<para>You <emphasis>must</emphasis> call this function from Python's main thread, and set
226		initOnly to False, if you want CherryPy to shut down when KeyboardInterrupt or SystemExit
227		are raised (including Ctrl-C). The only time you might want to do otherwise is if you run
228		CherryPy as a Windows service, or as an extension to, say, mod_python, and even then, you
229		might want to anyway.</para>
230		</section>
231		<section>
232		<title>cherrypy.server.blocking</title>
233		<para>If the "initOnly" argument to server.start is True, this will be False, and
234		vice-versa.</para>
235		</section>
236		<section>
237		<title>cherrypy.server.httpserverclass</title>
238		<para>Whatever HTTP server class is set in server.start will be stuck in here.</para>
239		</section>
240		<section>
241		<title>cherrypy.server.httpserver</title>
242		<para>Whatever HTTP server class is set in server.start will be instantiated and stuck in
243		here.</para>
244		</section>
245		<section>
246		<title>cherrypy.server.state</title>
247		<para>One of three values, indicating the state of the server:<itemizedlist>
248		<listitem>
249		<para>STOPPED = 0: The server hasn't been started, and will not accept
250		requests.</para>
251		</listitem>
252		<listitem>
253		<para>STARTING = None: The server is in the process of starting, or an error
254		occured while trying to start the server.</para>
255		</listitem>
256		<listitem>
257		<para>STARTED = 1: The server has started (including an HTTP server if
258		requested), and is ready to receive requests.</para>
259		</listitem>
260		</itemizedlist></para>
261		</section>
262		<section>
263		<title>cherrypy.server.ready</title>
264		<para>True if the server is ready to receive requests, false otherwise. Read-only.</para>
265		</section>
266		<section>
267		<title>cherrypy.server.wait()</title>
268		<para>Since server.start usually blocks, other threads need to be started before calling
269		server.start; however, they often must wait for server.start to complete it's setup of
270		the HTTP server. Use this function from other threads to make them wait for the HTTP
271		server to be ready to receive requests.</para>
272		</section>
273		<section>
274		<title>cherrypy.server.start_with_callback(func, args=(), kwargs={},
275		serverClass=_missing)</title>
276		<para>Since server.start usually blocks, use this to easily run another function in a new
277		thread. It starts the new thread and then runs server.start. The new thread automatically
278		waits for the server to finish its startup procedure.</para>
279		</section>
280		<section>
281		<title>cherrypy.server.stop()</title>
282		<para>Stop the CherryPy Server. Well, "suspend" might be a better term—this doesn't
283		terminate the process.</para>
284		</section>
285		<section>
286		<title>cherrypy.server.interrupt</title>
287		<para>Usually None, set this to KeyboardInterrupt() or SystemExit() to shut down the
288		entire process. That is, the new exception will be raised in the main thread.</para>
289		</section>
290		<section>
291		<title>cherrypy.server.restart()</title>
292		<para>Restart the CherryPy Server.</para>
293		</section>
294		<section>
295		<title>cherrypy.server.onStartServerList</title>
296		<para>A list of functions that will be called when the server starts.</para>
297		</section>
298		<section>
299		<title>cherrypy.server.onStopServerList</title>
300		<para>A list of functions that will be called when the server stops.</para>
301		</section>
302		<section>
303		<title>cherrypy.server.onStartThreadList</title>
304		<para>A list of functions that will be called when each request thread is started. Note
305		that such threads do not need to be started or controlled by CherryPy; for example, when
306		using CherryPy with mod_python, Apache will start and stop the request threads.
307		Nevertheless, CherryPy will run the onStartThreadList functions upon the first request
308		using each distinct thread.</para>
309		</section>
310		<section>
311		<title>cherrypy.server.onStopThreadList</title>
312		<para>A list of functions that will be called when each request thread is stopped.</para>
313		</section>
314		<section>
315		<title>cherrypy.server.request()</title>
316		<para>HTTP servers should call this function to create a new Request and Response object.
317		The return value is the Request object; call its <code>run</code> method to have the
318		CherryPy core process the request data and populate the response.</para>
319		</section>
320		</section>
321		<!-- end cherrypyserver section -->
322		<section id="cherrypyconfig">
323		<title>cherrypy.config</title>
324		<section>
325		<title>cherrypy.config.get(key, defaultValue = None, returnSection = False)</title>
326		<para>This function returns the configuration value for the given key. The function
327		checks if the setting is defined for the current request path; it walks up the request
328		path until the key is found, or it returns the default value. If returnSection is True,
329		the function returns the configuration path where the key is defined instead.</para>
330		</section>
331		<section>
332		<title>cherrypy.config.getAll(key)</title>
333		<para>The getAll function returns a list containing a (path, value) tuple for all
334		occurences of the key within the request path. This function allows applications to
335		inherit configuration data defined for parent paths.</para>
336		</section>
337		<section>
338		<title>cherrypy.config.update(updateMap=None, file=None)</title>
339		<para>Function to update the configuration map. The "updateMap" argument is a dictionary
340		of the form {'sectionPath' : { } }. The "file" argument is the path to the configuration
341		file.</para>
342		</section>
343		<section>
344		<title>cherrypy.config.environments</title>
345		<para>Dict containing config defaults for each named server.environment.</para>
346		</section>
347		</section>
348		<section id="exceptions">
349		<title>cherrypy exceptions</title>
350		<section>
351		<title>cherrypy.HTTPError</title>
352		<para>This exception can be used to automatically send a response using a http status
353		code, with an appropriate error page.</para>
354		<section>
355		<title>cherrypy.NotFound</title>
356		<para>This exception is raised when CherryPy is unable to map a requested path to an
357		internal method. It's a subclass of HTTPError (404).</para>
358		</section>
359		</section>
360		<section>
361		<title>cherrypy.HTTPRedirect</title>
362		<para>This exception will force a HTTP redirect.</para>
363		</section>
364		<section>
365		<title>cherrypy.InternalRedirect</title>
366		<para>This exception will redirect processing to another path within the site (without
367		informing the client).</para>
368		</section>
369		</section>
370		<section id="lib">
371		<title>The CherryPy library</title>
372		<section>
373		<title>cherrypy.lib.cptools</title>
374		<section>
375		<title>ExposeItems</title>
376		<para>Utility class that exposes a getitem-aware object. It does not provide index()
377		or default() methods, and it does not expose the individual item objects - just the
378		list or dict that contains them. User-specific index() and default() methods can be
379		implemented by inheriting from this class.</para>
380		</section>
381		<section>
382		<title>PositionalParametersAware</title>
383		<para>Utility class that restores positional parameters functionality that was found
384		in 2.0.0-beta.</para>
385		</section>
386		<section>
387		<title>getAccept(headername)</title>
388		<para>Returns a list of AcceptValue objects from the specified Accept-* header (or
389		None if the header is not present). The list is sorted so that the most-preferred
390		values are first in the list.</para>
391		<para>Each AcceptValue object has a <code>value</code> attribute, a string which is
392		the value itself. For example, if <code>headername</code> is "Accept-Encoding", the
393		<code>value</code> attribute might be "gzip". It also has a (read-only)
394		<code>qvalue</code> attribute, a float between 0 and 1 which specifies the client's
395		preference for the value; higher numbers are preferred. Finally, each AcceptValue
396		also has a <code>params</code> attribute, a dict; for most headers, this dict will
397		only possess the original "q" value as a string.</para>
398		<para>If <code>headername</code> is "Accept" (the default), then the params attribute
399		may contain extra parameters which further differentiate the value. In addition,
400		<code>params["q"]</code> may itself be an AcceptValue object, with its own
401		<code>params</code> dict. Don't ask us why; ask the authors of the HTTP spec.</para>
402		</section>
403		<section>
404		<title>getRanges(content_length)</title>
405		<para>Returns a list of (start, stop) indices from a Range request header. Returns
406		None if no such header is provided in the request. Each (start, stop) tuple will be
407		composed of two ints, which are suitable for use in a slicing operation. That is, the
408		header "Range: bytes=3-6", if applied against a Python string, is requesting
409		resource[3:7]. This function will return the list [(3, 7)].</para>
410		</section>
411		<section>
412		<title>HeaderMap</title>
413		<para>A subclass of Python's builtin <code>dict</code> class; CherryPy's default
414		<code>request.headerMap</code> and <code>response.headerMap</code> objects are
415		instances of this class. The keys are automatically titled
416		(<code>str(key).title()</code>) in order to provide case-insensitive comparisons and
417		avoid duplicates.</para>
418		</section>
419		<section>
420		<title>parseRequestLine(requestLine)</title>
421		<para>Returns (<code>method, path, querystring, protocol</code>) from an HTTP
422		requestLine. The default Request processor calls this function.</para>
423		</section>
424		<section>
425		<title>parseQueryString(queryString, keep_blank_values=True)</title>
426		<para>Returns a dict of <code>{'key': 'value'}</code> pairs from an HTTP "key=value"
427		query string. Also handles server-side image map query strings. The default Request
428		processor calls this function.</para>
429		</section>
430		<section>
431		<title>paramsFromCGIForm(form)</title>
432		<para>Returns a dict of <code>{'key': ''value'}</code> pairs from a
433		<code>cgi.FieldStorage</code> object. The default Request processor calls this
434		function.</para>
435		</section>
436		<section>
437		<title>serveFile(path, contentType=None, disposition=None, name=None)</title>
438		<para>Set status, headers, and body in order to serve the file at the given path. The
439		Content-Type header will be set to the contentType arg, if provided. If not provided,
440		the Content-Type will be guessed by the extension of the file. If disposition is not
441		None, the Content-Disposition header will be set to "<disposition>;
442		filename=<name>". If name is None, it will be set to the basename of path. If
443		disposition is None, no Content-Disposition header will be written.</para>
444		</section>
445		</section>
446		<section>
447		<title>cherrypy.lib.covercp</title>
448		<para>This module both provides code-coverage tools, and may also be run as a script. To
449		use this module, or the coverage tools in the test suite, you need to download
450		'coverage.py', either Gareth Rees' <ulink url="???">original implementation</ulink> or
451		Ned Batchelder's <ulink
452		url="http://www.nedbatchelder.com/code/modules/coverage.html">enhanced
453		version</ulink>.</para>
454		<para>Set cherrypy.codecoverage to True to turn on coverage tracing. Then, use the
455		covercp.serve() function to browse the results in a web browser. If you run this module
456		as a script (i.e., from the command line), it will call serve() for you.</para>
457		</section>
458		<section>
459		<title>cherrypy.lib.profiler</title>
460		<para>You can profile any of your page handlers (exposed methods) as follows:</para>
461		<example>
462		<title>Profiling example</title>
463		<programlisting><code>from cherrypy.lib import profile
	1	<?xml version='1.0'?>
	2	<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5b1//EN" "http://www.oasis-open.org/docbook/xml/4.5b1/docbookx.dtd">
	3	<section xml:id="apireference" xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
	4
	5	<title>API reference</title>
	6
	7	<section id="cherrypy">
	8
	9	<title>cherrypy.threadData</title>
	10
	11	<para>This attribute holds attributes that map to this thread
	12	only.</para>
	13
	14	</section>
	15
	16	<section id="cherrypyrequest">
	17
	18	<title>cherrypy.request</title>
	19
	20	<para>The cherrypy.request object contains request-related objects.
	21	Pretty lame description, but that's all it does; it's a
	22	big data dump. At the beginning of each HTTP request, the existing
	23	request object is destroyed, and a new one is created, (one request
	24	object for each thread). Therefore, CherryPy (and you yourself) can
	25	stick data into cherrypy.request and not worry about it conflicting
	26	with other requests.</para>
	27
	28	<section>
	29
	30	<title>cherrypy.request.remoteAddr</title>
	31
	32	<para>This attribute is a string containing the IP address of the
	33	client. It will be an empty string if it is not available.</para>
	34
	35	</section>
	36
	37	<section>
	38
	39	<title>cherrypy.request.remotePort</title>
	40
	41	<para>This attribute is an int containing the TCP port number of
	42	the client. It will be -1 if it is not available.</para>
	43
	44	</section>
	45
	46	<section>
	47
	48	<title>cherrypy.request.remoteHost</title>
	49
	50	<para>This attribute is a string containing the remote hostname
	51	of the client.</para>
	52
	53	</section>
	54
	55	<section>
	56
	57	<title>cherrypy.request.headerMap</title>
	58
	59	<para>This attribute is a dictionary containing the received HTTP
	60	headers, with automatically titled keys (e.g.,
	61	"Content-Type"). As it's a dictionary, no
	62	duplicates are allowed.</para>
	63
	64	</section>
	65
	66	<section>
	67
	68	<title>cherrypy.request.headers</title>
	69
	70	<para>This attribute is a list of (header, value) tuples
	71	containing the received HTTP headers. In general, you probably
	72	want to use headerMap instead; this is only here in case you need
	73	to inspect duplicates in the request headers.</para>
	74
	75	</section>
	76
	77	<section>
	78
	79	<title>cherrypy.request.requestLine</title>
	80
	81	<para>This attribute is a string containing the first line of the
	82	raw HTTP request; for example, "GET /path/page
	83	HTTP/1.1".</para>
	84
	85	</section>
	86
	87	<section>
	88
	89	<title>cherrypy.request.simpleCookie</title>
	90
	91	<para>This attribute is a SimpleCookie instance from the standard
	92	library's Cookie module which contains the incoming cookie
	93	values from the client.</para>
	94
	95	</section>
	96
	97	<section>
	98
	99	<title>cherrypy.request.rfile</title>
	100
	101	<para>This attribute is the input stream to the client, if
	102	applicable. See cherrypy.request.processRequestBody for more
	103	information.</para>
	104
	105	</section>
	106
	107	<section>
	108
	109	<title>cherrypy.request.body</title>
	110
	111	<para>This attribute is the request entity body, if applicable.
	112	See cherrypy.request.processRequestBody for more
	113	information.</para>
	114
	115	</section>
	116
	117	<section>
	118
	119	<title>cherrypy.request.processRequestBody</title>
	120
	121	<para>This attribute specifies whether or not the request's
	122	body (request.rfile, which is POST or PUT data) will be handled
	123	by CherryPy. If True (the default for POST and PUT requests),
	124	then request.rfile will be consumed by CherryPy (and unreadable
	125	after that). If the request Content-Type is
	126	"application/x-www-form-urlencoded", then the rfile
	127	will be parsed and placed into request.paramMap; otherwise, it
	128	will be available in request.body. If
	129	cherrypy.request.processRequestBody is False, then the rfile is
	130	not consumed, but will be readable by the exposed method.</para>
	131
	132	</section>
	133
	134	<section>
	135
	136	<title>cherrypy.request.method</title>
	137
	138	<para>This attribute is a string containing the HTTP request
	139	method, such as GET or POST.</para>
	140
	141	</section>
	142
	143	<section>
	144
	145	<title>cherrypy.request.protocol</title>
	146
	147	<para>This attribute is a string containing the HTTP protocol of
	148	the request in the form of HTTP/x.x</para>
	149
	150	</section>
	151
	152	<section>
	153
	154	<title>cherrypy.request.version</title>
	155
	156	<para>This attribute is a Version object which represents the
	157	HTTP protocol. It's the same os request.protocol, but allows
	158	easy comparisons like <code>if cherrypy.request.version >=
	159	"1.1": do_http_1_1_thing</code>.</para>
	160
	161	</section>
	162
	163	<section>
	164
	165	<title>cherrypy.request.queryString</title>
	166
	167	<para>This attribute is a string containing the query string of
	168	the request (the part of the URL following '?').</para>
	169
	170	</section>
	171
	172	<section>
	173
	174	<title>cherrypy.request.path</title>
	175
	176	<para>This attribute is a string containing the path of the
	177	resource the client requested.</para>
	178
	179	</section>
	180
	181	<section>
	182
	183	<title>cherrypy.request.paramMap</title>
	184
	185	<para>This attribute is a dictionary containing the query string
	186	and POST arguments of this request.</para>
	187
	188	</section>
	189
	190	<section>
	191
	192	<title>cherrypy.request.base</title>
	193
	194	<para>This attribute is a string containing the root URL of the
	195	server. By default, it is equal to
	196	request.scheme://request.headerMap['Host'].</para>
	197
	198	</section>
	199
	200	<section>
	201
	202	<title>cherrypy.request.browserUrl</title>
	203
	204	<para>This attribute is a string containing the URL the client
	205	requested. By default, it is equal to <code>request.base +
	206	request.path</code>, plus the querystring, if provided.</para>
	207
	208	</section>
	209
	210	<section>
	211
	212	<title>cherrypy.request.objectPath</title>
	213
	214	<para>This attribute is a string containing the path of the
	215	exposed method that will be called to handle this request. This
	216	is usually the same as cherrypy.request.path, but can be changed
	217	in a filter to change which method is actually called.</para>
	218
	219	</section>
	220
	221	<section>
	222
	223	<title>cherrypy.request.originalPath</title>
	224
	225	<para>This attribute is a string containing the original value of
	226	cherrypy.request.path, in case it is modified by a filter during
	227	the request.</para>
	228
	229	</section>
	230
	231	<section>
	232
	233	<title>cherrypy.request.originalParamMap</title>
	234
	235	<para>This attribute is a string containing the original value of
	236	cherrypy.request.paramMap, in case it is modified by a filter
	237	during the request.</para>
	238
	239	</section>
	240
	241	<section>
	242
	243	<title>cherrypy.request.scheme</title>
	244
	245	<para>This attribute is a string containing the URL scheme used
	246	in this request. It is either "http" or
	247	"https".</para>
	248
	249	</section>
	250
	251	</section>
	252
	253	<section id="cherrypyresponse">
	254
	255	<title>cherrypy.response</title>
	256
	257	<para>The cherrypy.response object contains response-related
	258	objects. Pretty lame description, but that's all it does;
	259	it's a big data dump. At the beginning of each HTTP request,
	260	the existing response object is destroyed, and a new one is
	261	created, (one response object for each thread). Therefore, CherryPy
	262	(and you yourself) can stick data into cherrypy.response and not
	263	worry about it conflicting with other requests.</para>
	264
	265	<section>
	266
	267	<title>cherrypy.response.headerMap</title>
	268
	269	<para>This attribute is a dictionary with automatically titled
	270	keys (e.g., "Content-Length"). It holds all outgoing
	271	HTTP headers to the client.</para>
	272
	273	</section>
	274
	275	<section>
	276
	277	<title>cherrypy.response.headers</title>
	278
	279	<para>This attribute is a list of (header, value) tuples.
	280	It's not available until the response has been finalized;
	281	it's really only there in the extremely rare cases when you
	282	need duplicate response headers. In general, you should use
	283	request.headerMap instead.</para>
	284
	285	</section>
	286
	287	<section>
	288
	289	<title>cherrypy.response.simpleCookie</title>
	290
	291	<para>This attribute is a SimpleCookie instance from the standard
	292	library's Cookie module. It contains the outgoing cookie
	293	values.</para>
	294
	295	</section>
	296
	297	<section>
	298
	299	<title>cherrypy.response.body</title>
	300
	301	<para>This attribute is originally just the return value of the
	302	exposed method, but by the end of the request it must be an
	303	iterable (usually a list or generator of strings) which will be
	304	the content of the HTTP response.</para>
	305
	306	</section>
	307
	308	<section>
	309
	310	<title>cherrypy.response.status</title>
	311
	312	<para>This attribute is a string containing the HTTP response
	313	code in the form "### Reason-Phrase", i.e. "200
	314	OK". You may also set it to an int, in which case the
	315	response finalization process will supply a Reason-Phrase for
	316	you.</para>
	317
	318	</section>
	319
	320	<section>
	321
	322	<title>cherrypy.response.version</title>
	323
	324	<para>This attribute is a Version object, representing the HTTP
	325	protocol version of the response. This is not necessarily the
	326	value that will be written in the response! Instead, it should be
	327	used to determine which features are
	328	<emphasis>available</emphasis> for the response. For example, an
	329	HTTP server may send an HTTP/1.1 response even though the client
	330	is known to only understand HTTP/1.0—the response.version will be
	331	set to Version("1.0") to inform you of this, so that
	332	you (and CherryPy) can restrict the response to HTTP/1.0 features
	333	only.</para>
	334
	335	</section>
	336
	337	</section>
	338
	339	<section id="cherrypyserver">
	340
	341	<title>cherrypy.server</title>
	342
	343	<section>
	344
	345	<title>cherrypy.server.start(initOnly=False,
	346	serverClass=_missing)</title>
	347
	348	<para>Start the CherryPy Server. Simple websites may call this
	349	without any arguments, to run the default server. If initOnly is
	350	False (the default), this function will block until
	351	KeyboardInterrupt or SystemExit is raised, so that the process
	352	will persist. When using one of the built-in HTTP servers, you
	353	should leave this set to False. You should only set it to True if
	354	you're running CherryPy as an extension to another HTTP
	355	server (for example, when using Apache and mod_python with
	356	CherryPy), in which case the foreign HTTP server should do its
	357	own process-management.</para>
	358
	359	<para>Use the serverClass argument to specify that you wish to
	360	use an HTTP server other than the default, built-in WSGIServer.
	361	If missing, config.get("server.class") will be checked
	362	for an alternate value; otherwise, the default is used. Possible
	363	alternate values (you may pass the class names as a string if you
	364	wish):</para>
	365
	366	<itemizedlist>
	367
	368	<listitem>
	369
	370	<para><code>cherrypy._cphttpserver.CherryHTTPServer</code>:
	371	this will load the old, single-threaded built-in HTTP server.
	372	This server is deprecated and will probably be removed in
	373	CherryPy 2.2.</para>
	374
	375	</listitem>
	376
	377	<listitem>
	378
	379	<para><code>cherrypy._cphttpserver.PooledThreadServer</code>:
	380	this will load the old, multi-threaded built-in HTTP server.
	381	This server is deprecated and will probably be removed in
	382	CherryPy 2.2.</para>
	383
	384	</listitem>
	385
	386	<listitem>
	387
	388	<para><code>cherrypy._cphttpserver.embedded_server</code>:
	389	use this to automatically select between the CherryHTTPServer
	390	and the PooledThreadServer based on the value of
	391	config.get("server.threadPool") and
	392	config.get("server.socketFile").</para>
	393
	394	</listitem>
	395
	396	<listitem>
	397
	398	<para><code>None</code>: this will not load any HTTP server.
	399	Note that this is not the default; the default (if
	400	serverClass is not given) is to load the WSGIServer.</para>
	401
	402	</listitem>
	403
	404	<listitem>
	405
	406	<para>Any other class (or dotted-name string): load a custom
	407	HTTP server.</para>
	408
	409	</listitem>
	410
	411	</itemizedlist>
	412
	413	<para>You <emphasis>must</emphasis> call this function from
	414	Python's main thread, and set initOnly to False, if you want
	415	CherryPy to shut down when KeyboardInterrupt or SystemExit are
	416	raised (including Ctrl-C). The only time you might want to do
	417	otherwise is if you run CherryPy as a Windows service, or as an
	418	extension to, say, mod_python, and even then, you might want to
	419	anyway.</para>
	420
	421	</section>
	422
	423	<section>
	424
	425	<title>cherrypy.server.blocking</title>
	426
	427	<para>If the "initOnly" argument to server.start is
	428	True, this will be False, and vice-versa.</para>
	429
	430	</section>
	431
	432	<section>
	433
	434	<title>cherrypy.server.httpserverclass</title>
	435
	436	<para>Whatever HTTP server class is set in server.start will be
	437	stuck in here.</para>
	438
	439	</section>
	440
	441	<section>
	442
	443	<title>cherrypy.server.httpserver</title>
	444
	445	<para>Whatever HTTP server class is set in server.start will be
	446	instantiated and stuck in here.</para>
	447
	448	</section>
	449
	450	<section>
	451
	452	<title>cherrypy.server.state</title>
	453
	454	<para>
	455
	456	One of three values, indicating the state of the server:
	457	<itemizedlist>
	458
	459	<listitem>
	460
	461	<para>STOPPED = 0: The server hasn't been started, and
	462	will not accept requests.</para>
	463
	464	</listitem>
	465
	466	<listitem>
	467
	468	<para>STARTING = None: The server is in the process of
	469	starting, or an error occured while trying to start the
	470	server.</para>
	471
	472	</listitem>
	473
	474	<listitem>
	475
	476	<para>STARTED = 1: The server has started (including an
	477	HTTP server if requested), and is ready to receive
	478	requests.</para>
	479
	480	</listitem>
	481
	482	</itemizedlist>
	483
	484	</para>
	485
	486	</section>
	487
	488	<section>
	489
	490	<title>cherrypy.server.ready</title>
	491
	492	<para>True if the server is ready to receive requests, false
	493	otherwise. Read-only.</para>
	494
	495	</section>
	496
	497	<section>
	498
	499	<title>cherrypy.server.wait()</title>
	500
	501	<para>Since server.start usually blocks, other threads need to be
	502	started before calling server.start; however, they often must
	503	wait for server.start to complete it's setup of the HTTP
	504	server. Use this function from other threads to make them wait
	505	for the HTTP server to be ready to receive requests.</para>
	506
	507	</section>
	508
	509	<section>
	510
	511	<title>cherrypy.server.start_with_callback(func, args=(),
	512	kwargs={}, serverClass=_missing)</title>
	513
	514	<para>Since server.start usually blocks, use this to easily run
	515	another function in a new thread. It starts the new thread and
	516	then runs server.start. The new thread automatically waits for
	517	the server to finish its startup procedure.</para>
	518
	519	</section>
	520