# `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