AppPkg/Applications/Python/Python-2.7.2/Lib/wsgiref/handlers.py

   1 """Base classes for server/gateway implementations"""
   2
   3 from types import StringType
   4 from util import FileWrapper, guess_scheme, is_hop_by_hop
   5 from headers import Headers
   6
   7 import sys, os, time
   8
   9 __all__ = ['BaseHandler', 'SimpleHandler', 'BaseCGIHandler', 'CGIHandler']
  10
  11 try:
  12     dict
  13 except NameError:
  14     def dict(items):
  15         d = {}
  16         for k,v in items:
  17             d[k] = v
  18         return d
  19
  20 # Uncomment for 2.2 compatibility.
  21 #try:
  22 #    True
  23 #    False
  24 #except NameError:
  25 #    True = not None
  26 #    False = not True
  27
  28
  29 # Weekday and month names for HTTP date/time formatting; always English!
  30 _weekdayname = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
  31 _monthname = [None, # Dummy so we can use 1-based month numbers
  32               "Jan", "Feb", "Mar", "Apr", "May", "Jun",
  33               "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
  34
  35 def format_date_time(timestamp):
  36     year, month, day, hh, mm, ss, wd, y, z = time.gmtime(timestamp)
  37     return "%s, %02d %3s %4d %02d:%02d:%02d GMT" % (
  38         _weekdayname[wd], day, _monthname[month], year, hh, mm, ss
  39     )
  40
  41
  42 class BaseHandler:
  43     """Manage the invocation of a WSGI application"""
  44
  45     # Configuration parameters; can override per-subclass or per-instance
  46     wsgi_version = (1,0)
  47     wsgi_multithread = True
  48     wsgi_multiprocess = True
  49     wsgi_run_once = False
  50
  51     origin_server = True    # We are transmitting direct to client
  52     http_version  = "1.0"   # Version that should be used for response
  53     server_software = None  # String name of server software, if any
  54
  55     # os_environ is used to supply configuration from the OS environment:
  56     # by default it's a copy of 'os.environ' as of import time, but you can
  57     # override this in e.g. your __init__ method.
  58     os_environ = dict(os.environ.items())
  59
  60     # Collaborator classes
  61     wsgi_file_wrapper = FileWrapper     # set to None to disable
  62     headers_class = Headers             # must be a Headers-like class
  63
  64     # Error handling (also per-subclass or per-instance)
  65     traceback_limit = None  # Print entire traceback to self.get_stderr()
  66     error_status = "500 Internal Server Error"
  67     error_headers = [('Content-Type','text/plain')]
  68     error_body = "A server error occurred.  Please contact the administrator."
  69
  70     # State variables (don't mess with these)
  71     status = result = None
  72     headers_sent = False
  73     headers = None
  74     bytes_sent = 0
  75
  76     def run(self, application):
  77         """Invoke the application"""
  78         # Note to self: don't move the close()!  Asynchronous servers shouldn't
  79         # call close() from finish_response(), so if you close() anywhere but
  80         # the double-error branch here, you'll break asynchronous servers by
  81         # prematurely closing.  Async servers must return from 'run()' without
  82         # closing if there might still be output to iterate over.
  83         try:
  84             self.setup_environ()
  85             self.result = application(self.environ, self.start_response)
  86             self.finish_response()
  87         except:
  88             try:
  89                 self.handle_error()
  90             except:
  91                 # If we get an error handling an error, just give up already!
  92                 self.close()
  93                 raise   # ...and let the actual server figure it out.
  94
  95
  96     def setup_environ(self):
  97         """Set up the environment for one request"""
  98
  99         env = self.environ = self.os_environ.copy()
 100         self.add_cgi_vars()
 101
 102         env['wsgi.input']        = self.get_stdin()
 103         env['wsgi.errors']       = self.get_stderr()
 104         env['wsgi.version']      = self.wsgi_version
 105         env['wsgi.run_once']     = self.wsgi_run_once
 106         env['wsgi.url_scheme']   = self.get_scheme()
 107         env['wsgi.multithread']  = self.wsgi_multithread
 108         env['wsgi.multiprocess'] = self.wsgi_multiprocess
 109
 110         if self.wsgi_file_wrapper is not None:
 111             env['wsgi.file_wrapper'] = self.wsgi_file_wrapper
 112
 113         if self.origin_server and self.server_software:
 114             env.setdefault('SERVER_SOFTWARE',self.server_software)
 115
 116
 117     def finish_response(self):
 118         """Send any iterable data, then close self and the iterable
 119
 120         Subclasses intended for use in asynchronous servers will
 121         want to redefine this method, such that it sets up callbacks
 122         in the event loop to iterate over the data, and to call
 123         'self.close()' once the response is finished.
 124         """
 125         if not self.result_is_file() or not self.sendfile():
 126             for data in self.result:
 127                 self.write(data)
 128             self.finish_content()
 129         self.close()
 130
 131
 132     def get_scheme(self):
 133         """Return the URL scheme being used"""
 134         return guess_scheme(self.environ)
 135
 136
 137     def set_content_length(self):
 138         """Compute Content-Length or switch to chunked encoding if possible"""
 139         try:
 140             blocks = len(self.result)
 141         except (TypeError,AttributeError,NotImplementedError):
 142             pass
 143         else:
 144             if blocks==1:
 145                 self.headers['Content-Length'] = str(self.bytes_sent)
 146                 return
 147         # XXX Try for chunked encoding if origin server and client is 1.1
 148
 149
 150     def cleanup_headers(self):
 151         """Make any necessary header changes or defaults
 152
 153         Subclasses can extend this to add other defaults.
 154         """
 155         if 'Content-Length' not in self.headers:
 156             self.set_content_length()
 157
 158     def start_response(self, status, headers,exc_info=None):
 159         """'start_response()' callable as specified by PEP 333"""
 160
 161         if exc_info:
 162             try:
 163                 if self.headers_sent:
 164                     # Re-raise original exception if headers sent
 165                     raise exc_info[0], exc_info[1], exc_info[2]
 166             finally:
 167                 exc_info = None        # avoid dangling circular ref
 168         elif self.headers is not None:
 169             raise AssertionError("Headers already set!")
 170
 171         assert type(status) is StringType,"Status must be a string"
 172         assert len(status)>=4,"Status must be at least 4 characters"
 173         assert int(status[:3]),"Status message must begin w/3-digit code"
 174         assert status[3]==" ", "Status message must have a space after code"
 175         if __debug__:
 176             for name,val in headers:
 177                 assert type(name) is StringType,"Header names must be strings"
 178                 assert type(val) is StringType,"Header values must be strings"
 179                 assert not is_hop_by_hop(name),"Hop-by-hop headers not allowed"
 180         self.status = status
 181         self.headers = self.headers_class(headers)
 182         return self.write
 183
 184
 185     def send_preamble(self):
 186         """Transmit version/status/date/server, via self._write()"""
 187         if self.origin_server:
 188             if self.client_is_modern():
 189                 self._write('HTTP/%s %s\r\n' % (self.http_version,self.status))
 190                 if 'Date' not in self.headers:
 191                     self._write(
 192                         'Date: %s\r\n' % format_date_time(time.time())
 193                     )
 194                 if self.server_software and 'Server' not in self.headers:
 195                     self._write('Server: %s\r\n' % self.server_software)
 196         else:
 197             self._write('Status: %s\r\n' % self.status)
 198
 199     def write(self, data):
 200         """'write()' callable as specified by PEP 333"""
 201
 202         assert type(data) is StringType,"write() argument must be string"
 203
 204         if not self.status:
 205             raise AssertionError("write() before start_response()")
 206
 207         elif not self.headers_sent:
 208             # Before the first output, send the stored headers
 209             self.bytes_sent = len(data)    # make sure we know content-length
 210             self.send_headers()
 211         else:
 212             self.bytes_sent += len(data)
 213
 214         # XXX check Content-Length and truncate if too many bytes written?
 215         self._write(data)
 216         self._flush()
 217
 218
 219     def sendfile(self):
 220         """Platform-specific file transmission
 221
 222         Override this method in subclasses to support platform-specific
 223         file transmission.  It is only called if the application's
 224         return iterable ('self.result') is an instance of
 225         'self.wsgi_file_wrapper'.
 226
 227         This method should return a true value if it was able to actually
 228         transmit the wrapped file-like object using a platform-specific
 229         approach.  It should return a false value if normal iteration
 230         should be used instead.  An exception can be raised to indicate
 231         that transmission was attempted, but failed.
 232
 233         NOTE: this method should call 'self.send_headers()' if
 234         'self.headers_sent' is false and it is going to attempt direct
 235         transmission of the file.
 236         """
 237         return False   # No platform-specific transmission by default
 238
 239
 240     def finish_content(self):
 241         """Ensure headers and content have both been sent"""
 242         if not self.headers_sent:
 243             # Only zero Content-Length if not set by the application (so
 244             # that HEAD requests can be satisfied properly, see #3839)
 245             self.headers.setdefault('Content-Length', "0")
 246             self.send_headers()
 247         else:
 248             pass # XXX check if content-length was too short?
 249
 250     def close(self):
 251         """Close the iterable (if needed) and reset all instance vars
 252
 253         Subclasses may want to also drop the client connection.
 254         """
 255         try:
 256             if hasattr(self.result,'close'):
 257                 self.result.close()
 258         finally:
 259             self.result = self.headers = self.status = self.environ = None
 260             self.bytes_sent = 0; self.headers_sent = False
 261
 262
 263     def send_headers(self):
 264         """Transmit headers to the client, via self._write()"""
 265         self.cleanup_headers()
 266         self.headers_sent = True
 267         if not self.origin_server or self.client_is_modern():
 268             self.send_preamble()
 269             self._write(str(self.headers))
 270
 271
 272     def result_is_file(self):
 273         """True if 'self.result' is an instance of 'self.wsgi_file_wrapper'"""
 274         wrapper = self.wsgi_file_wrapper
 275         return wrapper is not None and isinstance(self.result,wrapper)
 276
 277
 278     def client_is_modern(self):
 279         """True if client can accept status and headers"""
 280         return self.environ['SERVER_PROTOCOL'].upper() != 'HTTP/0.9'
 281
 282
 283     def log_exception(self,exc_info):
 284         """Log the 'exc_info' tuple in the server log
 285
 286         Subclasses may override to retarget the output or change its format.
 287         """
 288         try:
 289             from traceback import print_exception
 290             stderr = self.get_stderr()
 291             print_exception(
 292                 exc_info[0], exc_info[1], exc_info[2],
 293                 self.traceback_limit, stderr
 294             )
 295             stderr.flush()
 296         finally:
 297             exc_info = None
 298
 299     def handle_error(self):
 300         """Log current error, and send error output to client if possible"""
 301         self.log_exception(sys.exc_info())
 302         if not self.headers_sent:
 303             self.result = self.error_output(self.environ, self.start_response)
 304             self.finish_response()
 305         # XXX else: attempt advanced recovery techniques for HTML or text?
 306
 307     def error_output(self, environ, start_response):
 308         """WSGI mini-app to create error output
 309
 310         By default, this just uses the 'error_status', 'error_headers',
 311         and 'error_body' attributes to generate an output page.  It can
 312         be overridden in a subclass to dynamically generate diagnostics,
 313         choose an appropriate message for the user's preferred language, etc.
 314
 315         Note, however, that it's not recommended from a security perspective to
 316         spit out diagnostics to any old user; ideally, you should have to do
 317         something special to enable diagnostic output, which is why we don't
 318         include any here!
 319         """
 320         start_response(self.error_status,self.error_headers[:],sys.exc_info())
 321         return [self.error_body]
 322
 323
 324     # Pure abstract methods; *must* be overridden in subclasses
 325
 326     def _write(self,data):
 327         """Override in subclass to buffer data for send to client
 328
 329         It's okay if this method actually transmits the data; BaseHandler
 330         just separates write and flush operations for greater efficiency
 331         when the underlying system actually has such a distinction.
 332         """
 333         raise NotImplementedError
 334
 335     def _flush(self):
 336         """Override in subclass to force sending of recent '_write()' calls
 337
 338         It's okay if this method is a no-op (i.e., if '_write()' actually
 339         sends the data.
 340         """
 341         raise NotImplementedError
 342
 343     def get_stdin(self):
 344         """Override in subclass to return suitable 'wsgi.input'"""
 345         raise NotImplementedError
 346
 347     def get_stderr(self):
 348         """Override in subclass to return suitable 'wsgi.errors'"""
 349         raise NotImplementedError
 350
 351     def add_cgi_vars(self):
 352         """Override in subclass to insert CGI variables in 'self.environ'"""
 353         raise NotImplementedError
 354
 355
 356 class SimpleHandler(BaseHandler):
 357     """Handler that's just initialized with streams, environment, etc.
 358
 359     This handler subclass is intended for synchronous HTTP/1.0 origin servers,
 360     and handles sending the entire response output, given the correct inputs.
 361
 362     Usage::
 363
 364         handler = SimpleHandler(
 365             inp,out,err,env, multithread=False, multiprocess=True
 366         )
 367         handler.run(app)"""
 368
 369     def __init__(self,stdin,stdout,stderr,environ,
 370         multithread=True, multiprocess=False
 371     ):
 372         self.stdin = stdin
 373         self.stdout = stdout
 374         self.stderr = stderr
 375         self.base_env = environ
 376         self.wsgi_multithread = multithread
 377         self.wsgi_multiprocess = multiprocess
 378
 379     def get_stdin(self):
 380         return self.stdin
 381
 382     def get_stderr(self):
 383         return self.stderr
 384
 385     def add_cgi_vars(self):
 386         self.environ.update(self.base_env)
 387
 388     def _write(self,data):
 389         self.stdout.write(data)
 390         self._write = self.stdout.write
 391
 392     def _flush(self):
 393         self.stdout.flush()
 394         self._flush = self.stdout.flush
 395
 396
 397 class BaseCGIHandler(SimpleHandler):
 398
 399     """CGI-like systems using input/output/error streams and environ mapping
 400
 401     Usage::
 402
 403         handler = BaseCGIHandler(inp,out,err,env)
 404         handler.run(app)
 405
 406     This handler class is useful for gateway protocols like ReadyExec and
 407     FastCGI, that have usable input/output/error streams and an environment
 408     mapping.  It's also the base class for CGIHandler, which just uses
 409     sys.stdin, os.environ, and so on.
 410
 411     The constructor also takes keyword arguments 'multithread' and
 412     'multiprocess' (defaulting to 'True' and 'False' respectively) to control
 413     the configuration sent to the application.  It sets 'origin_server' to
 414     False (to enable CGI-like output), and assumes that 'wsgi.run_once' is
 415     False.
 416     """
 417
 418     origin_server = False
 419
 420
 421 class CGIHandler(BaseCGIHandler):
 422
 423     """CGI-based invocation via sys.stdin/stdout/stderr and os.environ
 424
 425     Usage::
 426
 427         CGIHandler().run(app)
 428
 429     The difference between this class and BaseCGIHandler is that it always
 430     uses 'wsgi.run_once' of 'True', 'wsgi.multithread' of 'False', and
 431     'wsgi.multiprocess' of 'True'.  It does not take any initialization
 432     parameters, but always uses 'sys.stdin', 'os.environ', and friends.
 433
 434     If you need to override any of these parameters, use BaseCGIHandler
 435     instead.
 436     """
 437
 438     wsgi_run_once = True
 439     # Do not allow os.environ to leak between requests in Google App Engine
 440     # and other multi-run CGI use cases.  This is not easily testable.
 441     # See http://bugs.python.org/issue7250
 442     os_environ = {}
 443
 444     def __init__(self):
 445         BaseCGIHandler.__init__(
 446             self, sys.stdin, sys.stdout, sys.stderr, dict(os.environ.items()),
 447             multithread=False, multiprocess=True
 448         )