DISCLAIMER: This is a total hack and may or may not serve you needs. I give various suggestions for expanding the example though, so I hope it’s helpful!

Now that that’s out of the way, let’s create a super simple configuration file. We’ll call it “config.ini” for convenience’s sake:

config.ini

server = Update Server:
username = Username:
password = Password:
update interval = Update Interval:
agency = Agency Filter:
filters = ""
 
[Values]
server = http://www.someCoolWebsite/hackery.php
username = ""
password = ""
update interval = 2
agency_choices = Include all agencies except, Include all agencies except, Exclude all agencies except
filters = ""

This configuration file has two sections: Labels and Values. The Labels section has the labels we will use to create wx.StaticText controls with. The Values section has some sample values we can use for the corresponding text control widgets and one combo box. Note that the agency_choices field is a list. The first item in the list will be the default option in the combo box and the other two items are the real contents of the widget.

Now let’s take a look at the code that will build the dialog:

preferencesDlg.py

import configobj
import wx
 
########################################################################
class PreferencesDialog(wx.Dialog):
    """
    Creates and displays a preferences dialog that allows the user to
    change some settings.
    """
 
    #----------------------------------------------------------------------
    def __init__(self):
        """
        Initialize the dialog
        """
        wx.Dialog.__init__(self, None, wx.ID_ANY, 'Preferences', size=(550,300))
        self.createWidgets()
 
    #----------------------------------------------------------------------
    def createWidgets(self):
        """
        Create and layout the widgets in the dialog
        """
        lblSizer = wx.BoxSizer(wx.VERTICAL)
        valueSizer = wx.BoxSizer(wx.VERTICAL)
        btnSizer = wx.StdDialogButtonSizer()
        colSizer = wx.BoxSizer(wx.HORIZONTAL)
        mainSizer = wx.BoxSizer(wx.VERTICAL)
 
        iniFile = "config.ini"
        self.config = configobj.ConfigObj(iniFile)
 
        labels = self.config["Labels"]
        values = self.config["Values"]
        self.widgetNames = values
        font = wx.Font(12, wx.SWISS, wx.NORMAL, wx.BOLD)
 
        for key in labels:
            value = labels[key]
            lbl = wx.StaticText(self, label=value)
            lbl.SetFont(font)
            lblSizer.Add(lbl, 0, wx.ALL, 5)
 
        for key in values:
            print key
            value = values[key]
            if isinstance(value, list):
                default = value[0]
                choices = value[1:]
                cbo = wx.ComboBox(self, value=value[0],
                                  size=wx.DefaultSize, choices=choices,
                                  style=wx.CB_DROPDOWN|wx.CB_READONLY,
                                  name=key)
                valueSizer.Add(cbo, 0, wx.ALL, 5)
            else:
                txt = wx.TextCtrl(self, value=value, name=key)
                valueSizer.Add(txt, 0, wx.ALL|wx.EXPAND, 5)
 
        saveBtn = wx.Button(self, wx.ID_OK, label="Save")
        saveBtn.Bind(wx.EVT_BUTTON, self.onSave)
        btnSizer.AddButton(saveBtn)
 
        cancelBtn = wx.Button(self, wx.ID_CANCEL)
        btnSizer.AddButton(cancelBtn)
        btnSizer.Realize()
 
        colSizer.Add(lblSizer)
        colSizer.Add(valueSizer, 1, wx.EXPAND)
        mainSizer.Add(colSizer, 0, wx.EXPAND)
        mainSizer.Add(btnSizer, 0, wx.ALL | wx.ALIGN_RIGHT, 5)
        self.SetSizer(mainSizer)
 
    #----------------------------------------------------------------------
    def onSave(self, event):
        """
        Saves values to disk
        """
        for name in self.widgetNames:
            widget = wx.FindWindowByName(name)
            if isinstance(widget, wx.ComboBox):
                selection = widget.GetValue()
                choices = widget.GetItems()
                choices.insert(0, selection)
                self.widgetNames[name] = choices
            else:
                value = widget.GetValue()
                self.widgetNames[name] = value
        self.config.write()
        self.EndModal(0)
 
########################################################################
class MyApp(wx.App):
    """"""
 
    #----------------------------------------------------------------------
    def OnInit(self):
        """Constructor"""
        dlg = PreferencesDialog()
        dlg.ShowModal()
        dlg.Destroy()
 
        return True
 
if __name__ == "__main__":
    app = MyApp(False)
    app.MainLoop()

