cherrypy.process.plugins module

Site services for use with a Web Site Process Bus.

class cherrypy.process.plugins.Autoreloader(bus, frequency=1, match='.*')

Bases: Monitor

Monitor which re-executes the process when files change.

This 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 autoreload.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, the autoreload plugin takes a frequency argument. The default is 1 second; that is, the autoreloader will examine files once each second.

static _archive_for_zip_module(module)

Return the archive filename for the module if relevant.

classmethod _file_for_file_module(module)

Return the file for the module.

classmethod _file_for_module(module)

Return the relevant file for the module.

static _make_absolute(filename)

Ensure filename is absolute to avoid effect of os.chdir.

files = None

The set of files to poll for modifications.

frequency = 1

The interval in seconds at which to poll for modified files.

match = '.*'

A regular expression by which to match filenames.

run()

Reload the process if registered files have been modified.

start()

Start our own background task thread for self.run.

sysfiles()

Return a Set of sys.modules filenames to monitor.

class cherrypy.process.plugins.BackgroundTask(interval, function, args=[], kwargs={}, bus=None)

Bases: Thread

A subclass of threading.Thread whose run() method repeats.

Use this class for most repeating tasks. It uses time.sleep() to wait for each interval, which isn’t very responsive; that is, even if you call self.cancel(), you’ll have to wait until the sleep() call finishes before the thread stops. To compensate, it defaults to being daemonic, which means it won’t delay stopping the whole process.

cancel()

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

class cherrypy.process.plugins.Daemonizer(bus, stdin='/dev/null', stdout='/dev/null', stderr='/dev/null')

Bases: SimplePlugin

Daemonize the running script.

Use this with a Web Site Process Bus via:

Daemonizer(bus).subscribe()

When this component finishes, the process is completely decoupled from the parent environment. Please note that when this component is used, the return code from the parent process will still be 0 if a startup error occurs in the forked children. Errors in the initial daemonizing process still return proper exit codes. 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.

static daemonize(stdin='/dev/null', stdout='/dev/null', stderr='/dev/null', logger=<function Daemonizer.<lambda>>)

start()

class cherrypy.process.plugins.DropPrivileges(bus, umask=None, uid=None, gid=None)

Bases: SimplePlugin

Drop privileges. uid/gid arguments not available on Windows.

Special thanks to Gavin Baker.

property gid

The gid under which to run.

Availability: Unix.

start()

property uid

The uid under which to run.

Availability: Unix.

property umask

The default permission mode for newly created files and directories.

Usually expressed in octal format, for example, 0644. Availability: Unix, Windows.

class cherrypy.process.plugins.Monitor(bus, callback, frequency=60, name=None)

Bases: SimplePlugin

WSPBus listener to periodically run a callback in its own thread.

callback = None

The function to call at intervals.

frequency = 60

The time in seconds between callback runs.

graceful()

Stop the callback’s background task thread and restart it.

start()

Start our callback in its own background thread.

stop()

Stop our callback’s background task thread.

thread = None

A BackgroundTask thread.

class cherrypy.process.plugins.PIDFile(bus, pidfile)

Bases: SimplePlugin

Maintain a PID file via a WSPBus.

exit()

start()

class cherrypy.process.plugins.PerpetualTimer(*args, **kwargs)

Bases: Timer

A responsive subclass of threading.Timer whose run() method repeats.

Use this timer only when you really need a very interruptible timer; this checks its ‘finished’ condition up to 20 times a second, which can results in pretty high CPU usage

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

class cherrypy.process.plugins.SignalHandler(bus)

Bases: object

Register bus channels (and listeners) for system signals.

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 SignalHandler.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.

_handle_signal(signum=None, frame=None)

Python signal handler (self.set_handler subscribes it for you).

_is_daemonized()

Return boolean indicating if the current process is running as a daemon.

The criteria to determine the daemon condition is to verify if the current pid is not the same as the one that got used on the initial construction of the plugin and the stdin is not connected to a terminal.

The sole validation of the tty is not enough when the plugin is executing inside other process like in a CI tool (Buildbot, Jenkins).

_jython_SIGINT_handler(signum=None, frame=None)

handle_SIGHUP()

Restart if daemonized, else exit.

handlers = {}

A map from signal names (e.g. ‘SIGTERM’) to handlers (e.g. bus.exit).

set_handler(signal, listener=None)

Subscribe a handler for the given signal (number or name).

If the optional ‘listener’ argument is provided, it will be subscribed as a listener for the given signal’s channel.

If the given signal name or number is not available on the current platform, ValueError is raised.

signals = {Signals.SIGHUP: 'SIGHUP', Signals.SIGINT: 'SIGINT', Signals.SIGQUIT: 'SIGQUIT', Signals.SIGILL: 'SIGILL', Signals.SIGTRAP: 'SIGTRAP', Signals.SIGABRT: 'SIGABRT', Signals.SIGBUS: 'SIGBUS', Signals.SIGFPE: 'SIGFPE', Signals.SIGKILL: 'SIGKILL', Signals.SIGUSR1: 'SIGUSR1', Signals.SIGSEGV: 'SIGSEGV', Signals.SIGUSR2: 'SIGUSR2', Signals.SIGPIPE: 'SIGPIPE', Signals.SIGALRM: 'SIGALRM', Signals.SIGTERM: 'SIGTERM', Signals.SIGCHLD: 'SIGCHLD', Signals.SIGCONT: 'SIGCONT', Signals.SIGSTOP: 'SIGSTOP', Signals.SIGTSTP: 'SIGTSTP', Signals.SIGTTIN: 'SIGTTIN', Signals.SIGTTOU: 'SIGTTOU', Signals.SIGURG: 'SIGURG', Signals.SIGXCPU: 'SIGXCPU', Signals.SIGXFSZ: 'SIGXFSZ', Signals.SIGVTALRM: 'SIGVTALRM', Signals.SIGPROF: 'SIGPROF', Signals.SIGWINCH: 'SIGWINCH', Signals.SIGIO: 'SIGPOLL', Signals.SIGPWR: 'SIGPWR', Signals.SIGSYS: 'SIGSYS', Signals.SIGRTMIN: 'SIGRTMIN', Signals.SIGRTMAX: 'SIGRTMAX'}

A map from signal numbers to names.

subscribe()

Subscribe self.handlers to signals.

unsubscribe()

Unsubscribe self.handlers from signals.

class cherrypy.process.plugins.SimplePlugin(bus)

Bases: object

Plugin base class which auto-subscribes methods for known channels.

bus = None

A Bus, usually cherrypy.engine.

subscribe()

Register this object as a (multi-channel) listener on the bus.

unsubscribe()

Unregister this object as a listener on the bus.

class cherrypy.process.plugins.ThreadManager(bus)

Bases: SimplePlugin

Manager for HTTP request threads.

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 publish to ‘start_thread’ and ‘stop_thread’ listeners in the bus as needed.

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.

acquire_thread()

Run ‘start_thread’ listeners for the current thread.

If the current thread has already been seen, any ‘start_thread’ listeners will not be run again.

graceful()

Release all threads and run all ‘stop_thread’ listeners.

release_thread()

Release the current thread and run ‘stop_thread’ listeners.

stop()

Release all threads and run all ‘stop_thread’ listeners.

threads = None

index number} pairs.

Type:

A map of {thread ident