`cement.ext.ext_reload_config`¶

WARNING: THIS EXTENSION IS EXPERIMENTAL

Experimental extension may (and probably will) change at any time. Please do not rely on these features until they are more fully vetted.

The Reload Config Framework Extension enables applications Built on Cement (tm) to easily reload configuration settings any time configuration files are modified without stopping/restarting the process.

Requirements¶

Python 2.6+, Python 3+

Python Modules: pyinotify

Linux (Kernel 2.6.13+)

Features¶

Application configuration files (CementApp.Meta.config_files) are reloaded if modified.

Application plugin configuration files (Anything found in (CementApp.Meta.plugin_config_dirs) are reloaded if modified.

The framework calls CementApp.config.parse_file() on any watched files once the kernel has signaled a modification.

New configurations settings are accessible via CementApp.config nearly immediately once the kernel (inotify) picks up the change.

Provides a pre_reload_config and post_reload_config hook so that applications can tie into the event and perform operations any time a configuration file is modified.

Asynchronously monitors configuration files for changes via inotify. Long running processes are not blocked by the operations performed when files are detected to be modified.

Limitations¶

Currently this extension only re-parses configuration files into the config handler. Some applications may need further work in-order to truly honor those changes. For example, if a configuration settings toggles something on or off, or triggers something else to happen (like making an API connection, etc)... this extension does not currently handle that, and it is left up to the application developer to tie into the events via the provided hooks.

Only available on Linux based systems.

Configuration¶

This extension does not currently honor any configuration settings.

Hooks¶

This extension defines the following hooks:

pre_reload_config¶

Run right before any framework actions are performed once modifications to any of the watched files are detected. Expects a single argument, which is the app object, and does not expect anything in return.

def my_pre_reload_config_hook(app):
    # do something with app?
    pass

post_reload_config¶

Run right after any framework actions are performed once modifications to any of the watched files are detected. Expects a single argument, which is the app object, and does not expect anything in return.

def my_post_reload_config_hook(app):
    # do something with app?
    pass

Usage¶

The following example shows how to add the reload_config extension, as well as perform an arbitrary action any time configuration changes are detected.

from time import sleep
from cement.core.exc import CaughtSignal
from cement.core.foundation import CementApp
from cement.core.controller import CementBaseController, expose

def print_foo(app):
    print "Foo => %s" % app.config.get('myapp', 'foo')

class Base(CementBaseController):
    class Meta:
        label = 'base'

    @expose(hide=True)
    def default(self):
        print('Inside Base.default()')

        # simulate a long running process
        while True:
            sleep(30)

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        base_controller = Base
        extensions = ['reload_config']


with MyApp() as app:
    # run this anytime the configuration has changed
    app.hook.register('post_reload_config', print_foo)

    try:
        app.run()
    except CaughtSignal as e:
        # maybe do something... but catch it regardless so app.close() is
        # called when exiting `with` cleanly.
        print(e)

The following would output something like the following when ~/.myapp.conf or any other configuration file is modified (spaces added for clarity):

Inside Base.default()


2015-05-05 03:00:32,023 (DEBUG) cement.ext.ext_reload_config : config
                                path modified: mask=IN_CLOSE_WRITE,
                                path=/home/vagrant/.myapp.conf
2015-05-05 03:00:32,023 (DEBUG) cement.core.config : config file
                                '/home/vagrant/.myapp.conf' exists,
                                loading settings...
2015-05-05 03:00:32,023 (DEBUG) cement.core.hook : running hook
                                'post_reload_config' (<function print_foo
                                at 0x7f1b52a5ab70>) from __main__
Foo => bar


2015-05-05 03:00:32,023 (DEBUG) cement.ext.ext_reload_config : config
                                path modified: mask=IN_CLOSE_WRITE,
                                path=/home/vagrant/.myapp.conf
2015-05-05 03:00:32,023 (DEBUG) cement.core.config : config file
                                '/home/vagrant/.myapp.conf' exists,
                                loading settings...
2015-05-05 03:00:32,023 (DEBUG) cement.core.hook : running hook
                                'post_reload_config' (<function print_foo
                                at 0x7f1b52a5ab70>) from __main__
Foo => bar2


2015-05-05 03:00:32,023 (DEBUG) cement.ext.ext_reload_config : config
                                path modified: mask=IN_CLOSE_WRITE,
                                path=/home/vagrant/.myapp.conf
2015-05-05 03:00:32,023 (DEBUG) cement.core.config : config file
                                '/home/vagrant/.myapp.conf' exists,
                                loading settings...
2015-05-05 03:00:32,023 (DEBUG) cement.core.hook : running hook
                                'post_reload_config' (<function print_foo
                                at 0x7f1b52a5ab70>) from __main__
Foo => bar3

cement.ext.ext_reload_config¶