To start, we subclass a wx.Dialog and all its createWidgets method. This method will read our config file and use the data therein to create the display. Once the config is read, we loop over the keys in the Labels section and create static text controls as needed. Next, we loop over the values in the other section and use a conditional to check the type of widget. In this case, we only care about wx.TextCtrl and wx.Combobox. This is where ConfigObj helps since it actually can typecast some of the entries in our configuration file. If you use a configspec, you can get even more granular and that may be the way you’ll want to go to extend this tutorial. Note that for the text controls and combo box, I set the name field. This is important for saving the data, which we’ll be seeing in just a moment.

Anyway, in both loops, we use vertical BoxSizers to hold our widgets. You may want to swap this for a GridBagSizer or FlexGridSizer for your specialized interface. I personally really like BoxSizers. I also used a StdDialogButtonSizer for the buttons at the suggestion of Steven Sproat (Whyteboard). If you use the correct standard ids for the buttons, this sizer will place them in the right order in a cross-platform way. It’s quite handy, although it doesn’t take many arguments. Also note that the documentation for this sizer implies you can specify the orientation, but you really cannot. I spoke with Robin Dunn (creator of wxPython) about this issue on IRC and he said that epydoc was grabbing the wrong docstring.

The next method that we care about is onSave. Here is where we save whatever the user has entered. Earlier in the program, I grabbed the widget names from the configuration and we loop over those now. We call wx.FindWindowByName to find the widget by name. Then we use isinstance again to check what kind of widget we have. Once that’s done, we grab the value that the widget holds using GetValue and assign that value to the correct field in our configuration. When the loop finishes, we write the data to disk. Immediate improvement alert: I have no validation here at all! This is something for you to do to extend this example. The last step is to call EndModal(0) to close the dialog and, in turn, the application.

Now you know the basics of generating a dialog from a configuration file. I think using some kind of dictionary with widget type names (probably in strings) might be an easy way to make this script work with other widgets. Use your imagination and let me know what you come up with.

Note: All code tested on Windows XP with Python 2.5, ConfigObj 4.6.0, and Validate 1.0.0.

Further Reading

• ConfigObj Tutorial
• XRC and wxPython
• wx.Dialog

  Documentation

Downloads

• dialog_from_config.zip
• dialog_from_config.tar

First we’ll create a simple controller for creating and accessing our configuration file with ConfigObj:

import configobj
import os
import sys
import wx
from wx.lib.buttons import GenBitmapTextButton
 
appPath = os.path.abspath(os.path.dirname(os.path.join(sys.argv[0])))
inifile = os.path.join(appPath, "example.ini")
 
########################################################################
class CloseBtn(GenBitmapTextButton):
    """
    Creates a reusuable close button with a bitmap
    """
 
    #----------------------------------------------------------------------
    def __init__(self, parent, label="Close"):
        """Constructor"""
        font = wx.Font(16, wx.SWISS, wx.NORMAL, wx.BOLD)
        img = wx.Bitmap(r"%s\images\cancel.png" % appPath)
        GenBitmapTextButton.__init__(self, parent, wx.ID_CLOSE, img,
                                     label=label, size=(110, 50))
        self.SetFont(font)
 
#----------------------------------------------------------------------
def createConfig():
    """
    Create the configuration file
    """
    config = configobj.ConfigObj()
    config.filename = inifile
    config['update server'] = "http://www.someCoolWebsite/hackery.php"
    config['username'] = ""
    config['password'] = ""
    config['update interval'] = 2
    config['agency filter'] = 'include'
    config['filters'] = ""
    config.write()
 
#----------------------------------------------------------------------
def getConfig():
    """
    Open the config file and return a configobj
    """
    if not os.path.exists(inifile):
        createConfig()
    return configobj.ConfigObj(inifile)

This piece of code is pretty straightforward. In the createConfig function, it creates an “example.ini” file in the same directory as the one that this script is run from. The config file gets six fields, but no sections. In the getConfig function, the code checks for the existence of the configuration file and creates it if it does not exist. Regardless, the function returns a ConfigObj object to the caller. We’ll put this script into “controller.py”. Now we’ll subclass the wx.Dialog class to create a preferences dialog.

# -----------------------------------------------------------
# preferencesDlg.py
#
# Created 10/20/2009 by mld
# -----------------------------------------------------------
 
import controller
import wx
from wx.lib.buttons import GenBitmapTextButton
 
