This documentation refers to CherryPy 3.1 and following. If you're using an older version, things are quite different.

Engine Plugins

The cherrypy.engine object is a WebSiteProcessBus. To extend the behavior of the bus, you subscribe plugins: engine.subscribe(channel, callback[, priority]). The channel is an event name, like "start", "stop", "exit", "graceful", or "log". The callback is a function, class, or other callable. The optional priority (0 - 100) allows multiple plugins to run in the correct order.

Most of the builtin plugins have their own subscribe method, so that instead of writing the above, you write: Plugin(engine).subscribe(). That's it. If you want to turn off a plugin, call plugin.unsubscribe(). The plugin already knows the correct channel, callback, and priority.

Builtin Plugins

Autoreloader

The autoreload plugin restarts the process (via os.execv) if any of the files it monitors change (or is deleted). By default, the autoreloader monitors all imported modules; you can add to the set by adding to autoreloader.files:

cherrypy.engine.autoreload.files.add(myFile)

If there are imported files you do *not* wish to monitor, you can adjust the match attribute, a regular expression. For example, to stop monitoring cherrypy itself:

cherrypy.engine.autoreload.match = r'^(?!cherrypy).+'

Like all Monitor plugins (see below), the autoreload plugin takes a frequency argument. The default is 1 second; that is, the autoreloader will examine its files once each second.

Daemonizer

When this component finishes, the process is completely decoupled from the parent environment, using the traditional double-fork. It is only available on Unix and similar systems which provide fork().

If a startup error occurs in the forked children, the return code from the parent process will still be 0. Errors in the initial daemonizing process still return proper exit codes, but errors after the fork won't. Therefore, if you use this plugin to daemonize, don't use the return code as an accurate indicator of whether the process fully started. In fact, that return code only indicates if the process successfully finished the first fork.

The plugin takes optional arguments to redirect standard streams: stdin, stdout, and stderr. By default, these are all redirected to /dev/null, but you're free to send them to log files or elsewhere.

You should be careful to not start any threads before this plugin runs. The plugin will warn if you do so, because "...the effects of calling functions that require certain resources between the call to fork() and the call to an exec function are undefined". (ref). It is for this reason that the Server plugin runs at priority 75 (it starts worker threads), which is later than the default priority of 65 for the Daemonizer.

DropPrivileges

Use this plugin to start your CherryPy site as root (to, for example, listen on port 80) and then reduce privileges to something more restricted.

• uid: the user id to switch to. Availability: Unix.
• gid: the group id to switch to. Availability: Unix.
• umask: the default permission mode for newly created files and directories. Usually expressed in octal format, for example, 0644. Availability: Unix, Windows.

Monitor

A generic plugin to periodically run a callback in its own thread. Some of the other builtin plugins subclass this already.

• callback: the function to call at intervals.
• frequency: the time in seconds between callback runs.

PIDFile

The PIDFile plugin is pretty straightforward: it writes the process id to a file on start, and deletes the file on exit. You must provide a 'pidfile' argument, preferably an absolute path.

HTTP Servers

Starting in CherryPy 3.1, cherrypy.server is implemented as a Plugin. It's actually an instance of _cpserver.Server, which is a subclass of process.servers.ServerAdapter. The ServerAdapter class is designed to control other servers, as well.

If you need to start more than one HTTP server (to serve on multiple ports, or protocols, etc.), you can manually register each one and then start them all with engine.start:

s1 = ServerAdapter(cherrypy.engine, MyWSGIServer(host='0.0.0.0', port=80))
s2 = ServerAdapter(cherrypy.engine, another.HTTPServer(host='127.0.0.1', SSL=True))
s1.subscribe()
s2.subscribe()
cherrypy.engine.start()

There are also FlupFCGIServer and FlupSCGIServer classes in process.servers. To start an fcgi server, for example, wrap an instance of it in a ServerAdapter:

addr = ('0.0.0.0', 4000)
f = servers.FlupFCGIServer(application=cherrypy.tree, bindAddress=addr)
s = servers.ServerAdapter(cherrypy.engine, httpserver=f, bind_addr=addr)
s.subscribe()

SignalHandler

This plugin is instantiated automatically as cherrypy.engine.signal_handler. However, it is only subscribed automatically by cherrypy.quickstart(). So if you want signal handling and you're calling tree.mount(); engine.start(); engine.block() on your own, be sure to add:

if hasattr(cherrypy.engine, 'signal_handler'):
    cherrypy.engine.signal_handler.subscribe()

You can modify what signals your application listens for, and what it does when it receives signals, by modifying SignalHandler.handlers, a dict of {signal name: callback} pairs. The default set is:

handlers = {'SIGTERM': self.bus.exit,
            'SIGHUP': self.handle_SIGHUP,
            'SIGUSR1': self.bus.graceful,
           }

The handle_SIGHUP method calls bus.restart() if the process is daemonized, but bus.exit() if the process is attached to a TTY. This is because Unix window managers tend to send SIGHUP to terminal windows when the user closes them.

Feel free to add signals which are not available on every platform. The SignalHandler will ignore errors raised from attempting to register handlers for unknown signals.

ThreadManager

A manager for HTTP request threads. Creating an instance of this plugin causes two new channels to be registered with the bus: acquire_thread and release_thread.

If you have control over thread creation and destruction, publish to the 'acquire_thread' and 'release_thread' channels (for each thread). This will register/unregister the current thread, and further cause a publish to 'start_thread' and 'stop_thread' listeners in the bus as needed. If you're using normal cherrypy.Applications (you probably are), then they will do all this for you.

If threads are created and destroyed by code you do not control (e.g., Apache), then, at the beginning of every HTTP request, publish to 'acquire_thread' only. You should not publish to 'release_thread' in this case, since you do not know whether the thread will be re-used or not. The bus will call 'stop_thread' listeners for you when it stops.