Changeset Navigation

← Previous Changeset
Next Changeset →

Changeset 880

Timestamp:

12/23/05 15:51:04

Author:

fumanchu

Message:

Doc update for #55/[879].

Files:

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

Legend:

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

trunk/docs/book/xml/apireference.xml

r865	r880
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.thread_data</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.headers</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.header_list</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 headers 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.params; 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.params</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.headers['Host'].</para>
197
198		</section>
199
200		<section>
201
202		<title>cherrypy.request.browser_url</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.params, 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.headers</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.header_list</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 header_list. In general, you should use
283		request.headers 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.thread_pool") and
392		config.get("server.socket_file").</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
521		<section>
522
523		<title>cherrypy.server.stop()</title>
524
525		<para>Stop the CherryPy Server. Well, "suspend" might
526		be a better term—this doesn't terminate the process.</para>
527
528		</section>
529
530		<section>
531
532		<title>cherrypy.server.interrupt</title>
533
534		<para>Usually None, set this to KeyboardInterrupt() or
535		SystemExit() to shut down the entire process. That is, the new
536		exception will be raised in the main thread.</para>
537
538		</section>
539
540		<section>
541
542		<title>cherrypy.server.restart()</title>
543
544		<para>Restart the CherryPy Server.</para>
545
546		</section>
547
548		<section>
549
550		<title>cherrypy.server.on_start_server_list</title>
551
552		<para>A list of functions that will be called when the server
553		starts.</para>
554
555		</section>
556
557		<section>
558
559		<title>cherrypy.server.on_stop_server_list</title>
560
561		<para>A list of functions that will be called when the server
562		stops.</para>
563
564		</section>
565
566		<section>
567
568		<title>cherrypy.server.on_start_thread_list</title>
569
570		<para>A list of functions that will be called when each request
571		thread is started. Note that such threads do not need to be
572		started or controlled by CherryPy; for example, when using
573		CherryPy with mod_python, Apache will start and stop the request
574		threads. Nevertheless, CherryPy will run the on_start_thread_list
575		functions upon the first request using each distinct
576		thread.</para>
577
578		</section>
579
580		<section>
581
582		<title>cherrypy.server.on_stop_thread_list</title>
583
584		<para>A list of functions that will be called when each request
585		thread is stopped.</para>
586
587		</section>
588
589		<section>
590
591		<title>cherrypy.server.request()</title>
592
593		<para>HTTP servers should call this function to create a new
594		Request and Response object. The return value is the Request
595		object; call its <code>run</code> method to have the CherryPy
596		core process the request data and populate the response.</para>
597
598		</section>
599
600		</section>
601
602		<section id="cherrypyconfig">
603
604		<title>cherrypy.config</title>
605
606		<section>
607
608		<title>cherrypy.config.get(key, defaultValue = None,
609		returnSection = False)</title>
610
611		<para>This function returns the configuration value for the given
612		key. The function checks if the setting is defined for the
613		current request path; it walks up the request path until the key
614		is found, or it returns the default value. If returnSection is
615		True, the function returns the configuration path where the key
616		is defined instead.</para>
617
618		</section>
619
620		<section>
621
622		<title>cherrypy.config.getAll(key)</title>
623
624		<para>The getAll function returns a list containing a (path,
625		value) tuple for all occurences of the key within the request
626		path. This function allows applications to inherit configuration
627		data defined for parent paths.</para>
628
629		</section>
630
631		<section>
632
633		<title>cherrypy.config.update(updateMap=None, file=None)</title>
634
635		<para>Function to update the configuration map. The
636		"updateMap" argument is a dictionary of the form
637		{'sectionPath' : { } }. The "file" argument
638		is the path to the configuration file.</para>
639
640		</section>
641
642		<section>
643
644		<title>cherrypy.config.environments</title>
645
646		<para>Dict containing config defaults for each named
647		server.environment.</para>
648
649		</section>
650
651		</section>
652
653		<section id="exceptions">
654
655		<title>cherrypy exceptions</title>
656
657		<section>
658
659		<title>cherrypy.HTTPError</title>
660
661		<para>This exception can be used to automatically send a response
662		using a http status code, with an appropriate error page.</para>
663
664		<section>
665
666		<title>cherrypy.NotFound</title>
667
668		<para>This exception is raised when CherryPy is unable to map a
669		requested path to an internal method. It's a subclass of
670		HTTPError (404).</para>
671
672		</section>
673
674		</section>
675
676		<section>
677
678		<title>cherrypy.HTTPRedirect</title>
679
680		<para>This exception will force a HTTP redirect.</para>
681
682		</section>
683
684		<section>
685
686		<title>cherrypy.InternalRedirect</title>
687
688		<para>This exception will redirect processing to another path
689		within the site (without informing the client).</para>
690
691		</section>
692
693		</section>
694
695		<section id="lib">
696
697		<title>The CherryPy library</title>
698
699		<section>
700
701		<title>cherrypy.lib.cptools</title>
702
703		<section>
704
705		<title>ExposeItems</title>
706
707		<para>Utility class that exposes a getitem-aware object. It
708		does not provide index() or default() methods, and it does not
709		expose the individual item objects - just the list or dict that
710		contains them. User-specific index() and default() methods can
711		be implemented by inheriting from this class.</para>
712
713		</section>
714
715		<section>
716
717		<title>PositionalParametersAware</title>
718
719		<para>Utility class that restores positional parameters
720		functionality that was found in 2.0.0-beta.</para>
721
722		</section>
723
724		<section>
725
726		<title>getAccept(headername)</title>
727
728		<para>Returns a list of AcceptValue objects from the specified
729		Accept-* header (or None if the header is not present). The
730		list is sorted so that the most-preferred values are first in
731		the list.</para>
732
733		<para>Each AcceptValue object has a <code>value</code>
734		attribute, a string which is the value itself. For example, if
735		<code>headername</code> is "Accept-Encoding", the
736		<code>value</code> attribute might be "gzip". It also
737		has a (read-only) <code>qvalue</code> attribute, a float
738		between 0 and 1 which specifies the client's preference
739		for the value; higher numbers are preferred. Finally, each
740		AcceptValue also has a <code>params</code> attribute, a dict;
741		for most headers, this dict will only possess the original
742		"q" value as a string.</para>
743
744		<para>If <code>headername</code> is "Accept" (the
745		default), then the params attribute may contain extra
746		parameters which further differentiate the value. In addition,
747		<code>params["q"]</code> may itself be an AcceptValue
748		object, with its own <code>params</code> dict. Don't ask
749		us why; ask the authors of the HTTP spec.</para>
750
751		</section>
752
753		<section>
754
755		<title>getRanges(content_length)</title>
756
757		<para>Returns a list of (start, stop) indices from a Range
758		request header. Returns None if no such header is provided in
759		the request. Each (start, stop) tuple will be composed of two
760		ints, which are suitable for use in a slicing operation. That
761		is, the header "Range: bytes=3-6", if applied against
762		a Python string, is requesting resource[3:7]. This function
763		will return the list [(3, 7)].</para>
764
765		</section>
766
767		<section>
768
769		<title>headers</title>
770
771		<para>A subclass of Python's builtin <code>dict</code>
772		class; CherryPy's default <code>request.headers</code>
773		and <code>response.headers</code> objects are instances of
774		this class. The keys are automatically titled
775		(<code>str(key).title()</code>) in order to provide
776		case-insensitive comparisons and avoid duplicates.</para>
777
778		</section>
779
780		<section>
781
782		<title>parseRequestLine(requestLine)</title>
783
784		<para>Returns (<code>method, path, querystring,
785		protocol</code>) from an HTTP requestLine. The default Request
786		processor calls this function.</para>
787
788		</section>
789
790		<section>
791
792		<title>parseQueryString(queryString,
793		keep_blank_values=True)</title>
794
795		<para>Returns a dict of <code>{'key':
796		'value'}</code> pairs from an HTTP
797		"key=value" query string. Also handles server-side
798		image map query strings. The default Request processor calls
799		this function.</para>
800
801		</section>
802
803		<section>
804
805		<title>paramsFromCGIForm(form)</title>
806
807		<para>Returns a dict of <code>{'key':
808		''value'}</code> pairs from a
809		<code>cgi.FieldStorage</code> object. The default Request
810		processor calls this function.</para>
811
812		</section>
813
814		<section>
815
816		<title>serveFile(path, contentType=None, disposition=None,
817		name=None)</title>
818
819		<para>Set status, headers, and body in order to serve the file
820		at the given path. The Content-Type header will be set to the
821		contentType arg, if provided. If not provided, the Content-Type
822		will be guessed by the extension of the file. If disposition is
823		not None, the Content-Disposition header will be set to
824		"<disposition>; filename=<name>". If name
825		is None, it will be set to the basename of path. If disposition
826		is None, no Content-Disposition header will be written.</para>
827
828		</section>
829
830		</section>
831
832		<section>
833
834		<title>cherrypy.lib.covercp</title>
835
836		<para>This module both provides code-coverage tools, and may also
837		be run as a script. To use this module, or the coverage tools in
838		the test suite, you need to download 'coverage.py',
839		either Gareth Rees' <ulink url="???">original
840		implementation</ulink> or Ned Batchelder's
841		<ulink url="http://www.nedbatchelder.com/code/modules/coverage.html">
842		enhanced version</ulink>.</para>
843
844		<para>Set cherrypy.codecoverage to True to turn on coverage
845		tracing. Then, use the covercp.serve() function to browse the
846		results in a web browser. If you run this module as a script
847		(i.e., from the command line), it will call serve() for
848		you.</para>
849
850		</section>
851
852		<section>
853
854		<title>cherrypy.lib.profiler</title>
855
856		<para>You can profile any of your page handlers (exposed methods)
857		as follows:</para>
858
859		<example>
860
861		<title>Profiling example</title>
862
863		<programlisting><code>from cherrypy.lib import profile
	1	<?xml version="1.0" encoding="UTF-8"?>
	2	<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5b1//EN"
	3	"http://www.oasis-open.org/docbook/xml/4.5b1/docbookx.dtd">
	4	<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
	5	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="apireference">
	6	<title>API reference</title>
	7	<section id="cherrypy">
	8	<title>cherrypy.thread_data</title>
	9	<para>This attribute holds attributes that map to this thread only.</para>
	10	</section>
	11	<section id="cherrypyrequest">
	12	<title>cherrypy.request</title>
	13	<para>The cherrypy.request object contains request-related objects. Pretty lame description,
	14	but that's all it does; it's a big data dump. At the beginning of each HTTP request, the
	15	existing request object is destroyed, and a new one is created, (one request object for each
	16	thread). Therefore, CherryPy (and you yourself) can stick data into cherrypy.request and not
	17	worry about it conflicting with other requests.</para>
	18	<section>
	19	<title>cherrypy.request.remoteAddr</title>
	20	<para>This attribute is a string containing the IP address of the client. It will be an
	21	empty string if it is not available.</para>
	22	</section>
	23	<section>
	24	<title>cherrypy.request.remotePort</title>
	25	<para>This attribute is an int containing the TCP port number of the client. It will be
	26	-1 if it is not available.</para>
	27	</section>
	28	<section>
	29	<title>cherrypy.request.remoteHost</title>
	30	<para>This attribute is a string containing the remote hostname of the client.</para>
	31	</section>
	32	<section>
	33	<title>cherrypy.request.headers</title>
	34	<para>This attribute is a dictionary containing the received HTTP headers, with
	35	automatically titled keys (e.g., "Content-Type"). As it's a dictionary, no duplicates are
	36	allowed.</para>
	37	</section>
	38	<section>
	39	<title>cherrypy.request.header_list</title>
	40	<para>This attribute is a list of (header, value) tuples containing the received HTTP
	41	headers. In general, you probably want to use headers instead; this is only here in case
	42	you need to inspect duplicates in the request headers.</para>
	43	</section>
	44	<section>
	45	<title>cherrypy.request.requestLine</title>
	46	<para>This attribute is a string containing the first line of the raw HTTP request; for
	47	example, "GET /path/page HTTP/1.1".</para>
	48	</section>
	49	<section>
	50	<title>cherrypy.request.simpleCookie</title>
	51	<para>This attribute is a SimpleCookie instance from the standard library's Cookie module
	52	which contains the incoming cookie values from the client.</para>
	53	</section>
	54	<section>
	55	<title>cherrypy.request.rfile</title>
	56	<para>This attribute is the input stream to the client, if applicable. See
	57	cherrypy.request.processRequestBody for more information.</para>
	58	</section>
	59	<section>
	60	<title>cherrypy.request.body</title>
	61	<para>This attribute is the request entity body, if applicable. See
	62	cherrypy.request.processRequestBody for more information.</para>
	63	</section>
	64	<section>
	65	<title>cherrypy.request.processRequestBody</title>
	66	<para>This attribute specifies whether or not the request's body (request.rfile, which is
	67	POST or PUT data) will be handled by CherryPy. If True (the default for POST and PUT
	68	requests), then request.rfile will be consumed by CherryPy (and unreadable after that).
	69	If the request Content-Type is "application/x-www-form-urlencoded", then the rfile will
	70	be parsed and placed into request.params; otherwise, it will be available in
	71	request.body. If cherrypy.request.processRequestBody is False, then the rfile is not
	72	consumed, but will be readable by the exposed method.</para>
	73	</section>
	74	<section>
	75	<title>cherrypy.request.method</title>
	76	<para>This attribute is a string containing the HTTP request method, such as GET or
	77	POST.</para>
	78	</section>
	79	<section>
	80	<title>cherrypy.request.protocol</title>
	81	<para>This attribute is a string containing the HTTP protocol of the request in the form
	82	of HTTP/x.x</para>
	83	</section>
	84	<section>
	85	<title>cherrypy.request.version</title>
	86	<para>This attribute is a Version object which represents the HTTP protocol. It's the
	87	same os request.protocol, but allows easy comparisons like <code>if
	88	cherrypy.request.version >= "1.1": do_http_1_1_thing</code>.</para>
	89	</section>
	90	<section>
	91	<title>cherrypy.request.queryString</title>
	92	<para>This attribute is a string containing the query string of the request (the part of
	93	the URL following '?').</para>
	94	</section>
	95	<section>
	96	<title>cherrypy.request.path</title>
	97	<para>This attribute is a string containing the path of the resource the client
	98	requested.</para>
	99	</section>
	100	<section>
	101	<title>cherrypy.request.params</title>
	102	<para>This attribute is a dictionary containing the query string and POST arguments of
	103	this request.</para>
	104	</section>
	105	<section>
	106	<title>cherrypy.request.base</title>
	107	<para>This attribute is a string containing the root URL of the server. By default, it is
	108	equal to request.scheme://request.headers['Host'].</para>
	109	</section>
	110	<section>
	111	<title>cherrypy.request.browser_url</title>
	112	<para>This attribute is a string containing the URL the client requested. By default, it
	113	is equal to <code>request.base + request.path</code>, plus the querystring, if
	114	provided.</para>
	115	</section>
	116	<section>
	117	<title>cherrypy.request.objectPath</title>
	118	<para>This attribute is a string containing the path of the exposed method that will be
	119	called to handle this request. This is usually the same as cherrypy.request.path, but can
	120	be changed in a filter to change which method is actually called.</para>
	121	</section>
	122	<section>
	123	<title>cherrypy.request.originalPath</title>
	124	<para>This attribute is a string containing the original value of cherrypy.request.path,
	125	in case it is modified by a filter during the request.</para>
	126	</section>
	127	<section>
	128	<title>cherrypy.request.originalParamMap</title>
	129	<para>This attribute is a string containing the original value of
	130	cherrypy.request.params, in case it is modified by a filter during the request.</para>
	131	</section>
	132	<section>
	133	<title>cherrypy.request.scheme</title>
	134	<para>This attribute is a string containing the URL scheme used in this request. It is
	135	either "http" or "https".</para>
	136	</section>
	137	</section>
	138	<section id="cherrypyresponse">
	139	<title>cherrypy.response</title>
	140	<para>The cherrypy.response object contains response-related objects. Pretty lame
	141	description, but that's all it does; it's a big data dump. At the beginning of each HTTP
	142	request, the existing response object is destroyed, and a new one is created, (one response
	143	object for each thread). Therefore, CherryPy (and you yourself) can stick data into
	144	cherrypy.response and not worry about it conflicting with other requests.</para>
	145	<section>
	146	<title>cherrypy.response.headers</title>
	147	<para>This attribute is a dictionary with automatically titled keys (e.g.,
	148	"Content-Length"). It holds all outgoing HTTP headers to the client.</para>
	149	</section>
	150	<section>
	151	<title>cherrypy.response.header_list</title>
	152	<para>This attribute is a list of (header, value) tuples. It's not available until the
	153	response has been finalized; it's really only there in the extremely rare cases when you
	154	need duplicate response header_list. In general, you should use request.headers
	155	instead.</para>
	156	</section>
	157	<section>
	158	<title>cherrypy.response.simpleCookie</title>
	159	<para>This attribute is a SimpleCookie instance from the standard library's Cookie
	160	module. It contains the outgoing cookie values.</para>
	161	</section>
	162	<section>
	163	<title>cherrypy.response.body</title>
	164	<para>This attribute is originally just the return value of the exposed method, but by
	165	the end of the request it must be an iterable (usually a list or generator of strings)
	166	which will be the content of the HTTP response.</para>
	167	</section>
	168	<section>
	169	<title>cherrypy.response.status</title>
	170	<para>This attribute is a string containing the HTTP response code in the form "###
	171	Reason-Phrase", i.e. "200 OK". You may also set it to an int, in which case the response
	172	finalization process will supply a Reason-Phrase for you.</para>
	173	</section>
	174	<section>
	175	<title>cherrypy.response.version</title>
	176	<para>This attribute is a Version object, representing the HTTP protocol version of the
	177	response. This is not necessarily the value that will be written in the response!
	178	Instead, it should be used to determine which features are <emphasis>available</emphasis>
	179	for the response. For example, an HTTP server may send an HTTP/1.1 response even though
	180	the client is known to only understand HTTP/1.0—the response.version will be set to
	181	Version("1.0") to inform you of this, so that you (and CherryPy) can restrict the
	182	response to HTTP/1.0 features only.</para>
	183	</section>
	184	</section>
	185	<section id="cherrypyserver">
	186	<title>cherrypy.server</title>
	187	<section>
	188	<title>cherrypy.server.start(initOnly=False, serverClass=_missing)</title>
	189	<para>Start the CherryPy Server. Simple websites may call this without any arguments, to
	190	run the default server. If initOnly is False (the default), this function will block
	191	until KeyboardInterrupt or SystemExit is raised, so that the process will persist. When
	192	using one of the built-in HTTP servers, you should leave this set to False. You should
	193	only set it to True if you're running CherryPy as an extension to another HTTP server
	194	(for example, when using Apache and mod_python with CherryPy), in which case the foreign
	195	HTTP server should do its own process-management.</para>
	196	<para>Use the serverClass argument to specify that you wish to use an HTTP server other
	197	than the default, built-in WSGIServer. If missing, config.get("server.class") will be
	198	checked for an alternate value; otherwise, the default is used. Possible alternate values
	199	(you may pass the class names as a string if you wish):</para>
	200	<itemizedlist>
	201	<listitem>
	202	<para><code>cherrypy._cphttpserver.CherryHTTPServer</code>: this will load the
	203	old, single-threaded built-in HTTP server. This server is deprecated and will
	204	probably be removed in CherryPy 2.2.</para>
	205	</listitem>
	206	<listitem>
	207	<para><code>cherrypy._cphttpserver.PooledThreadServer</code>: this will load the
	208	old, multi-threaded built-in HTTP server. This server is deprecated and will
	209	probably be removed in CherryPy 2.2.</para>
	210	</listitem>
	211	<listitem>
	212	<para><code>cherrypy._cphttpserver.embedded_server</code>: use this to
	213	automatically select between the CherryHTTPServer and the PooledThreadServer
	214	based on the value of config.get("server.thread_pool") and
	215	config.get("server.socket_file").</para>
	216	</listitem>
	217	<listitem>
	218	<para><code>None</code>: this will not load any HTTP server. Note that this is
	219	not the default; the default (if serverClass is not given) is to load the
	220	WSGIServer.</para>
	221	</listitem>
	222	<listitem>
	223	<para>Any other class (or dotted-name string): load a custom HTTP server.</para>
	224	</listitem>
	225	</itemizedlist>
	226	<para>You <emphasis>must</emphasis> call this function from Python's main thread, and set
	227	initOnly to False, if you want CherryPy to shut down when KeyboardInterrupt or SystemExit
	228	are raised (including Ctrl-C). The only time you might want to do otherwise is if you run
	229	CherryPy as a Windows service, or as an extension to, say, mod_python, and even then, you
	230	might want to anyway.</para>
	231	</section>
	232	<