########################################################################
class PreferencesDialog(wx.Dialog):
    """
    Creates and displays a preferences dialog that allows the user to
    change some settings.
    """
 
    #----------------------------------------------------------------------
    def __init__(self):
        """
        """
        wx.Dialog.__init__(self, None, wx.ID_ANY, 'Preferences', size=(550,300))
        appPath = controller.appPath
 
        # ---------------------------------------------------------------------
        # Create widgets
        font = wx.Font(12, wx.SWISS, wx.NORMAL, wx.BOLD)
        serverLbl = wx.StaticText(self, wx.ID_ANY, "Update Server:")
        self.serverTxt = wx.TextCtrl(self, wx.ID_ANY, "")
        self.serverTxt.Disable()
 
        usernameLbl = wx.StaticText(self, wx.ID_ANY, "Username:")
        self.usernameTxt = wx.TextCtrl(self, wx.ID_ANY, "")
        self.usernameTxt.Disable()
 
        passwordLbl = wx.StaticText(self, wx.ID_ANY, "Password:")
        self.passwordTxt = wx.TextCtrl(self, wx.ID_ANY, "", style=wx.TE_PASSWORD)
        self.passwordTxt.Disable()
 
        updateLbl = wx.StaticText(self, wx.ID_ANY, "Update Interval:")
        self.updateTxt = wx.TextCtrl(self, wx.ID_ANY, "")
        minutesLbl = wx.StaticText(self, wx.ID_ANY, "minutes")
 
        agencyLbl = wx.StaticText(self, wx.ID_ANY, "Agency Filter:")
        choices = ["Include all agencies except", "Exclude all agencies except"]
        self.agencyCbo = wx.ComboBox(self, wx.ID_ANY, "Include all agencies except",
                                     None, wx.DefaultSize, choices, wx.CB_DROPDOWN|wx.CB_READONLY)
        self.agencyCbo.SetFont(font)
        self.filterTxt = wx.TextCtrl(self, wx.ID_ANY, "")
 
        img = wx.Bitmap(r"%s/images/filesave.png" % appPath)
        saveBtn = GenBitmapTextButton(self, wx.ID_ANY, img, "Save", size=(110, 50))
        saveBtn.Bind(wx.EVT_BUTTON, self.savePreferences)
        cancelBtn = controller.CloseBtn(self, label="Cancel")
        cancelBtn.Bind(wx.EVT_BUTTON, self.onCancel)
 
        widgets = [serverLbl, usernameLbl, passwordLbl, updateLbl, agencyLbl, minutesLbl,
                   self.serverTxt, self.usernameTxt, self.passwordTxt, self.updateTxt,
                   self.agencyCbo, self.filterTxt, saveBtn, cancelBtn]
        for widget in widgets:
            widget.SetFont(font)
 
        # ---------------------------------------------------------------------
        # layout widgets
        mainSizer = wx.BoxSizer(wx.VERTICAL)
        updateSizer = wx.BoxSizer(wx.HORIZONTAL)
        btnSizer = wx.BoxSizer(wx.HORIZONTAL)
        prefSizer = wx.FlexGridSizer(cols=2, hgap=5, vgap=5)
        prefSizer.AddGrowableCol(1)
 
        prefSizer.Add(serverLbl, 0, wx.ALIGN_LEFT | wx.ALIGN_CENTER_VERTICAL)
        prefSizer.Add(self.serverTxt, 0, wx.EXPAND)
        prefSizer.Add(usernameLbl, 0, wx.ALIGN_LEFT | wx.ALIGN_CENTER_VERTICAL)
        prefSizer.Add(self.usernameTxt, 0, wx.EXPAND)
        prefSizer.Add(passwordLbl, 0, wx.ALIGN_LEFT | wx.ALIGN_CENTER_VERTICAL)
        prefSizer.Add(self.passwordTxt, 0, wx.EXPAND)
        prefSizer.Add(updateLbl, 0, wx.ALIGN_LEFT | wx.ALIGN_CENTER_VERTICAL)
        updateSizer.Add(self.updateTxt, 0, wx.RIGHT, 5)
        updateSizer.Add(minutesLbl, 0, wx.ALIGN_LEFT | wx.ALIGN_CENTER_VERTICAL)
        prefSizer.Add(updateSizer)
        prefSizer.Add(agencyLbl, 0, wx.ALIGN_LEFT | wx.ALIGN_CENTER_VERTICAL)
        prefSizer.Add(self.agencyCbo, 0, wx.EXPAND)
        prefSizer.Add((20,20))
        prefSizer.Add(self.filterTxt, 0, wx.EXPAND)
 
        mainSizer.Add(prefSizer, 0, wx.EXPAND|wx.ALL, 5)
        btnSizer.Add(saveBtn, 0, wx.ALL, 5)
        btnSizer.Add(cancelBtn, 0, wx.ALL, 5)
        mainSizer.Add(btnSizer, 0, wx.ALL | wx.ALIGN_RIGHT, 10)
        self.SetSizer(mainSizer)
 
        # ---------------------------------------------------------------------
        # load preferences
        self.loadPreferences()
 
    #----------------------------------------------------------------------
    def loadPreferences(self):
        """
        Load the preferences and fill the text controls
        """
        config = controller.getConfig()
        updateServer = config['update server']
        username = config['username']
        password = config['password']
        interval = config['update interval']
        agencyFilter = config['agency filter']
        filters = config['filters']
 
        self.serverTxt.SetValue(updateServer)
        self.usernameTxt.SetValue(username)
        self.passwordTxt.SetValue(password)
        self.updateTxt.SetValue(interval)
        self.agencyCbo.SetValue(agencyFilter)
        self.filterTxt.SetValue(filters)
 
    #----------------------------------------------------------------------
    def onCancel(self, event):
        """
        Closes the dialog
        """
        self.EndModal(0)
 
    #----------------------------------------------------------------------
    def savePreferences(self, event):
        """
        Save the preferences
        """
        config = controller.getConfig()
 
        config['update interval'] = self.updateTxt.GetValue()
        config['agency filter'] = str(self.agencyCbo.GetValue())
        data = self.filterTxt.GetValue()
        if "," in data:
            filters = [i.strip() for i in data.split(',')]
        elif " " in data:
            filters = [i.strip() for i in data.split(' ')]
        else:
            filters = [data]
        text = ""
        for f in filters:
            text += " " + f
        text = text.strip()
        config['filters'] = text
        config.write()
 
        dlg = wx.MessageDialog(self, "Preferences Saved!", 'Information',
                               wx.OK|wx.ICON_INFORMATION)
        dlg.ShowModal()
        self.EndModal(0)
 
