PyQtConfig

PyQtConfig is a simple API for handling, persisting and synchronising configuration within PyQt applications.

Features

consistent interface to read values from widgets, always get and set
seamlessly handle conversion of types from QSettings strings
integrated mapping handles conversions between display and internal settings, e.g. nice text in combo boxes to integer values
save and load configuration via dict (to JSON) or XML
automatically generate a layout containing config items
BSD licensed

Introduction

The core of the API is a ConfigManager instance that holds configuration settings (either as a Python dict, or a QSettings instance) and provides standard methods to get and set values.

Configuration parameters can have Qt widgets attached as handlers. Once attached the widget and the configuration value will be kept in sync. Setting the value on the ConfigManager will update any attached widgets and changes to the value on the widget will be reflected immmediately in the ConfigManager. Qt signals are emitted on each update.

Default values can be set and will be returned transparently if a parameter remains unset. The current state of config can be saved and reloaded via XML or exported to a flat dict.

A small application has been included in PyQtConfig to demonstrate these features (interaction with widgets requires a running QApplication). Go to the pyqtconfig install folder and run it with:

cd pyqtconfig/examples
python demo.py

PyQtConfig can also auto-generate settings dialogs from Python dictionaries. To see an example run the second demo.

cd pyqtconfig/examples
python settings_dialog_demo.py

Simple usage (dictionary)

To store your settings you need to create a ConfigManager instance. This consists of a settings dictionary, a default settings dictionary and a number of helper functions to handle setting, getting and other functions.

from pyqtconfig import ConfigManager

config = ConfigManager()

config.set_defaults({
    'number': 13,
    'text': 'hello',
    'array': ['1','2'],
    'active': True,

})

Before values are set the default value will be returned when queried.

config.get('number')
13

config.set('number', 42)
config.get('number')
42

Simple usage (QSettings)

The QSettingsManager provides exactly the same API as the standard QConfigManager, the only difference is in the storage of values.

from pyqtconfig import QSettingsManager

settings = QSettingsManager()

settings.set('number', 42)
settings.set('text', "bla")
settings.set('array', ["a", "b"])
settings.set('active', True)

settings.get('number')
>> 42

Note: On some platforms, versions of Qt, or Qt APIs QSettings will return strings for all values which can lead to complicated code and breakage. However, PyQtConfig is smart enough to use the type of the config parameter in defaults to auto-convert returned values.

However, you do not have to set defaults manually. As of v0.7 default values are auto-set when attaching widgets (handlers) to the config manager if they're not already set.

From this point on we'll be referring to the ConfigManager class only, but all features work identically in QSettingsManager.

Adding widget handlers

So far we could have achieved the same thing with a standard Python dict/QSettings object. The real usefulness of PyQtConfig is in the ability to interact with QWidgets maintaining synchronisation between widgets and internal config, and providing a simple standard interface to retrieve values.

Note: It's difficult to demonstrate the functionality since you need a running QApplication to make it work, and you can't do that in the interactive interpreter. The examples that follow are contrived outputs that you would see if it were possible to do that. For a real example, see the demo included in the package.

lineEdit = QtGui.QLineEdit()
config.add_handler('text', lineEdit)

checkbox = QtGui.QCheckBox('active')
config.add_handler('active', checkbox)

The values of the widgets are automatically set to the pre-set defaults. Note that if we hadn't pre-set a default value the reverse would happen, and the default would be set to the value in the widget. This allows you to define the defaults in either way.

Next we'll change the value of both widgets.

We can read out the values of the widgets via the ConfigManager using the standard get interface rather than using the widget-specific access functions.

config.get('text')
>> 'hello'

config.get('active')
>> True

We can also update the widgets via the ConfigManager using set.

config.set('text', 'new value')
config.set('active', False)

Mapping

Sometimes you want to display a different value in a widget than you store in the configuration. The most obvious example would be in a combo box where you want to list nice descriptive names, but want to store short names or numbers in the configuration.

To enable this PyQtConfig allows a mapper to be defined when attaching a widget to a config. Mappers are provided as tuple of 2 functions set and get that each perform the conversion required when setting and getting the value from the widget. To simplify map creation however you can also specify the mapping as a dict and PyQtConfig will create the necessary lambdas behind the scenes.

CHOICE_A = 1
CHOICE_B = 2
CHOICE_C = 3
CHOICE_D = 4

