Another fundamental aspect of software systems is to provide a way to configure and customize them. Pluggdapps provide a wonderful configuration system. It is the responsibility of platform to gather configuration settings from various sources (like ini-files, data-base etc..) and make them available for plugins.
So how are these configuration settings related to a plugin ? Well, a plugin is nothing but a dictionary like object, whose (key,value) pairs are nothing but its configuration settings. If settings for a plugin is changed in the ini-file or in the data-base, it is automatically made available as a key,value inside the plugin. For example, pluggdapps.web.server.HTTPEPollServer plugin has configurable parameters like, host, port, backlog etc ... the settings are configured in the ini-file like,
1 2 3 4 | [plugin:HTTPEPollServer]
host = mysite.com
port = 80
backlog = 10
|
these settings are automatically made available inside the plugin (plugin is refered by self) logic like,
1 2 3 4 5 6 7 8 | class HTTPEPollServer( Pluing ):
...
def bind( args, kwargs ) :
...
sock.listen( self['backlog'] )
print( "Listening host and port, " % (self['host'], self['port']) )
...
...
|
From administrator’s point of view, platform configuration can be done via ini file(s) or through browser using pre-packaged application webadmin, which is mounted on the url like http://<hostname>:<port>/webadmin.
Pluggdapps is typically launched using a master configuration file. For instance, the following command provides a way to start the pluggdapps server with -c switch supplying master configuration file.
1 | $ pa-env/bin/pa -w -c etc/master.ini serve
|
master configuration file is expected to provide configuration parameters organized under two types of sections, special-section and plugin-section.
[DEFAULT] special section
The semantics of DEFAULT section is same as defined by configparser from python standard library. In short, the configured names and their corresponding values will be applicable to every other section defined in the configuration file and all the other configuration files refered by the master configuration file.
[pluggdapps] special section
Platform related configuration is expected to go under this section.
[mountloc] special section
This section is defined by Webapps platform. While using Pluggdapps platform this section is not supported. Administrators can mount web application instances on subdomains and script-paths. For Eg,
1 2 3 | [mountloc]
pluggdapps.com/webadmin = pluggdapps.webadmin, %(here)s/webadmin.ini
tayra.pluggdapps.com/ = pluggdapps.docroot, %(here)s/tayra.ini
|
The configuration name under [mountloc] section is nothing but url prefix on which a web-application instance is mounted. When a web-request enter the platform environment it is first resolved for the correct web-application under which the request must be handled. On the right hand side of the [mountloc] section a web-application is identified by its name and an optional configuration file, called application configuration file, shall override configuration settings for all plugins invoked under the webapp’s context, there by plugins can have different behaviour for each web-application.
Note that, application configuration file will accept only plugin sections and [DEFAULT] special-section. Any other section will be silently ignore.
plugin section
Every plugin can have its configuration settings organised under a separate section. The title of the section should look like,
[plugin:<package-name>.<plugin-name>]
<package-name>.<plugin-name> is called as the canonical name of plugin.
An example master configuration file,
master.ini
----------
[DEFAULT]
<option> = <value>
...
[pluggdapps]
<option> = <value>
...
[plugin:<packagename>.<pluginname>]
<option> = <value>
...
[plugin:<packagename>.<pluginname>]
...
Webadmin is a pluggdapps application pre-packaged along with pluggdapps-distribution. By default [mountloc] section in ./etc/master.ini will mount webadmin application as http://<hostname>/webadmin. It is possible to mount webadmin app on preferred subdomain/script-path. Like wise, administrators can access the configuration system through url - http://<hostname>/webadmin or from its mounted subdomain/script-path. Configured parameters will be persisted separately by a backend-stored, which by default will be sqlite3.
If you are using paenv environment to run pluggdapps platform, then configuration database is persisted in file - paenv/db/configdb.sqlite3.
If you are not intending to develop plugins for pluggdapps you should do good just by following previous explanations. In case you intend to develop plugins for pluggdapps, there are couple of more things you may need to know.
When a plugin class derives from pluggdapps.plugin.Plugin, which is how they become a plugin, it automatically implements an interface called pluggdapps.plugin.ISettings. This interface specifies a bunch of methods that handles configuration settings for the plugin class. While the platform is booted, the configuration settings are gathered from different sources, organised and normalized for plugins’ consumption. And when the plugins get instantiated (queried by query_*() methods), these settings are populated inside the plugin-dictionary.
The cute part about plugin configuration is that, configuration information, from various sources, are read, parsed aggregated and are automatically attached to plugin instances when they are instantiated by the platform. Like mentioned elsewhere plugin classes, although they are defined as regular python classes must be instantiated only by calling .query_plugin(), .query_plugins() or .query_pluginr() methods. Every plugin instance created by this way will have its configuration settings accessible as dictionary of key,value pairs on the plugin itself. That is, a plugin instance can be accessed like a dictionary, where the key name is the configuration name and the value return by the key-name is its settings-value.
Default configuration, every plugin classes deriving from Plugin base-classes automatically implements ISettings interface. This interface specifies that plugins can optionally implement ISettings.default_settings() method and ISettings.normalize_settings() method. When default_settings() method is called, it is expected to return a ConfigDict object which will define how a plugin can be configured.
If a plugin is configured in master ini file, then settings from master-ini file will override plugin’s default settings. If a plugin is also configured in application configuration file, referred under [mountloc] section, then settings from app-ini file will override both default settings and settings from master-ini file. Finally, settings from backend data-store will override settings from all the other sources.
Normalizing configuration, once configuration settings is gathered from various sources it will be aggregated for each plugin and passed on to plugin’s ISettings.normalize_settings() method, which can then apply data-conversion logic on the settings value and return a curated settings dictionary.
The normalized settings is preserved along with Interface and Plugin blue-prints until the system is shutdown.