if __name__ == "__main__":
    app = wx.PySimpleApp()
    dlg = PreferencesDialog()
    dlg.ShowModal()
    dlg.Destroy()

The code above creates a basic preferences dialog and loads its configuration from a file using ConfigObj. You can see how that works by reading the code in the loadPreferences method. The only other piece that we care about is how the code saves the preferences when the user changes them. For that, we need to look at the savePreferences method. This is a pretty straightforward method in that all it does is grab the various values from the widgets using wx’s specific getter functions. There’s also a conditional that does some minor checking on the filter field. The main reason for that is that in my original program, I use a space as the delimiter and the program needed to convert commas and such to spaces. This code is still a work in progress though as it does not cover all the cases that a user could enter.

Anyway, once we have the values inside the ConfigObj’s dict-like interface, we write the ConfigObj instance’s data to file. Then the program displays a simple dialog to let the user know that’s saved.

Now, let’s say that our program’s specifications change such that we need to add or remove a preference. All that is required to do so is to add or delete it in the configuration file. ConfigObj will pick up the changes and we just need to remember to add or remove the appropriate widgets in our GUI. One of the best things about ConfigObj is that it won’t reset the data in your file, it will just add the changes as appropriate. Give it a try and find out just how easy it is!

Note: All code tested on Windows XP with Python 2.5, ConfigObj 4.6.0, and Validate 1.0.0.

Downloads

• ConfigObj-GUI-Ex.zip
• ConfigObj-GUI-Ex.tar

Getting Started

First of all you will need to download ConfigObj. Once you have that downloaded and installed, we can continue. Got it? Then let’s see what it can do!

To start off, open a text editor and create a file with some contents like this:


product = Sony PS3
accessories = controller, eye, memory stick
# This is a comment that will be ignored
retail_price = $400


Save it where ever you like. I’m going to call mine “config.ini”. Now let’s see how ConfigObj can be used to extract that information:


>>> from configobj import ConfigObj
>>> config = ConfigObj(r"path to config.ini")
>>> config["product"]
'Sony PS3'
>>> config["accessories"]
['controller', 'eye', 'memory stick']
>>> type(config["accessories"])
<type 'list'>


As you can see, ConfigObj uses Python’s dict API to access the information it has extracted. All you had to do to get ConfigObj to parse the file was to pass the file’s path to ConfigObj. Now, if the information had been under a section (i.e. [Sony]), then you would have had to do pre-pend everything with ["Sony"], like this: config["Sony"]["product"]. Also take note that the “accessories” section was returned as a list of strings. ConfigObj will take any valid line with a comma-separated list and return it as a Python list. You can also create multi-line strings in the config file as long as you enclose them with triple single or double quotes.

