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
|
Configuring Bazaar
==================
A configuration option has:
- a name: a valid python identifier (even if it's not used as an
identifier in python itself)
- a value: a unicode string
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 are needed to set or remove an option, ReadOnlySection should
be used otherwise.
Stores
------
Options can 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 a 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`` 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`` to provide additional context (the
``LocationSection`` add an ``extra_path`` attribute to implement the
``appendpath`` policy for example).
.. FIXME: Replace the appendpath example if/when it's deprecated ;)
|