1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
Configuring Bazaar
==================
.. contents::
:depth: 2
The short story
---------------
As a Bazaar developer there are three things you need to know about
configuration.
1. Get a value.
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.
2. Add a new 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? ...."))
3. Old and new configuration code.
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.
Option
------
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).
Sections
--------
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.
Stores
------
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.
Filtering sections
------------------
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:
* ``LocationMatcher(store, location)``: To select all sections that match
``location``.
* ``NameMatcher(store, unique_id)``: To select a single section matching
``unique_id``.
Stacks
------
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.
|