4
A configuration option has:
6
- a name: a valid python identifier (even if it's not used as an
7
identifier in python itself)
9
- a value: a unicode string
14
Options are grouped into sections which share some properties with the well
17
- the key is the name,
18
- you can get, set and remove an option,
19
- the value is a unicode string.
21
MutableSection is needed to set or remove an option, ReadOnlySection should
27
Options can be persistent in which case they are saved into Stores.
29
``config.Store`` defines the abstract interface that all stores should
32
This object doesn't provide direct access to the options, it only provides
33
access to Sections. This is deliberate to ensure that sections can be
34
properly shared by reusing the same underlying objects. Accessing options
35
should be done via the ``Section`` objects.
37
A ``Store`` can contain one or more sections, each section is uniquely
38
identified by a unicode string.
40
``config.ConfigObjStore`` is an implementation that use ``ConfigObj``.
42
Depending on the object it is associated with (or not) a ``Store`` also needs
43
to implement a locking mechanism. ``LockableConfigObjStore`` implements such a
44
mechanism for ``ConfigObj`` based stores.
46
Classes are provided for the usual Bazaar configuration files and could be
47
used as examples to define new ones if needed. The associated tests provides a
48
basis for new classes which only need to register themselves in the right
49
places to inherit from the existing basic tests and add their own specific
55
For some contexts, only some sections from a given store will apply. Defining
56
which is what the ``SectionMatcher`` are about.
58
The main constraint here is that a ``SectionMatcher`` should delay the loading
59
of the associated store as long as possible. The constructor should collect
60
all data needed for the selection and uses it while processing the sections in
63
Only ``ReadOnlySection`` objects are manipulated here but a ``SectionMatcher``
64
can return dedicated ``Section`` to provide additional context (the
65
``LocationSection`` add an ``extra_path`` attribute to implement the
66
``appendpath`` policy for example).
68
.. FIXME: Replace the appendpath example if/when it's deprecated ;)
73
An option can take different values depending on the context it is used. Such
74
a context can involve configuration files, options from the command line,
75
default values in bzrlib and then some.
77
Such a context is implemented by creating a list of ``Section`` stacked upon
78
each other. A ``Stack`` can then be asked for an option value and returns the
79
first definition found.
81
This provides a great flexibility to decide priorities between sections when
82
the stack is defined without to worry about them in the code itself.
84
A stack also defines a mutable section (which can be None) to handle
87
Many sections (or even stores) are aimed at providing default values for an
88
option but these sections shouldn't be modified lightly as modifying an option
89
used for different contexts will indeed be seen by all these contexts.
91
Default values in configuration files are defined by users. Developers
92
shouldn't have to modify them, as such, no mechanism nor heuristics are used
93
to find which section (or sections) should be modified.
95
A ``Stack`` defines a mutable section when there is no ambiguity. If there
96
is one, then the *user* should be able to decide and in this case a new
97
``Stack`` can be created cheaply.
added
removed
doc/developers/configuration.txt
