cherrypy.wsgiserver – WSGI Server

HTTP

class cherrypy.wsgiserver.HTTPRequest(server, conn)

An HTTP Request (and response).

A single HTTP connection may consist of multiple request/response pairs.

chunked_write = False

If True, output will be encoded with the “chunked” transfer-coding.

This value is set automatically inside send_headers.

close_connection = False

Signals the calling Connection that the request should close. This does not imply an error! The client and/or server may each request that the connection be closed.

conn = None

The HTTPConnection object on which this request connected.

inheaders = {}

A dict of request headers.

outheaders = []

A list of header tuples to write in the response.

parse_request()

Parse the next HTTP request start-line and message-headers.

parse_request_uri(uri)

Parse a Request-URI into (scheme, authority, path).

Note that Request-URI’s must be one of:

Request-URI    = "*" | absoluteURI | abs_path | authority

Therefore, a Request-URI which starts with a double forward-slash cannot be a “net_path”:

net_path      = "//" authority [ abs_path ]

Instead, it must be interpreted as an “abs_path” with an empty first path segment:

abs_path      = "/"  path_segments
path_segments = segment *( "/" segment )
segment       = *pchar *( ";" param )
param         = *pchar
read_request_headers()

Read self.rfile into self.inheaders. Return success.

ready = False

When True, the request has been parsed and is ready to begin generating the response. When False, signals the calling Connection that the response should not be generated and the connection should close.

respond()

Call the gateway and write its iterable output.

send_headers()

Assert, process, and send the HTTP response message-headers.

You must set self.status, and self.outheaders before calling this.

server = None

The HTTPServer object which is receiving this request.

simple_response(status, msg='')

Write a simple response back to the client.

write(chunk)

Write unbuffered data to the client.

class cherrypy.wsgiserver.HTTPConnection(server, sock, makefile=<class 'cherrypy.wsgiserver.wsgiserver2.CP_fileobject'>)

An HTTP connection (active socket).

server: the Server object which received this connection. socket: the raw socket object (usually TCP) for this connection. makefile: a fileobject class for reading from the socket.

RequestHandlerClass

alias of HTTPRequest

close()

Close the socket underlying this connection.

communicate()

Read each request and respond appropriately.

class cherrypy.wsgiserver.HTTPServer(bind_addr, gateway, minthreads=10, maxthreads=-1, server_name=None)

An HTTP server.

ConnectionClass

The class to use for handling HTTP connections.

alias of HTTPConnection

bind(family, type, proto=0)

Create (or recreate) the actual socket object.

bind_addr

The interface on which to listen for connections.

For TCP sockets, a (host, port) tuple. Host values may be any IPv4 or IPv6 address, or any valid hostname. The string ‘localhost’ is a synonym for ‘127.0.0.1’ (or ‘::1’, if your hosts file prefers IPv6). The string ‘0.0.0.0’ is a special IPv4 entry meaning “any active interface” (INADDR_ANY), and ‘::’ is the similar IN6ADDR_ANY for IPv6. The empty string or None are not allowed.

For UNIX sockets, supply the filename as a string.

gateway = None

A Gateway instance.

interrupt

Set this to an Exception instance to interrupt the server.

max_request_body_size = 0

The maximum size, in bytes, for request bodies, or 0 for no limit.

max_request_header_size = 0

The maximum size, in bytes, for request headers, or 0 for no limit.

maxthreads = None

The maximum number of worker threads to create (default -1 = no limit).

minthreads = None

The minimum number of worker threads to create (default 10).

nodelay = True

If True (the default since 3.1), sets the TCP_NODELAY socket option.

protocol = 'HTTP/1.1'

The version string to write in the Status-Line of all HTTP responses.

For example, “HTTP/1.1” is the default. This also limits the supported features used in the response.

ready = False

An internal flag which marks whether the socket is accepting connections

request_queue_size = 5

The ‘backlog’ arg to socket.listen(); max queued connections (default 5).

server_name = None

The name of the server; defaults to socket.gethostname().

shutdown_timeout = 5

The total time, in seconds, to wait for worker threads to cleanly exit.

software = None

The value to set for the SERVER_SOFTWARE entry in the WSGI environ.

If None, this defaults to '%s Server' % self.version.

ssl_adapter = None

An instance of SSLAdapter (or a subclass).

You must have the corresponding SSL driver library installed.

start()

Run the server forever.

