1
2 import Cookie
3 import os
4 import sys
5 import time
6 import types
7
8 import cherrypy
9 from cherrypy import _cpcgifs, _cpconfig
10 from cherrypy._cperror import format_exc, bare_error
11 from cherrypy.lib import http
12
13
15 """A callback and its metadata: failsafe, priority, and kwargs."""
16
17 __metaclass__ = cherrypy._AttributeDocstrings
18
19 callback = None
20 callback__doc = """
21 The bare callable that this Hook object is wrapping, which will
22 be called when the Hook is called."""
23
24 failsafe = False
25 failsafe__doc = """
26 If True, the callback is guaranteed to run even if other callbacks
27 from the same call point raise exceptions."""
28
29 priority = 50
30 priority__doc = """
31 Defines the order of execution for a list of Hooks. Priority numbers
32 should be limited to the closed interval [0, 100], but values outside
33 this range are acceptable, as are fractional values."""
34
35 kwargs = {}
36 kwargs__doc = """
37 A set of keyword arguments that will be passed to the
38 callable on each call."""
39
40 - def __init__(self, callback, failsafe=None, priority=None, **kwargs):
52
55
57 """Run self.callback(**self.kwargs)."""
58 return self.callback(**self.kwargs)
59
60
62 """A map of call points to lists of callbacks (Hook objects)."""
63
65 d = dict.__new__(cls)
66 for p in points or []:
67 d[p] = []
68 return d
69
72
73 - def attach(self, point, callback, failsafe=None, priority=None, **kwargs):
76
77 - def run(self, point):
101
103 newmap = self.__class__()
104
105
106 for k, v in self.iteritems():
107 newmap[k] = v[:]
108 return newmap
109 copy = __copy__
110
112 cls = self.__class__
113 return "%s.%s(points=%r)" % (cls.__module__, cls.__name__, self.keys())
114
115
116
117
119 """Attach bare hooks declared in config."""
120
121
122
123 hookpoint = k.split(".", 1)[0]
124 if isinstance(v, basestring):
125 v = cherrypy.lib.attributes(v)
126 if not isinstance(v, Hook):
127 v = Hook(v)
128 cherrypy.request.hooks[hookpoint].append(v)
129
131 """Attach request attributes declared in config."""
132 setattr(cherrypy.request, k, v)
133
135 """Attach response attributes declared in config."""
136 setattr(cherrypy.response, k, v)
137
139 """Attach error pages declared in config."""
140 cherrypy.request.error_page[int(k)] = v
141
142
143 hookpoints = ['on_start_resource', 'before_request_body',
144 'before_handler', 'before_finalize',
145 'on_end_resource', 'on_end_request',
146 'before_error_response', 'after_error_response']
147
148
150 """An HTTP request.
151
152 This object represents the metadata of an HTTP request message;
153 that is, it contains attributes which describe the environment
154 in which the request URL, headers, and body were sent (if you
155 want tools to interpret the headers and body, those are elsewhere,
156 mostly in Tools). This 'metadata' consists of socket data,
157 transport characteristics, and the Request-Line. This object
158 also contains data regarding the configuration in effect for
159 the given URL, and the execution plan for generating a response.
160 """
161
162 __metaclass__ = cherrypy._AttributeDocstrings
163
164 prev = None
165 prev__doc = """
166 The previous Request object (if any). This should be None
167 unless we are processing an InternalRedirect."""
168
169
170 local = http.Host("localhost", 80)
171 local__doc = \
172 "An http.Host(ip, port, hostname) object for the server socket."
173
174 remote = http.Host("localhost", 1111)
175 remote__doc = \
176 "An http.Host(ip, port, hostname) object for the client socket."
177
178 scheme = "http"
179 scheme__doc = """
180 The protocol used between client and server. In most cases,
181 this will be either 'http' or 'https'."""
182
183 server_protocol = "HTTP/1.1"
184 server_protocol__doc = """
185 The HTTP version for which the HTTP server is at least
186 conditionally compliant."""
187
188 base = ""
189 base__doc = """The (scheme://host) portion of the requested URL."""
190
191
192 request_line = ""
193 request_line__doc = """
194 The complete Request-Line received from the client. This is a
195 single string consisting of the request method, URI, and protocol
196 version (joined by spaces). Any final CRLF is removed."""
197
198 method = "GET"
199 method__doc = """
200 Indicates the HTTP method to be performed on the resource identified
201 by the Request-URI. Common methods include GET, HEAD, POST, PUT, and
202 DELETE. CherryPy allows any extension method; however, various HTTP
203 servers and gateways may restrict the set of allowable methods.
204 CherryPy applications SHOULD restrict the set (on a per-URI basis)."""
205
206 query_string = ""
207 query_string__doc = """
208 The query component of the Request-URI, a string of information to be
209 interpreted by the resource. The query portion of a URI follows the
210 path component, and is separated by a '?'. For example, the URI
211 'http://www.cherrypy.org/wiki?a=3&b=4' has the query component,
212 'a=3&b=4'."""
213
214 protocol = (1, 1)
215 protocol__doc = """The HTTP protocol version corresponding to the set
216 of features which should be allowed in the response. If BOTH
217 the client's request message AND the server's level of HTTP
218 compliance is HTTP/1.1, this attribute will be the tuple (1, 1).
219 If either is 1.0, this attribute will be the tuple (1, 0).
220 Lower HTTP protocol versions are not explicitly supported."""
221
222 params = {}
223 params__doc = """
224 A dict which combines query string (GET) and request entity (POST)
225 variables. This is populated in two stages: GET params are added
226 before the 'on_start_resource' hook, and POST params are added
227 between the 'before_request_body' and 'before_handler' hooks."""
228
229
230 header_list = []
231 header_list__doc = """
232 A list of the HTTP request headers as (name, value) tuples.
233 In general, you should use request.headers (a dict) instead."""
234
235 headers = http.HeaderMap()
236 headers__doc = """
237 A dict-like object containing the request headers. Keys are header
238 names (in Title-Case format); however, you may get and set them in
239 a case-insensitive manner. That is, headers['Content-Type'] and
240 headers['content-type'] refer to the same value. Values are header
241 values (decoded according to RFC 2047 if necessary). See also:
242 http.HeaderMap, http.HeaderElement."""
243
244 cookie = Cookie.SimpleCookie()
245 cookie__doc = """See help(Cookie)."""
246
247 rfile = None
248 rfile__doc = """
249 If the request included an entity (body), it will be available
250 as a stream in this attribute. However, the rfile will normally
251 be read for you between the 'before_request_body' hook and the
252 'before_handler' hook, and the resulting string is placed into
253 either request.params or the request.body attribute.
254
255 You may disable the automatic consumption of the rfile by setting
256 request.process_request_body to False, either in config for the desired
257 path, or in an 'on_start_resource' or 'before_request_body' hook.
258
259 WARNING: In almost every case, you should not attempt to read from the
260 rfile stream after CherryPy's automatic mechanism has read it. If you
261 turn off the automatic parsing of rfile, you should read exactly the
262 number of bytes specified in request.headers['Content-Length'].
263 Ignoring either of these warnings may result in a hung request thread
264 or in corruption of the next (pipelined) request.
265 """
266
267 process_request_body = True
268 process_request_body__doc = """
269 If True, the rfile (if any) is automatically read and parsed,
270 and the result placed into request.params or request.body."""
271
272 methods_with_bodies = ("POST", "PUT")
273 methods_with_bodies__doc = """
274 A sequence of HTTP methods for which CherryPy will automatically
275 attempt to read a body from the rfile."""
276
277 body = None
278 body__doc = """
279 If the request Content-Type is 'application/x-www-form-urlencoded'
280 or multipart, this will be None. Otherwise, this will contain the
281 request entity body as a string; this value is set between the
282 'before_request_body' and 'before_handler' hooks (assuming that
283 process_request_body is True)."""
284
285
286 dispatch = cherrypy.dispatch.Dispatcher()
287 dispatch__doc = """
288 The object which looks up the 'page handler' callable and collects
289 config for the current request based on the path_info, other
290 request attributes, and the application architecture. The core
291 calls the dispatcher as early as possible, passing it a 'path_info'
292 argument.
293
294 The default dispatcher discovers the page handler by matching path_info
295 to a hierarchical arrangement of objects, starting at request.app.root.
296 See help(cherrypy.dispatch) for more information."""
297
298 script_name = ""
299 script_name__doc = """
300 The 'mount point' of the application which is handling this request."""
301
302 path_info = "/"
303 path_info__doc = """
304 The 'relative path' portion of the Request-URI. This is relative
305 to the script_name ('mount point') of the application which is
306 handling this request."""
307
308 login = None
309 login__doc = """
310 When authentication is used during the request processing this is
311 set to 'False' if it failed and to the 'username' value if it succeeded.
312 The default 'None' implies that no authentication happened."""
313
314 app = None
315 app__doc = \
316 """The cherrypy.Application object which is handling this request."""
317
318 handler = None
319 handler__doc = """
320 The function, method, or other callable which CherryPy will call to
321 produce the response. The discovery of the handler and the arguments
322 it will receive are determined by the request.dispatch object.
323 By default, the handler is discovered by walking a tree of objects
324 starting at request.app.root, and is then passed all HTTP params
325 (from the query string and POST body) as keyword arguments."""
326
327 toolmaps = {}
328 toolmaps__doc = """
329 A nested dict of all Toolboxes and Tools in effect for this request,
330 of the form: {Toolbox.namespace: {Tool.name: config dict}}."""
331
332 config = None
333 config__doc = """
334 A flat dict of all configuration entries which apply to the
335 current request. These entries are collected from global config,
336 application config (based on request.path_info), and from handler
337 config (exactly how is governed by the request.dispatch object in
338 effect for this request; by default, handler config can be attached
339 anywhere in the tree between request.app.root and the final handler,
340 and inherits downward)."""
341
342 is_index = None
343 is_index__doc = """
344 This will be True if the current request is mapped to an 'index'
345 resource handler (also, a 'default' handler if path_info ends with
346 a slash). The value may be used to automatically redirect the
347 user-agent to a 'more canonical' URL which either adds or removes
348 the trailing slash. See cherrypy.tools.trailing_slash."""
349
350 hooks = HookMap(hookpoints)
351 hooks__doc = """
352 A HookMap (dict-like object) of the form: {hookpoint: [hook, ...]}.
353 Each key is a str naming the hook point, and each value is a list
354 of hooks which will be called at that hook point during this request.
355 The list of hooks is generally populated as early as possible (mostly
356 from Tools specified in config), but may be extended at any time.
357 See also: _cprequest.Hook, _cprequest.HookMap, and cherrypy.tools."""
358
359 error_response = cherrypy.HTTPError(500).set_response
360 error_response__doc = """
361 The no-arg callable which will handle unexpected, untrapped errors
362 during request processing. This is not used for expected exceptions
363 (like NotFound, HTTPError, or HTTPRedirect) which are raised in
364 response to expected conditions (those should be customized either
365 via request.error_page or by overriding HTTPError.set_response).
366 By default, error_response uses HTTPError(500) to return a generic
367 error response to the user-agent."""
368
369 error_page = {}
370 error_page__doc = """
371 A dict of {error code: response filename} pairs. The named response
372 files should be Python string-formatting templates, and can expect by
373 default to receive the format values with the mapping keys 'status',
374 'message', 'traceback', and 'version'. The set of format mappings
375 can be extended by overriding HTTPError.set_response."""
376
377 show_tracebacks = True
378 show_tracebacks__doc = """
379 If True, unexpected errors encountered during request processing will
380 include a traceback in the response body."""
381
382 throws = (KeyboardInterrupt, SystemExit, cherrypy.InternalRedirect)
383 throws__doc = \
384 """The sequence of exceptions which Request.run does not trap."""
385
386 throw_errors = False
387 throw_errors__doc = """
388 If True, Request.run will not trap any errors (except HTTPRedirect and
389 HTTPError, which are more properly called 'exceptions', not errors)."""
390
391 namespaces = _cpconfig.NamespaceSet(
392 **{"hooks": hooks_namespace,
393 "request": request_namespace,
394 "response": response_namespace,
395 "error_page": error_page_namespace,
396
397 })
398
399 - def __init__(self, local_host, remote_host, scheme="http",
400 server_protocol="HTTP/1.1"):
401 """Populate a new Request object.
402
403 local_host should be an http.Host object with the server info.
404 remote_host should be an http.Host object with the client info.
405 scheme should be a string, either "http" or "https".
406 """
407 self.local = local_host
408 self.remote = remote_host
409 self.scheme = scheme
410 self.server_protocol = server_protocol
411
412 self.closed = False
413
414
415 self.error_page = self.error_page.copy()
416
417
418 self.namespaces = self.namespaces.copy()
419
421 """Run cleanup code and remove self from globals. (Core)"""
422 if not self.closed:
423 self.closed = True
424 self.hooks.run('on_end_request')
425
426 - def run(self, method, path, query_string, req_protocol, headers, rfile):
427 """Process the Request. (Core)
428
429 method, path, query_string, and req_protocol should be pulled directly
430 from the Request-Line (e.g. "GET /path?key=val HTTP/1.0").
431 path should be %XX-unquoted, but query_string should not be.
432 headers should be a list of (name, value) tuples.
433 rfile should be a file-like object containing the HTTP request entity.
434
435 When run() is done, the returned object should have 3 attributes:
436 status, e.g. "200 OK"
437 header_list, a list of (name, value) tuples
438 body, an iterable yielding strings
439
440 Consumer code (HTTP servers) should then access these response
441 attributes to build the outbound stream.
442
443 """
444
445 try:
446 self.error_response = cherrypy.HTTPError(500).set_response
447
448 self.method = method
449 path = path or "/"
450 self.query_string = query_string or ''
451
452
453
454
455
456
457
458
459
460
461
462
463
464 rp = int(req_protocol[5]), int(req_protocol[7])
465 sp = int(self.server_protocol[5]), int(self.server_protocol[7])
466 self.protocol = min(rp, sp)
467
468
469 url = path
470 if query_string:
471 url += '?' + query_string
472 self.request_line = '%s %s %s' % (method, url, req_protocol)
473
474 self.header_list = list(headers)
475 self.rfile = rfile
476 self.headers = http.HeaderMap()
477 self.cookie = Cookie.SimpleCookie()
478 self.handler = None
479
480
481
482 self.script_name = self.app.script_name
483 self.path_info = pi = path[len(self.script_name.rstrip("/")):]
484
485 self.respond(pi)
486
487 except self.throws:
488 raise
489 except:
490 if self.throw_errors:
491 raise
492 else:
493
494
495 cherrypy.log(traceback=True)
496 if self.show_tracebacks:
497 body = format_exc()
498 else:
499 body = ""
500 r = bare_error(body)
501 response = cherrypy.response
502 response.status, response.header_list, response.body = r
503
504 if self.method == "HEAD":
505
506 cherrypy.response.body = []
507
508 cherrypy.log.access()
509
510 if cherrypy.response.timed_out:
511 raise cherrypy.TimeoutError()
512
513 return cherrypy.response
514
566
568 """Parse HTTP header data into Python structures. (Core)"""
569 self.params = http.parse_query_string(self.query_string)
570
571
572 headers = self.headers
573 for name, value in self.header_list:
574
575
576 name = name.title()
577 value = value.strip()
578
579
580
581
582 if "=?" in value:
583 dict.__setitem__(headers, name, http.decode_TEXT(value))
584 else:
585 dict.__setitem__(headers, name, value)
586
587
588
589 if name == 'Cookie':
590 self.cookie.load(value)
591
592 if not dict.__contains__(headers, 'Host'):
593
594
595
596 if self.protocol >= (1, 1):
597 msg = "HTTP/1.1 requires a 'Host' request header."
598 raise cherrypy.HTTPError(400, msg)
599 host = dict.get(headers, 'Host')
600 if not host:
601 host = self.local.name or self.local.ip
602 self.base = "%s://%s" % (self.scheme, host)
603
605 """Call a dispatcher (which sets self.handler and .config). (Core)"""
606 dispatch = self.dispatch
607
608
609
610 trail = path
611 while trail:
612 nodeconf = self.app.config.get(trail, {})
613
614 d = nodeconf.get("request.dispatch")
615 if d:
616 dispatch = d
617 break
618
619 lastslash = trail.rfind("/")
620 if lastslash == -1:
621 break
622 elif lastslash == 0 and trail != "/":
623 trail = "/"
624 else:
625 trail = trail[:lastslash]
626
627
628 dispatch(path)
629
630 - def process_body(self):
631 """Convert request.rfile into request.params (or request.body). (Core)"""
632 if not self.headers.get("Content-Length", ""):
633
634
635
636
637
638
639
640
641
642 return
643
644
645 methenv = {'REQUEST_METHOD': "POST"}
646 try:
647 forms = _cpcgifs.FieldStorage(fp=self.rfile,
648 headers=self.headers,
649 environ=methenv,
650 keep_blank_values=1)
651 except http.MaxSizeExceeded:
652
653 raise cherrypy.HTTPError(413)
654
655
656
657
658
659 if forms.file:
660
661 self.body = forms.file
662 else:
663 self.params.update(http.params_from_CGI_form(forms))
664
676
677
679 """Yield the given input (a file object) in chunks (default 64k). (Core)"""
680 chunk = input.read(chunkSize)
681 while chunk:
682 yield chunk
683 chunk = input.read(chunkSize)
684 input.close()
685
686
688 """The body of the HTTP response (the response entity)."""
689
690 - def __get__(self, obj, objclass=None):
691 if obj is None:
692
693 return self
694 else:
695 return obj._body
696
697 - def __set__(self, obj, value):
698
699 if isinstance(value, basestring):
700
701
702
703 if value:
704 value = [value]
705 else:
706
707 value = []
708 elif isinstance(value, types.FileType):
709 value = file_generator(value)
710 elif value is None:
711 value = []
712 obj._body = value
713
714
716 """An HTTP Response, including status, headers, and body.
717
718 Application developers should use Response.headers (a dict) to
719 set or modify HTTP response headers. When the response is finalized,
720 Response.headers is transformed into Response.header_list as
721 (key, value) tuples.
722 """
723
724 __metaclass__ = cherrypy._AttributeDocstrings
725
726
727 status = ""
728 status__doc = """The HTTP Status-Code and Reason-Phrase."""
729
730 header_list = []
731 header_list__doc = """
732 A list of the HTTP response headers as (name, value) tuples.
733 In general, you should use response.headers (a dict) instead."""
734
735 headers = http.HeaderMap()
736 headers__doc = """
737 A dict-like object containing the response headers. Keys are header
738 names (in Title-Case format); however, you may get and set them in
739 a case-insensitive manner. That is, headers['Content-Type'] and
740 headers['content-type'] refer to the same value. Values are header
741 values (decoded according to RFC 2047 if necessary). See also:
742 http.HeaderMap, http.HeaderElement."""
743
744 cookie = Cookie.SimpleCookie()
745 cookie__doc = """See help(Cookie)."""
746
747 body = Body()
748 body__doc = """The body (entity) of the HTTP response."""
749
750 time = None
751 time__doc = """The value of time.time() when created. Use in HTTP dates."""
752
753 timeout = 300
754 timeout__doc = """Seconds after which the response will be aborted."""
755
756 timed_out = False
757 timed_out__doc = """
758 Flag to indicate the response should be aborted, because it has
759 exceeded its timeout."""
760
761 stream = False
762 stream__doc = """If False, buffer the response body."""
763
779
780 - def collapse_body(self):
781 """Iterate over self.body, replacing it with and returning the result."""
782 newbody = ''.join([chunk for chunk in self.body])
783 self.body = newbody
784 return newbody
785
787 """Transform headers (and cookies) into self.header_list. (Core)"""
788 try:
789 code, reason, _ = http.valid_status(self.status)
790 except ValueError, x:
791 raise cherrypy.HTTPError(500, x.args[0])
792
793 self.status = "%s %s" % (code, reason)
794
795 headers = self.headers
796 if self.stream:
797 if dict.get(headers, 'Content-Length') is None:
798 dict.pop(headers, 'Content-Length', None)
799 elif code < 200 or code in (204, 205, 304):
800
801
802
803 dict.pop(headers, 'Content-Length', None)
804 self.body = ""
805 else:
806
807
808 if dict.get(headers, 'Content-Length') is None:
809 content = self.collapse_body()
810 dict.__setitem__(headers, 'Content-Length', len(content))
811
812
813 self.header_list = h = headers.output(cherrypy.request.protocol)
814
815 cookie = self.cookie.output()
816 if cookie:
817 for line in cookie.split("\n"):
818 name, value = line.split(": ", 1)
819 h.append((name, value))
820
822 """If now > self.time + self.timeout, set self.timed_out.
823
824 This purposefully sets a flag, rather than raising an error,
825 so that a monitor thread can interrupt the Response thread.
826 """
827 if time.time() > self.time + self.timeout:
828 self.timed_out = True
829