« back to all changes in this revision
Viewing changes to doc/developers/configuration.txt
- browse files at revision 6378
- compare with another revision
- compare with revision 6079
- download diff
- download tarball
- view history from revision 6378
- Committer: Patch Queue Manager
- Date: 2011-12-15 18:38:46 UTC
- mfrom: (6362.3.2 config-explained)
- Revision ID: pqm@pqm.ubuntu.com-20111215183846-l332p0xr8hy0ekhf
(vila) More documentation about the new config implementation. (Vincent
Ladeuil)
Ladeuil)
added
removed
doc/developers/configuration.txt
4
4
.. contents::
5
5
:depth: 2
6
6
7
8
The short story
9
---------------
10
11
As a Bazaar developer there are three things you need to know about
12
configuration.
13
14
1. Get a value.
15
16
You construct or get a reference to a ConfigStack subclass that's relevant
17
to the context where you want to look up a value. For instance, given a
18
branch::
19
20
print branch.get_config_stack().get('log_format')
21
22
This will look up the stack through all relevant configuration sources.
23
The value returned is of the type declared for that Option and if nothing
24
is specifically declared you will get the default for that option.
25
26
2. Add a new option.
7
As a Bazaar developer there are a few things you need to know about
8
configuration:
9
10
* how to add a new option,
11
12
* how add a new stack,
13
14
* how add a new store.
15
16
The first sections in this document summarize the steps needed when adding a
17
new configuration item, the rest of the document gives more internal details
18
on how this is implemented.
19
20
Get an option value
21
-------------------
22
23
Options values are obtained with ``stack.get(option_name)`` where ``stack``
24
is one of the daughter classes of ``config.Stack``, see their docstrings for
25
a description of which sections are used from which stores.
26
27
The value returned is of the type declared for that ``Option`` and if
28
nothing is specifically declared you will get the default for that option.
29
30
Add a new option
31
----------------
27
32
28
33
You add a new ``Option`` to the ``option_registry``, either inside
29
``bzrlib/config.py`` or during initialization of your plugin. New plugins
30
should have systematic hierarchical names so that related values are grouped
31
together::
34
``bzrlib/config.py`` or during initialization of your plugin (use
35
``register_lazy`` in this case). New plugins should have systematic
36
hierarchical names so that related values are grouped together::
32
37
33
38
option_registry.register(
34
39
Option('dirstate.fdatasync', default=True,
35
40
from_unicode=bool_from_store,
36
41
help="Flush dirstate changes onto physical disk? ...."))
37
42
38
39
3. Old and new configuration code.
43
You then need to decide which stack is appropriate to implement the Option
44
policy:
45
46
* which config files (aka ``Store``) needs to be queried, which sections are
47
relevant and in what order,
48
49
* which section will receive the modifications (if relevant).
50
51
The docstrings for the existing stacks cover most of the known use cases.
52
53
Modify an option value or delete an option
54
------------------------------------------
55
56
Just reading an option is what is needed most of the time, modifying option
57
values or removing options is usually something that is not automated but
58
left to the user (with ``bzr config``).
59
60
Nevertheless, if you need to save a modified option value, use
61
``.set(option_name, value)`` and ``.remove(option_name)`` to delete the
62
option. Both methods are provided by the ``Stack`` object.
63
64
But before doing that, you must be sure that the stack you're using have a
65
writable section (this is true for ``GlobalStack`` which uses the
66
``DEFAULT`` section in ``bazaar.conf`` and for ``BranchStack``which uses the
67
no-name section in ``branch.conf``).
68
69
Old and new configuration code
70
------------------------------
40
71
41
72
There is (as of late 2011) some older and some newer configuration code. The
42
73
old code has specific methods for various checks or uses classes like
43
74
``GlobalConfig``. Don't add to to it; try to remove it.
44
75
76
If you encounter an option using the old code you may want to migrate
77
it. This generally involves:
78
79
* registering the option,
80
81
* replace the old config by a stack:
82
83
* ``GlobalConfig`` became ``GlobalStack``,
84
85
* ``LocationConfig`` became ``LocationStack``,
86
87
* ``BranchConfig`` became ``BranchStack`` (or in this case,
88
``get_config()`` became ``get_config_stack()``.
89
90
* replace the custom accessor calls with ``conf.get(option_name)``.
91
92
The new config code provides some help for commonly encountered use cases
93
that can allow further simplifications like:
94
95
* providing a default value when the option is not defined in any way by the
96
user,
97
98
* convert the unicode string provided by the user into a suitable
99
representation (integer, list, etc).
100
101
Adding a new stack
102
------------------
103
104
Stacks capture the various places an option can be declared by the user with
105
associated levels of generality and query them in the appropriate order
106
returning the first definition found. For example, the
107
``append_revisions_only`` option may be declared for all branches of a user
108
in ``bazaar.conf``, or for a hierarchy of branches in ``locations.conf`` or
109
in a single branch in ``branch.conf``.
110
111
Defining a new stack means you need a new way to expose these levels to the
112
user that is not covered by the existing stacks.
113
114
This is achieved by declaring:
115
116
* which stores can provide a value for the option,
117
118
* which sections apply to the stack instance, some filtering for a given
119
context can be defined,
120
121
* which (store, section) should receive the modifications.
122
123
Mapping different sections to different stacks is a powerful way to organize
124
the options and provide various levels of configuration to the user. This is
125
achieved with ``Store`` and ``SectionMatcher`` objects.
126
127
128
Adding a new store
129
------------------
130
131
132
133
The following stores are used by ``bzr`` in ways that illustrate various
134
uses of sections.
135
136
bazaar.conf
137
===========
138
139
``bzr`` itself defines two sections here:
140
141
* ``DEFAULT`` where global options are defined,
142
143
* ``ALIASES`` where command aliases are defined. This section is *not*
144
available via ``GlobalStack``, instead, the ``bzr alias`` command uses it
145
for its own purposes.
146
147
Plugins can define either additional options in the ``DEFAULT`` section or
148
new sections for their own needs (this is not especially encouraged
149
though). The ``bzr-bookmarks`` plugin defines a ``BOOKMARKS`` section there
150
for example.
151
152
pkgimport.conf
153
==============
154
155
The Ubuntu package importer defines a store and two stacks involving
156
``pkgimport.conf``. A no-name section contains the options common to all
157
packages and sections named after their corresponding package can also be
158
defined.
159
160
The ``ImporterStack`` uses ``locations.conf`` and the no-name section in
161
``pkgimport.conf`` for the importer options.
162
163
The ``PackageStack`` uses only ``pkgimport.conf`` and uses the section name
164
after the package followed by the no-name section.
165
166
location.conf
167
=============
168
169
``bzr`` defines sections corresponding to URLs there and includes the
170
relevant sections in ``LocationStack`` and ``BranchStack``. No no-name
171
section is recognized in this file.
172
173
branch.conf
174
===========
175
176
This file defines the option for a given branch and uses only the no-name
177
section.
178
45
179
Option
46
180
------
47
181
54
188
suitable value for the option. If the string cannot be coerced it should
55
189
return None.
56
190
57
* default: the default value that Stack.get() should return if no
58
value can be found for the option.
191
* default: the default value that Stack.get() should return if no value can
192
be found for the option. This can also be a callable as long as it returns
193
a unicode string.
59
194
60
195
* default_from_env: a list of environment variables. The first variable set
61
196
will provide a default value overriding 'default' which remains the
104
239
A ``Store`` can contain one or more sections, each section is uniquely
105
240
identified by a unicode string.
106
241
107
``config.ConfigObjStore`` is an implementation that use ``ConfigObj``.
242
``config.IniFileStore`` is an implementation that use ``ConfigObj``.
108
243
109
244
Depending on the object it is associated with (or not) a ``Store`` also needs
110
to implement a locking mechanism. ``LockableConfigObjStore`` implements such a
111
mechanism for ``ConfigObj`` based stores.
245
to implement a locking mechanism. ``LockableIniFileStore`` implements such a
246
mechanism for ``IniFileStore`` based stores.
112
247
113
248
Classes are provided for the usual Bazaar configuration files and could be
114
249
used as examples to define new ones if needed. The associated tests provides a
119
254
Filtering sections
120
255
------------------
121
256
122
For some contexts, only some sections from a given store will apply. Defining
123
which is what the ``SectionMatcher`` objects are about.
257
For some contexts, only some sections from a given store will apply. The
258
``SectionMatcher`` objects are used to define which sections in a store
259
apply to a given context.
124
260
125
261
The main constraint here is that a ``SectionMatcher`` should delay the loading
126
262
of the associated store as long as possible. The constructor should collect
130
266
Only ``ReadOnlySection`` objects are manipulated here but a
131
267
``SectionMatcher`` can return dedicated ``Section`` objects to provide
132
268
additional context (the ``LocationSection`` add an ``extra_path`` attribute
133
to implement the ``appendpath`` policy for example). If no sections match,
269
to implement the section local options for example). If no sections match,
134
270
an empty list is returned.
135
271
136
Options local to a section can also be defined for special purposes and be
272
Options local to a section can be defined for special purposes and be
137
273
handled by ``Section.get()``. One such option is ``relpath`` which is
138
274
defined in ``LocationSection`` as an alternative to the ``appendpath``
139
275
policy.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1