stop()

Gracefully shutdown a server that is serving forever.

tick()

Accept a new connection and put it on the Queue.

timeout = 10

The timeout in seconds for accepted connections (default 10).

version = 'CherryPy/3.3.0'

A version string for the HTTPServer.

Request Entities

class cherrypy.wsgiserver.SizeCheckWrapper(rfile, maxlen)

Wraps a file-like object, raising MaxSizeExceeded if too large.

class cherrypy.wsgiserver.KnownLengthRFile(rfile, content_length)

Wraps a file-like object, returning an empty string when exhausted.

class cherrypy.wsgiserver.ChunkedRFile(rfile, maxlen, bufsize=8192)

Wraps a file-like object, returning an empty string when exhausted.

This class is intended to provide a conforming wsgi.input value for request entities that have been encoded with the ‘chunked’ transfer encoding.

class cherrypy.wsgiserver.CP_fileobject(*args, **kwargs)

Faux file object attached to a socket object.

sendall(data)

Sendall for non-blocking sockets.

Exceptions

class cherrypy.wsgiserver.MaxSizeExceeded
class cherrypy.wsgiserver.NoSSLError

Exception raised when a client speaks HTTP to an HTTPS socket.

class cherrypy.wsgiserver.FatalSSLAlert

Exception raised when the SSL implementation signals a fatal alert.

Thread Pool

class cherrypy.wsgiserver.WorkerThread(server)

Thread which continuously polls a Queue for Connection objects.

Due to the timing issues of polling a Queue, a WorkerThread does not check its own ‘ready’ flag after it has started. To stop the thread, it is necessary to stick a _SHUTDOWNREQUEST object onto the Queue (one for each running WorkerThread).

conn = None

The current connection pulled off the Queue, or None.

ready = False

A simple flag for the calling server to know when this thread has begun polling the Queue.

server = None

The HTTP Server which spawned this thread, and which owns the Queue and is placing active connections into it.

class cherrypy.wsgiserver.ThreadPool(server, min=10, max=-1)

A Request Queue for an HTTPServer which pools threads.

ThreadPool objects must provide min, get(), put(obj), start() and stop(timeout) attributes.

grow(amount)

Spawn new worker threads (not above self.max).

idle

Number of worker threads which are idle. Read-only.

shrink(amount)

Kill off worker threads (not below self.min).

start()

Start the pool of threads.

SSL

class cherrypy.wsgiserver.SSLAdapter(certificate, private_key, certificate_chain=None)

Base class for SSL driver library adapters.

Required methods:

  • wrap(sock) -> (wrapped socket, ssl environ dict)
  • makefile(sock, mode='r', bufsize=DEFAULT_BUFFER_SIZE) -> socket file object

WSGI

class cherrypy.wsgiserver.CherryPyWSGIServer(bind_addr, wsgi_app, numthreads=10, server_name=None, max=-1, request_queue_size=5, timeout=10, shutdown_timeout=5)

A subclass of HTTPServer which calls a WSGI application.

wsgi_version = (1, 0)

The version of WSGI to produce.

class cherrypy.wsgiserver.Gateway(req)

A base class to interface HTTPServer with other systems, such as WSGI.

respond()

Process the current request. Must be overridden in a subclass.

class cherrypy.wsgiserver.WSGIGateway(req)

A base class to interface HTTPServer with WSGI.

get_environ()

Return a new environ dict targeting the given wsgi.version

respond()

Process the current request.

start_response(status, headers, exc_info=None)

WSGI callable to begin the HTTP response.

write(chunk)

WSGI callable to write unbuffered data to the client.

This method is also used internally by start_response (to write data from the iterable returned by the WSGI application).

class cherrypy.wsgiserver.WSGIGateway_10(req)

A Gateway class to interface HTTPServer with WSGI 1.0.x.

get_environ()

Return a new environ dict targeting the given wsgi.version

class cherrypy.wsgiserver.WSGIGateway_u0(req)

A Gateway class to interface HTTPServer with WSGI u.0.

WSGI u.0 is an experimental protocol, which uses unicode for keys and values in both Python 2 and Python 3.

get_environ()

Return a new environ dict targeting the given wsgi.version

class cherrypy.wsgiserver.WSGIPathInfoDispatcher(apps)

A WSGI dispatcher for dispatch based on the PATH_INFO.

apps: a dict or list of (path_prefix, app) pairs.