Download Install Tutorial Docs FAQ Tools Wiki ∇ License Team IRC Planet Involvement Shop Book

Changeset 1539

Show
Ignore:
Timestamp:
12/20/06 19:02:20
Author:
fumanchu
Message:

Docstrings for wsgiserver.py.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/cherrypy/wsgiserver.py

    r1538 r1539  
    1  
    2 ######################################################################### 
    3 # 
    4 # # Simplest example on how to use this module directly 
    5 # # Without going through the CherryPy machinery 
    6 #  
    7 # from cherrypy import wsgiserver 
    8 # 
    9 # def my_crazy_app(environ, start_response): 
    10 #     status = '200 OK' 
    11 #     response_headers = [('Content-type','text/plain')] 
    12 #     start_response(status, response_headers) 
    13 #     return ['Hello world!\n'] 
    14 # 
    15 # # The CherryPy WSGI server can serve as many WSGI application 
    16 # # as you want in one instance 
    17 # 
    18 # # Her we set our application to the script_name '/'  
    19 # wsgi_apps = [('/', my_crazy_app)] 
    20 # 
    21 # # This won't call CherryPy machinery at all 
    22 # # Only the WSGI server which is independant from CherryPy itself 
    23 # # Its name reflects its origin... 
    24 # server = wsgiserver.CherryPyWSGIServer(('localhost', 8070),  
    25 #                                        wsgi_apps, server_name='localhost') 
    26 # 
    27 # # Want SSL support? Just set those attributes 
    28 # # server.ssl_certificate = ... 
    29 # # server.ssl_private_key = ... 
    30 # 
    31 # if __name__ == '__main__': 
    32 #     server.start() 
    33 ######################################################################### 
    34  
    35 """A high-speed, production ready, thread pooled, generic WSGI server.""" 
     1"""A high-speed, production ready, thread pooled, generic WSGI server. 
     2 
     3Simplest example on how to use this module directly 
     4(without using CherryPy's application machinery): 
     5 
     6    from cherrypy import wsgiserver 
     7     
     8    def my_crazy_app(environ, start_response): 
     9        status = '200 OK' 
     10        response_headers = [('Content-type','text/plain')] 
     11        start_response(status, response_headers) 
     12        return ['Hello world!\n'] 
     13     
     14    # Here we set our application to the script_name '/'  
     15    wsgi_apps = [('/', my_crazy_app)] 
     16     
     17    server = wsgiserver.CherryPyWSGIServer(('localhost', 8070), wsgi_apps, 
     18                                           server_name='localhost') 
     19     
     20    # Want SSL support? Just set these attributes 
     21    # server.ssl_certificate = <filename> 
     22    # server.ssl_private_key = <filename> 
     23     
     24    if __name__ == '__main__': 
     25        server.start() 
     26 
     27This won't call the CherryPy engine (application side) at all, only the 
     28WSGI server, which is independant from the rest of CherryPy. Don't 
     29let the name "CherryPyWSGIServer" throw you; the name merely reflects 
     30its origin, not it's coupling. 
     31 
     32The CherryPy WSGI server can serve as many WSGI application 
     33as you want in one instance: 
     34 
     35    wsgi_apps = [('/', my_crazy_app), (/blog', my_blog_app)] 
     36 
     37""" 
     38 
    3639 
    3740import base64 
    …… 
    8487 
    8588class HTTPRequest(object): 
    86      
    87  
     89    """An HTTP Request (and response). 
     90     
     91    A single HTTP connection may consist of multiple request/response pairs. 
     92     
     93    connection: the HTTP Connection object which spawned this request. 
     94    rfile: the 'read' fileobject from the connection's socket 
     95    ready: when True, the request has been parsed and is ready to begin 
     96        generating the response. When False, signals the calling Connection 
     97        that the response should not be generated and the connection should 
     98        close. 
     99    close_connection: signals the calling Connection that the request 
     100        should close. This does not imply an error! The client and/or 
     101        server may each request that the connection be closed. 
     102    chunked_write: if True, output will be encoded with the "chunked" 
     103        transfer-coding. This value is set automatically inside 
     104        send_headers. 
     105    """ 
     106     
    88107    def __init__(self, connection): 
    89108        self.connection = connection 
    …… 
    100119     
    101120    def parse_request(self): 
     121        """Parse the next HTTP request start-line and message-headers.""" 
    102122        # HTTP/1.1 connections are persistent by default. If a client 
    103123        # requests a page, then idles (leaves the connection open), 
    …… 
    269289     
    270290    def parse_headers(self, headers): 
     291        """Parse the given HTTP request message-headers.""" 
    271292        environ = {} 
    272293        ct = headers.getheader("Content-type", "") 
    …… 
    320341     
    321342    def respond(self): 
     343        """Call the appropriate WSGI app and write its iterable output.""" 
    322344        wfile = self.connection.wfile 
    323345        response = self.wsgi_app(self.environ, self.start_response) 
    …… 
    354376     
    355377    def start_response(self, status, headers, exc_info = None): 
     378        """WSGI callable to begin the HTTP response.""" 
    356379        if self.started_response: 
    357380            if not exc_info: 
    …… 
    368391     
    369392    def write(self, chunk): 
     393        """WSGI callable to write unbuffered data to the client. 
     394         
     395        This method is also used internally by start_response (to write 
     396        data from the iterable returned by the WSGI application). 
     397        """ 
    370398        if not self.sent_headers: 
    371399            self.sent_headers = True 
    …… 
    382410     
    383411    def send_headers(self): 
     412        """Assert, process, and send the HTTP response message-headers.""" 
    384413        hkeys = [key.lower() for (key, value) in self.outheaders] 
    385414        status = int(self.status[:3]) 
    …… 
    474503 
    475504class HTTPConnection(object): 
     505    """An HTTP connection (active socket). 
     506     
     507    socket: the raw socket object (usually TCP) for this connection. 
     508    addr: the "bind address" for the remote end of the socket. 
     509        For IP sockets, this is a tuple of (REMOTE_ADDR, REMOTE_PORT). 
     510        For UNIX domain sockets, this will be a string. 
     511    server: the HTTP Server for this Connection. Usually, the server 
     512        object possesses a passive (server) socket which spawns multiple, 
     513        active (client) sockets, one for each connection. 
     514     
     515    environ: a WSGI environ template. This will be copied for each request. 
     516    rfile: a fileobject for reading from the socket. 
     517    wfile: a fileobject for writing to the socket. 
     518    """ 
    476519     
    477520    rbufsize = -1 
    …… 
    551594     
    552595    def close(self): 
     596        """Close the socket underlying this connection.""" 
    553597        self.rfile.close() 
    554598        self.wfile.close() 
    …… 
    568612 
    569613class WorkerThread(threading.Thread): 
     614    """Thread which continuously polls a Queue for Connection objects. 
     615     
     616    server: the HTTP Server which spawned this thread, and which owns the 
     617        Queue and is placing active connections into it. 
     618    ready: a simple flag for the calling server to know when this thread 
     619        has begun polling the Queue. 
     620     
     621    Due to the timing issues of polling a Queue, a WorkerThread does not 
     622    check its own 'ready' flag after it has started. To stop the thread, 
     623    it is necessary to stick a _SHUTDOWNREQUEST object onto the Queue 
     624    (one for each running WorkerThread). 
     625    """ 
    570626     
    571627    def __init__(self, server): 
    …… 
    591647 
    592648class SSLConnection: 
     649    """A thread-safe wrapper for an SSL.Connection. 
     650     
     651    *args: the arguments to create the wrapped SSL.Connection(*args). 
     652    """ 
     653     
    593654    def __init__(self, *args): 
    594655        self._ssl_conn = SSL.Connection(*args) 
    …… 
    626687        specifies the maximum number of queued connections (default 5). 
    627688    timeout: the timeout in seconds for accepted connections (default 10). 
     689     
     690    protocol: the version string to write in the Status-Line of all 
     691        HTTP responses. For example, "HTTP/1.1" (the default). This 
     692        also limits the supported features used in the response. 
     693     
     694     
     695    SSL/HTTPS 
     696    --------- 
     697    The OpenSSL module must be importable for SSL functionality. 
     698    You can obtain it from http://pyopenssl.sourceforge.net/ 
     699     
     700    ssl_certificate: the filename of the server SSL certificate. 
     701    ssl_privatekey: the filename of the server's private key file. 
     702     
     703    If either of these is None (both are None by default), this server 
     704    will not use SSL. If both are given and are valid, they will be read 
     705    on server start and used in the SSL context for the listening socket. 
    628706    """ 
    629707     
    …… 
    763841     
    764842    def tick(self): 
     843        """Accept a new connection and put it on the Queue.""" 
    765844        try: 
    766845            s, addr = self.socket.accept() 
    …… 
    792871        self.stop() 
    793872        self._interrupt = interrupt 
    794     interrupt = property(_get_interrupt, _set_interrupt) 
     873    interrupt = property(_get_interrupt, _set_interrupt, 
     874                         doc="Set this to an Exception instance to " 
     875                             "interrupt the server.") 
    795876     
    796877    def stop(self): 

Hosted by WebFaction

Log in as guest/cpguest to create tickets