/brz/remove-bazaar : contents of doc/developers/configuration.txt at revision 5743.2.31

: (revision 5743.2.31)

To get this branch, use:

bzr branch
http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

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 ;)

5743.3.7 by Vincent Ladeuil Add some documentation about option and sections.	1	Configuring Bazaar
	2	==================
	3
	4	A configuration option has:
	5
	6	- a name: a valid python identifier (even if it's not used as an
	7	identifier in python itself)
	8
	9	- a value: a unicode string
	10
	11	Sections
	12	--------
	13
	14	Options are grouped into sections which share some properties with the well
	15	known dict objects:
	16
	17	- the key is the name,
	18	- you can get, set and remove an option,
	19	- the value is a unicode string.
	20
	21	MutableSection are needed to set or remove an option, ReadOnlySection should
	22	be used otherwise.
	23
5743.4.16 by Vincent Ladeuil Some doc for the stores.	24	Stores
	25	------
	26
	27	Options can persistent in which case they are saved into Stores.
	28
	29	``config.Store`` defines the abstract interface that all stores should
	30	implement.
	31
	32	This object doesn't provide a direct access to the options, it only provides
	33	access to Sections. This is deliberate to ensure that sections can be properly
	34	shared by reusing the same underlying objects. Accessing options should be
	35	done via the ``Section`` objects.
	36
	37	A ``Store`` can contain one or more sections, each section is uniquely
	38	identified by a unicode string.
	39
	40	``config.ConfigObjStore`` is an implementation that use ``ConfigObj``.
	41
	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.
5743.5.6 by Vincent Ladeuil Mention that the test framework ought to support adding new stores.	45
	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
	50	ones.
5743.2.29 by Vincent Ladeuil Add doc for the section matchers.	51
	52	Filtering sections
	53	------------------
	54
	55	For some contexts, only some sections from a given store will apply. Defining
	56	which is what the ``SectionMatcher`` are about.
	57
	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
	61	``get_sections``.
	62
	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).
	67
	68	.. FIXME: Replace the appendpath example if/when it's deprecated ;)