map_dict = {
    'Choice A': CHOICE_A,
    'Choice B': CHOICE_B,
    'Choice C': CHOICE_C,
    'Choice D': CHOICE_D,
}

config.set_default('combo', CHOICE_C)
config.get('combo')
>> 3

comboBox = QtGui.QComboBox()
comboBox.addItems( map_dict.keys() )
config.add_handler('combo', comboBox, mapper=map_dict)

Note how the config is set to 3 (the value of CHOICE_C) but displays "Choice C" as text.

Supported Widgets

The following Qt-Widgets are supported:

QComboBox
QCheckBox
QAction
QActionGroup
QPushButton
QSpinBox
QDoubleSpinBox
QPlainTextEdit
QLineEdit
QListWidget
QSlider
QButtonGroup

There are also some additional hooks defined for non standard widgets. With

import pyqtconfig
print(pyqtconfig.HOOKS.keys())

you can obtain a list of all registered Widgets. Adding support for your own widget is also straight forward:

from pyqtconfig import ConfigManager

def _get_MyWidget(self):
    return self.myvalue

def _set_MyWidget(self, val):
    self.myvalue = val

def _event_MyWidget(self):
    return self.MyValueChanged

config = ConfigManager()
config.add_hooks('MyWidget', (_get_MyWidget, _set_MyWidget, _event_MyWidget))

Saving and loading data

QSettingsManager uses a QSettings object as a config store and so the saving of configuration is automatic through the Qt APIs. ConfigManager supports loading and saving of settings in a JSON file. To load settings from file, specify a filename on creation of the ConfigManager

config = ConfigManager(default_settings, filename="config/settings_config.json")

To save settings to file, use save()

config.save()

If you want to use your own approach to save and load your settings, you can output the stored data as a dict using as_dict()

config.as_dict()

This dict contains all values in the internal dictionary, with defaults used where values are not set. You can take this dict and set the defaults on a new ConfigManager to persist state.

config2 = ConfigManager()
config2.set_defaults( config.as_dict() )

config2.get('combo')
>> 3

You can also export and import data as XML. The two functions for handling XML import take an ElementTree root element and search for config settings under Config/ConfigSetting. This allows you to use PyQtConfig to write config into an XML file without worrying about the format.

import ElementTree as et

config.set('combo', CHOICE_D)

root = et.Element("MyXML")
root = config.getXMLConfig( root )

config2.setXMLConfig(root)
config2.get('combo')
>> 4

Generating a Config Dialog

pyqtconfig has the ability to automatically generate a dialog populated with the contents of a ConfigManager. The following code shows how this is done from the context of a QMainWindow class. (see the examples for the full code)

        config_dialog = ConfigDialog(self.config, self, cols=2)
        config_dialog.setWindowTitle("Settings")
        config_dialog.accepted.connect(lambda: self.update_config(config_dialog.config))
        config_dialog.exec()

Below is an example of the generated Dialog:

Metadata

To make it easier to work with multiple config items, especially when using the auto-generated config dialog, you can define some of the behavior of config items using metadata. Metadata are properties attached to each config item, and can be defined using a dict. For example, the defaults and metadata used to define the settings for the above dialog:

default_settings = {
    "Setting 1": "Hello",
    "Setting 2": 25,
    "Setting 3": 12.5,
    "Setting 4": False,
}

default_settings_metadata = {
    "Setting 2": {
        "preferred_handler": QtWidgets.QComboBox,
        "preferred_map_dict": {
            "Choice A": 25,
            "Choice B": 26,
            "Choice C": 27
        }
    },
    "Setting 3": {
        "prefer_hidden": True
    }
}

These are set using the set_many_metadata method

config.set_many_metadata(default_settings_metadata)

Metadata are defined for a config item through a metadata dict item with a matching key (e.g. "Setting 2" in config is controlled by "Setting 2" in metadata). "preferred_handler" sets the type that will be used by add_handler if none is passed as an argument. (e.g. during creation of a ConfigDialog). "preferred_map_dict" is used in the same way. If "prefer_hidden" is set to True, it will not be added to a ConfigDialog. You can also get the list of config items that do not have "prefer_hidden" set to true using get_visible_keys()

Acknowledgements

Thanks to Pirmin Kalberer for starting this documentation that I had forgot about entirely.

Bug reports and pull-requests are most welcome.

pythonguis/pyqtconfig