As a Breezy developer there are a few things you need to know about configuration:
how to add a new option,
how add a new stack,
how add a new store.
The first sections in this document summarize the steps needed when adding a new configuration item, the rest of the document gives more internal details on how this is implemented.
Options values are obtained with
is one of the daughter classes of
config.Stack, see their docstrings for
a description of which sections are used from which stores.
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
breezy/config.py or during initialization of your plugin (use
register_lazy in this case). 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? ...."))
You then need to decide which stack is appropriate to implement the Option policy:
which config files (aka
Store) needs to be queried, which sections are relevant and in what order,
which section will receive the modifications (if relevant).
The docstrings for the existing stacks cover most of the known use cases.
Just reading an option is what is needed most of the time, modifying option
values or removing options is usually something that is not automated but
left to the user (with
Nevertheless, if you need to save a modified option value, use
.set(option_name, value) and
.remove(option_name) to delete the
option. Both methods are provided by the
But before doing that, you must be sure that the stack you’re using have a
writable section (this is true for
GlobalStack which uses the
DEFAULT section in
breezy.conf and for
BranchStack``which uses the
no-name section in ``branch.conf).
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.
If you encounter an option using the old code you may want to migrate it. This generally involves:
registering the option,
replace the old config by a stack:
BranchStack(or in this case,
replace the custom accessor calls with
The new config code provides some help for commonly encountered use cases that can allow further simplifications like:
providing a default value when the option is not defined in any way by the user,
convert the unicode string provided by the user into a suitable representation (integer, list, etc).
If you start migrating a given option to the config stacks, don’t stop mid-way, all its uses should be covered (tests included). There are some edge cases where updates via one API will be not be seen by the other API (see http://pad.lv/948339 and http://pad.lv/948344 for details). Roughly, the old API always trigger an IO while the new one cache values to avoid them. This works fine as long as a given option is handled via a single API.
Stacks capture the various places an option can be declared by the user with
associated levels of generality and query them in the appropriate order
returning the first definition found. For example, the
append_revisions_only option may be declared for all branches of a user
breezy.conf, or for a hierarchy of branches in
in a single branch in
Defining a new stack means you need a new way to expose these levels to the user that is not covered by the existing stacks.
This is achieved by declaring:
which stores can provide a value for the option,
which sections apply to the stack instance, some filtering for a given context can be defined,
which (store, section) should receive the modifications.
Mapping different sections to different stacks is a powerful way to organize
the options and provide various levels of configuration to the user. This is
The following stores are used by
brz in ways that illustrate various
uses of sections.
brz itself defines two sections here:
DEFAULTwhere global options are defined,
ALIASESwhere command aliases are defined. This section is not available via
GlobalStack, instead, the
brz aliascommand uses it for its own purposes.
Plugins can define either additional options in the
DEFAULT section or
new sections for their own needs (this is not especially encouraged
bzr-bookmarks plugin defines a
BOOKMARKS section there
brz defines sections corresponding to URLs there and includes the
relevant sections in
BranchStack. No no-name
section is recognized in this file.
This file defines the option for a given branch and uses only the no-name section.
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.
override_from_env: a list of environment variables. The first variable set will be used as the option value overriding any other definition of the option.
default: the default value that Stack.get() should return if no value can be found for the option. This can also be a callable as long as it returns a unicode string.
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:
brz 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
If you need a list value, you should use
For options that take their values from a
RegistryOption can be used. This will automatically take care of
looking up the specified values in the dictionary and documenting the
possible values in help.
Options are grouped into sections which share some properties with the well known dict objects:
the key is the name,
you can get, set and remove an option,
the value is a unicode string.
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
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
Store can contain one or more sections, each section is uniquely
identified by a unicode string.
config.IniFileStore is an implementation that use
Depending on the object it is associated with (or not) a
Store also needs
to implement a locking mechanism.
LockableIniFileStore implements such a
IniFileStore based stores.
Classes are provided for the usual Breezy 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.
Store defines how option values are stored, this includes:
defining the sections where the options are grouped,
defining how the values are quoted/unquoted for storage purposes. Stacks use the unquoted values internally (default value handling and option expansion are simpler this way) and
brz configquote them when they need to be displayed.
For some contexts, only some sections from a given store will apply. The
SectionMatcher objects are used to define which sections in a store
apply to a given context.
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
ReadOnlySection objects are manipulated here but a
SectionMatcher can return dedicated
Section objects to provide
additional context (the
LocationSection add an
to implement the section local options for example). If no sections match,
an empty list is returned.
Options local to a section can be defined for special purposes and be
Section.get(). One such option is
relpath which is
LocationSection as an alternative to the
LocationSection will carry
extra_path as the
relative path between the section name and the location used.
will be available as a
Section local option with the same
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
NameMatcher(store, unique_id): To select a single section matching
LocationMatcher(store, location): To select all sections that match
locationsorted by decreasing number of path components.
StartingPathMatcher(store, location): To select all sections that match
locationin the order they appear in the
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 breezy 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.
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
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
Also note that
MemoryStack can be used without any disk resources which
allows for simpler and faster tests. A common pattern is to accept a
config parameter related to a given feature and test it with predefined
configurations without involving the whole
breezy.tests.test_smtp_connection are good examples.