Server API

In CherryPy 3, there are a number of objects working together between the client (browser) and the Request object. That is, cherrypy.server (an instance of the Server class) creates and controls an HTTP Server*. The HTTP Server object then accepts each HTTP request from the Client, transforms it for the CherryPy API, obtains a CherryPy Request object, calls request.run() to obtain a response, and then writes that response as HTTP to the client. Again, if you're using WSGI, there's an extra set of transformations in there (but it's that very thing that allows you to swap out HTTP Servers).

In general, that stack looks like this (the WSGI phase is only used with WSGI servers):

                 Server
                   |
                   V
              +--------+      +----------+                                +-----------+
        HTTP  |        |      |          |                          new   |           |
Client -----> |        | ---> |          | ---> Engine/app.request() ---> | Request() |
              |  HTTP  |      |   WSGI   |                                |           |
              | Server | ---> |          | -------------------- run() --> +-----+-----+
        HTTP  |        |      |          |                                      |
       <----- |        | <--- |          | <----------------------------<-------+ 
              +--------+      +----------+

* CP 3.0 allowed cherrypy.server to control multiple HTTP servers, a design mistake which will be corrected in version 3.1.

cherrypy.server

This object is created for you when CherryPy is first imported. As you can see in the diagram above, it isn't the HTTP server itself; rather, it manages an HTTP Server. This provides a uniform interface to developers that is configurable using cherrypy.config. Whatever values you set in config that start with "server." will be set on the cherrypy.server object. For example, the config file:

[global]
server.socket_port = 80
server.thread_pool = 30

...will set cherrypy.server.socket_port = 80 and cherrypy.server.thread_pool = 30. You can then call cherrypy.server.quickstart(), and those values will be passed to the actual HTTP server.

By default, CherryPy will listen on any available interface; however, the decision whether to prefer IPv4 or IPv6 (if available) is up to the operating system. If you need to force a specific addressing space you will need to either turn the other off on the system, or provide a specific address (like "192.0.2.0" for IPv4) via the server.socket_host option. This can also take a hostname.

HTTP Server API

If you want to use an HTTP Server other than the builtin server, and you want cherrypy.server to start and stop it, it needs to follow a certain API (so you'll probably need to write a wrapper for it). Instantiate additional or custom HTTP servers yourself and then register them using cherrypy._cpserver.ServerAdapter(cherrypy.engine, myserver, (host, port)).subscribe() (3.0: cherrypy.server.httpservers[myserver] = (host, port)). Such servers must possess the following attributes:

• start(): This function will be called with no arguments. It is expected to block (so steps are taken by CherryPy to run it in a new thread). If KeyboardInterrupt or SystemExit are raised, CherryPy traps them and shuts down all HTTP servers and the CherryPy engine. All other errors should be trapped within the HTTP server.
• ready: This attribute should be a boolean (or at least evaluable with "if ready:"). It should evaluate to False by default. If the HTTP Server is actually listening on its socket and ready to receive requests, it should evaluate to True. Once it does, CherryPy will attempt to connect on the socket to verify that it is listening. If the HTTP Server has no "ready" attribute, CherryPy will assume the HTTP server is always ready, and will not wait for it to announce that it is ready before verifying the socket is bound.
• stop(): This function will be called with no arguments, and MUST block until the HTTP Server is truly stopped; that is, all worker threads must be terminated, and the socket released, before returning from this method. Once this method returns, cherrypy.server will attempt to connect on the socket to verify that there is no service listening on it.

If you want to use CherryPy defaults to configure your HTTP Server (using quickstart), your server's __init__ method may inspect/copy the following attributes of cherrypy.server:

Attribute	Default
socket_port	8080
socket_host
socket_file
socket_queue_size	5
socket_timeout	10
protocol_version	'HTTP/1.1'
reverse_dns	False
thread_pool	10
max_request_header_size	500 * 1024
max_request_body_size	100 * 1024 * 1024
ssl_certificate	None
ssl_private_key	None

Older versions

2.2

replace this	with this
server.quickstart	server.start(init_only=True)

In CherryPy 2, cherrypy.server was a subclass of cherrypy.engine, and therefore had the following additional attributes:

blocking

If the "init_only" argument to server.start is True, this will be False, and vice-versa.

httpserverclass

Whatever HTTP server class is set in server.start will be stuck in here.

httpserver

Whatever HTTP server class is set in server.start will be instantiated and stuck in here.

start_with_callback

start_with_callback(func, args=(), kwargs={}, serverclass = missing)

Since server.start usually blocks, use this to easily run another function in a new thread. It starts the new thread and then runs server.start. The new thread automatically waits for the server to finish its startup procedure.