If you need to create a sub-section in the file, then use extra square brackets. For example, [Sony] is the top section, [[Playstation]] is the sub-section and [[[PS3]]] is the sub-section of the sub-section. You can create sub-sections up to any depth. For more information on the formatting of the file, I recommend the documentation linked to above.

Now we’ll do the reverse and create the config file programmatically.

import configobj
 
def createConfig(path):
    config = configobj.ConfigObj()
    config.filename = path
    config["Sony"] = {}
    config["Sony"]["product"] = "Sony PS3"
    config["Sony"]["accessories"] = ['controller', 'eye', 'memory stick']
    config["Sony"]["retail price"] = "$400"
    config.write()

As you can see, all it took was 8 lines of code. In the code above, we create a function and pass it the path for our config file. Then we create a ConfigObj object and set its filename property. To create the section, we create an empty dict with the name “Sony”. Then we pre-pend each line of the sections contents in the same way. Finally, we call our config object’s write method to write the data to the file.

Using a configspec

ConfigObj also provides a way to validate your configuration files using a configspec. When I mentioned that I was going to write this article, Steven Sproat (creator of Whyteboard) volunteered his configspec code as an example. I took his specification and used it to create a default config file. In this example, we use Foord’s validate module to do the validation. I don’t think it’s included in your ConfigObj download, so you may need to download it as well. Now, let’s take a look at the code:

import configobj, validate
 
cfg = """
bmp_select_transparent = boolean(default=False)
canvas_border = integer(min=10, max=35, default=15)
colour1 = list(min=3, max=3, default=list('280', '0', '0'))
colour2 = list(min=3, max=3, default=list('255', '255', '0'))
colour3 = list(min=3, max=3, default=list('0', '255', '0'))
colour4 = list(min=3, max=3, default=list('255', '0', '0'))
colour5 = list(min=3, max=3, default=list('0', '0', '255'))
colour6 = list(min=3, max=3, default=list('160', '32', '240'))
colour7 = list(min=3, max=3, default=list('0', '255', '255'))
colour8 = list(min=3, max=3, default=list('255', '165', '0'))
colour9 = list(min=3, max=3, default=list('211', '211', '211'))
convert_quality = option('highest', 'high', 'normal', default='normal')
default_font = string
default_width = integer(min=1, max=12000, default=640)
default_height = integer(min=1, max=12000, default=480)
imagemagick_path = string
handle_size = integer(min=3, max=15, default=6)
language = option('English', 'English (United Kingdom)', 'Russian', 'Hindi', default='English')
print_title = boolean(default=True)
statusbar = boolean(default=True)
toolbar = boolean(default=True)
toolbox = option('icon', 'text', default='icon')
undo_sheets = integer(min=5, max=50, default=10)
"""
 
def createConfig(path):
    """
    Create a config file using a configspec
    and validate it against a Validator object
    """
    spec = cfg.split("\n")
    config = configobj.ConfigObj(path, configspec=spec)
    validator = validate.Validator()
    config.validate(validator, copy=True)
    config.filename = path
    config.write()
 
if __name__ == "__main__":
    createConfig("config.ini")

If you go and look at Steven’s original configspec, you’ll notice I shortened his list of languages quite a bit. I did this to make the code easier to read. Anyway, the configspec allows the programmer the ability to specify what types are returned for each line in the configuration file. It also can be used to set a default value and a min and max values (among other things). If you run the code above, you will see a “config.ini” file generated in the current working directory that has just the default values. If the programmer didn’t specify a default, then that line isn’t even added to the configuration.

Let’s take a closer look at what’s going on just to make sure you understand. In the createConfig function, we create a ConfigObj method be passing in the file path and setting the configspec. Note that the configspec can also be a normal text file or a python file rather than the string that is in this example. Next, we create a Validator object. Normal usage is to just call config.validate(validator), but in this code I set the copy argument to True so that I could create a file. Otherwise, all it would do is validate that the file I passed in fit the configspec’s rules. Finally I set the config’s filename and write the data out.

Wrapping Up

Now you know just enough to get you started on the ins and outs of ConfigObj. I hope you’ll find it as helpful as I have. There’s lots more to learn, so be sure to check out some of the links below.

Note: All code tested on Windows XP with Python 2.5, ConfigObj 4.6.0, and Validate 1.0.0.

Further Reading

• ConfigObj Official Documentation
• Validate Official Documentation
• Michael Foord’s ConfigObj Tutorial

Download the Source

• configObjTut.zip
• configObjTut.tar