As a Bazaar developer there are three things you need to know about configuration.
You construct or get a reference to a ConfigStack subclass that's relevant to the context where you want to look up a value. For instance, given a branch:
print branch.get_config_stack().get('log_format')
This will look up the stack through all relevant configuration sources. The value returned is of the type declared for that Option and if nothing is specifically declared you will get the default for that option.
You add a new Option to the option_registry, either inside bzrlib/config.py or during initialization of your plugin. New plugins should have systematic hierarchical names so that related values are grouped together:
option_registry.register(
Option('dirstate.fdatasync', default=True,
from_unicode=bool_from_store,
help="Flush dirstate changes onto physical disk? ...."))
There is (as of late 2011) some older and some newer configuration code. The old code has specific methods for various checks or uses classes like GlobalConfig. Don't add to to it; try to remove it.
The Option object is used to define its properties:
name: a name: a valid python identifier (even if it's not used as an identifier in python itself). This is also used to register the option.
from_unicode: a callable accepting a unicode string and returning a suitable value for the option. If the string cannot be coerced it should return None.
default: the default value that Stack.get() should return if no value can be found for the option.
default_from_env: a list of environment variables. The first variable set will provide a default value overriding 'default' which remains the default value if no environment variable is set.
help: a doc string describing the option, the first line should be a summary and can be followed by a blank line and a more detailed explanation. This will be displayed to the user with:
bzr help <option name>
invalid: the action to be taken when an invalid value is encountered in a store (during a Stack.get()).
The value of an option is a unicode string or None if it's not defined. By using from_unicode you can turn this string into a more appropriate representation (a list of unicode strings for example).
Options are grouped into sections which share some properties with the well known dict objects:
MutableSection is needed to set or remove an option, ReadOnlySection should be used otherwise.
Options can be persistent in which case they are saved into Stores.
config.Store defines the abstract interface that all stores should implement.
This object doesn't provide direct access to the options, it only provides access to Sections. This is deliberate to ensure that sections can be properly shared by reusing the same underlying objects. Accessing options should be done via the Section objects.
A Store can contain one or more sections, each section is uniquely identified by a unicode string.
config.ConfigObjStore is an implementation that use ConfigObj.
Depending on the object it is associated with (or not) a Store also needs to implement a locking mechanism. LockableConfigObjStore implements such a mechanism for ConfigObj based stores.
Classes are provided for the usual Bazaar configuration files and could be used as examples to define new ones if needed. The associated tests provides a basis for new classes which only need to register themselves in the right places to inherit from the existing basic tests and add their own specific ones.
For some contexts, only some sections from a given store will apply. Defining which is what the SectionMatcher objects are about.
The main constraint here is that a SectionMatcher should delay the loading of the associated store as long as possible. The constructor should collect all data needed for the selection and uses it while processing the sections in get_sections.
Only ReadOnlySection objects are manipulated here but a SectionMatcher can return dedicated Section objects to provide additional context (the LocationSection add an extra_path attribute to implement the appendpath policy for example). If no sections match, an empty list is returned.
Options local to a section can also be defined for special purposes and be handled by Section.get(). One such option is relpath which is defined in LocationSection as an alternative to the appendpath policy.
For appendpath, the LocationSection will carry extra_path as the relative path between the section name and the location used. relpath will be available as a Section local option with the same value. basename will carry the location base name and be available as a local option with the same name. Note that such options can only be expanded inside the section that defines them.
Specific section matchers can be implemented by overriding get_sections or just match.
bzrlib provides:
An option can take different values depending on the context it is used. This can involve configuration files, options from the command line, default values in bzrlib and then some.
Such a context is implemented by creating a list of Section stacked upon each other. A Stack can then be asked for an option value and returns the first definition found.
This provides a great flexibility to decide priorities between sections when the stack is defined without to worry about them in the code itself.
A stack also defines a mutable section (which can be None) to handle modifications.
Many sections (or even stores) are aimed at providing default values for an option but these sections shouldn't be modified lightly as modifying an option used for different contexts will indeed be seen by all these contexts.
Default values in configuration files are defined by users. Developers shouldn't have to modify them, as such, no mechanism nor heuristics are used to find which section (or sections) should be modified.
A Stack defines a mutable section when there is no ambiguity. If there is one, then the user should be able to decide and in this case a new Stack can be created cheaply.
Different stacks can be created for different purposes, the existing GlobalStack, LocationStack and BranchStack can be used as basis or examples. These classes are the only ones that should be used in code, Stores can be used to build them but shouldn't be used otherwise, ditto for sections. Again, the associated tests could and should be used against the created stacks.