4.2.1. The BasicConfigGroup Class

For many of these functions, the API provides helper functions that handle the most common cases. These functions are provided as methods to the BasicConfigGroup class. Most front ends will need to merely create an instance of this class, or optionally inherit from it and create an instance of the derived class.

A BasicConfigGroup object presents the interface of a Python sequence, containing a set of configlets in priority-sorted order. This sequence is created by the constructor using a directory path; this directory is search for subdirectories containing configlets, and each configlet found is instantiated and added to the sequence. The directory defaults to /usr/share/configlets, which means that the group will instantiate all configlets installed in the standard location by default.

In addition to the normal sequence interface, BasicConfigGroup provides other helper methods which act on all configlets within the group. These will be described below.

4.2.2. Starting Configlets

All configlets must be started using the start_configlet function. It takes one argument: the directory in which the configlet resides. It returns a fully instantiated configlet object.

Configlets are only meant to be instantiated once. If start_configlet is called more than once for the same directory, it will return a reference to the object it created previously, rather than creating a new one.

If you use BasicConfigGroup, it uses start_configlet to start all of the configlets it finds. Thus, you do not need to call start_configlet yourself. Be aware, however, that the configlets in BasicConfigGroup have been created this way, and in particular cannot be "recreated" outside the group.

4.2.3. Interacting with Debconf

In order for the configlets to be useful, they need to be fed data from the debconf database, and they need to be able to feed changes back to debconf. The front end is responsible for doing this, using two classes from the API: the privileged runner classes and the DebConf class.

The privileged runner classes are intended to provide an interface for front ends to perform tasks as root. They have a simple interface: a run function, that takes the command to run as the only argument. No return value is provided; run will throw a RuntimeError exception if there is any problem running the command. Because the interface is so simple, the privileged runner classes do not inherit; a class only needs to provide a run method in order to be a privileged runner.

The API provides two privileged runner classes: SimplePrivilegedRunner and GnomeSudoPrivilegedRunner. The default privileged runner, SimplePrivilegedRunner, simply assumes that the front end already has root privileges and runs commands accordingly. GnomeSudoPrivilegedRunner uses the gnome-sudo command to obtain root to run the command; this provides a nice graphical password dialog to the user when root privilege is needed and caches the successful authentication for subsequent commands. See the gnome-sudo documentation for setting this up properly.

The DebConf class does the actual work of getting and setting the debconf information. A proper DebConf object for the version of debconf can be obtained by calling get_debconf, passing in the list of packages that the configlets configure. (This information can be retrieved by calling get_packages on the configlet, and calling get_packages on a BasicConfigGroup will get all of the packages configured by all of the configlets in the group.) As the DebConf class uses a privileged runner class to do its work, you should set an appropriate privileged runner class for it by calling the set_privileged_runner method, passing in the privileged runner object as an argument.

Once the DebConf object is set up, it provides three methods: get, set, and commit. The get method returns an array of strings containing the debconf data in the format the configlets need. The set method takes a similarly formatted array of strings as debconf data and sets it in the database. The commit method takes it upon itself to cause the configured packages to reread their debconf data and reconfigure themselves accordingly.

Once debconf information is read, it must be passed to the configlets. This is done by taking the data returned from the get method and passing it to the configlet's load_debconf method. The configlet will search through the data, finding the appropriate values it needs and saving them internally in some way.

Saving debconf information involves several more steps. First, all configlets must be told to prepare for shutdown; this is done with the on_gnome_close method. Then, call report_debconf on each configlet, merge the results into a single array of strings, and pass that array to DebConf's set method. Finally, call DebConf.commit to cause the packages to reconfigure.

The BasicConfigGroup class does much of this work for you. By calling the load_all_debconf method, you can cause the group to load the debconf information and send it to all of the configlets in the group. Similarly, the save_and_commit_all_debconf method will read all of the debconf information from the configlets, save it to the debconf database, and commit it. The BasicConfigGroup takes care of creating a DebConf object and managing it for you; you should, however, create an appropriate privileged runner and set it for the group by calling the group's set_privileged_runner method on it. As an alternative, you can get access to the group's DebConf object with the get_debconf method; you can then iterate across all of the configlets in the group to load or save data, or use the group's load_debconf and report_debconf methods, which do the iteration for you.