Rev 5767: Merge config-stack into config-concrete-stacks in file:///home/vila/src/bzr/experimental/config/
Vincent Ladeuil
v.ladeuil+lp at free.fr
Fri Apr 8 16:26:53 UTC 2011
At file:///home/vila/src/bzr/experimental/config/
------------------------------------------------------------
revno: 5767 [merge]
revision-id: v.ladeuil+lp at free.fr-20110408162653-vnzanyhe3fey8fge
parent: v.ladeuil+lp at free.fr-20110408134027-05rofldk978dt7xy
parent: v.ladeuil+lp at free.fr-20110408162618-nj6vpy1hx5gj086x
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: config-concrete-stacks
timestamp: Fri 2011-04-08 18:26:53 +0200
message:
Merge config-stack into config-concrete-stacks
added:
doc/developers/configuration.txt configuration.txt-20110408142435-korjxxnskvq44sta-1
modified:
bzrlib/config.py config.py-20051011043216-070c74f4e9e338e8
bzrlib/tests/test_config.py testconfig.py-20051011041908-742d0c15d8d8c8eb
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
doc/en/user-guide/configuring_bazaar.txt configuring_bazaar.t-20071128000722-ncxiua259xwbdbg7-1
-------------- next part --------------
=== modified file 'bzrlib/config.py'
--- a/bzrlib/config.py 2011-04-08 13:40:27 +0000
+++ b/bzrlib/config.py 2011-04-08 16:26:53 +0000
@@ -2112,7 +2112,7 @@
return self.options.get(name, default)
-_Created = object()
+_NewlyCreatedOption = object()
"""Was the option created during the MutableSection lifetime"""
@@ -2126,7 +2126,7 @@
def set(self, name, value):
if name not in self.options:
# This is a new option
- self.orig[name] = _Created
+ self.orig[name] = _NewlyCreatedOption
elif name not in self.orig:
self.orig[name] = self.get(name, None)
self.options[name] = value
@@ -2261,6 +2261,12 @@
return MutableSection(section_name, section)
+# Note that LockableConfigObjStore inherits from ConfigObjStore because we need
+# unlockable stores for use with objects that can already ensure the locking
+# (think branches). If different stores (not based on ConfigObj) are created,
+# they may face the same issue.
+
+
class LockableConfigObjStore(ConfigObjStore):
"""A ConfigObjStore using locks on save to ensure store integrity."""
@@ -2335,7 +2341,7 @@
self.store = store
def get_sections(self):
- # This is where we requires loading the store so we can see all defined
+ # This is where we require loading the store so we can see all defined
# sections.
sections = self.store.get_sections()
# Walk the revisions in the order provided
=== modified file 'bzrlib/tests/test_config.py'
--- a/bzrlib/tests/test_config.py 2011-04-07 20:56:43 +0000
+++ b/bzrlib/tests/test_config.py 2011-04-08 16:26:53 +0000
@@ -1887,7 +1887,7 @@
# The option didn't exist initially so it we need to keep track of it
# with a special value
self.assertTrue('foo' in section.orig)
- self.assertEquals(config._Created, section.orig['foo'])
+ self.assertEquals(config._NewlyCreatedOption, section.orig['foo'])
def get_ConfigObjStore(transport, file_name, content=None):
=== added file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt 1970-01-01 00:00:00 +0000
+++ b/doc/developers/configuration.txt 2011-04-08 16:26:18 +0000
@@ -0,0 +1,96 @@
+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 ;)
+
+Stacks
+------
+
+An option can take different values depending on the context it is used. Such
+a context 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 this case a new ``Stack`` can be created cheaply.
+
=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt 2011-01-06 06:26:23 +0000
+++ b/doc/developers/index.txt 2011-04-08 14:59:29 +0000
@@ -36,9 +36,10 @@
.. toctree::
:maxdepth: 1
+ configuration
+ fetch
transports
ui
- fetch
Releasing and Packaging
=======================
=== modified file 'doc/en/user-guide/configuring_bazaar.txt'
--- a/doc/en/user-guide/configuring_bazaar.txt 2011-02-07 01:39:42 +0000
+++ b/doc/en/user-guide/configuring_bazaar.txt 2011-04-08 14:59:29 +0000
@@ -37,6 +37,24 @@
which shouldn't be reached by the proxy. (See
<http://docs.python.org/library/urllib.html> for more details.)
+Various ways to configure
+-------------------------
+
+As shown in the example above, there are various ways to
+configure Bazaar, they all share some common properties though,
+an option has:
+
+- a name which is generally a valid python identifier,
+
+- a value which is a string. In some cases, Bazzar will be able
+ to recognize special values like 'True', 'False' to infer a
+ boolean type, but basically, as a user, you will always specify
+ a value as a string.
+
+Options are grouped in various contexts so their name uniquely
+identify them in this context. When needed, options can be made
+persistent by recording them in a configuration file.
+
Configuration files
-------------------
More information about the bazaar-commits
mailing list