<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Configuring Bazaar — Bazaar v2.4.2 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2.4.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/bzr.ico"/>
<link rel="top" title="Bazaar v2.4.2 documentation" href="index.html" />
<link rel="next" title="Fetching data" href="fetch.html" />
<link rel="prev" title="Documenting Changes" href="documenting-changes.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="fetch.html" title="Fetching data"
accesskey="N">next</a></li>
<li class="right" >
<a href="documenting-changes.html" title="Documenting Changes"
accesskey="P">previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li><a href="index.html">Developer Document Catalog (2.4.2)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="configuring-bazaar">
<h1>Configuring Bazaar<a class="headerlink" href="#configuring-bazaar" title="Permalink to this headline">¶</a></h1>
<p>A configuration option has:</p>
<ul class="simple">
<li>a name: a valid python identifier (even if it’s not used as an
identifier in python itself)</li>
<li>a value: a unicode string</li>
</ul>
<div class="section" id="option">
<h2>Option<a class="headerlink" href="#option" title="Permalink to this headline">¶</a></h2>
<p>The Option object is used to define its properties:</p>
<ul class="simple">
<li>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.</li>
<li>default: the default value that Stack.get() should return if no
value can be found for the option.</li>
</ul>
<p>Since plugins should be able to lazily register options, the associated help
is not part of the object but provided at registration time.</p>
</div>
<div class="section" id="sections">
<h2>Sections<a class="headerlink" href="#sections" title="Permalink to this headline">¶</a></h2>
<p>Options are grouped into sections which share some properties with the well
known dict objects:</p>
<ul class="simple">
<li>the key is the name,</li>
<li>you can get, set and remove an option,</li>
<li>the value is a unicode string.</li>
</ul>
<p>MutableSection is needed to set or remove an option, ReadOnlySection should
be used otherwise.</p>
</div>
<div class="section" id="stores">
<h2>Stores<a class="headerlink" href="#stores" title="Permalink to this headline">¶</a></h2>
<p>Options can be persistent in which case they are saved into Stores.</p>
<p><tt class="docutils literal"><span class="pre">config.Store</span></tt> defines the abstract interface that all stores should
implement.</p>
<p>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 <tt class="docutils literal"><span class="pre">Section</span></tt> objects.</p>
<p>A <tt class="docutils literal"><span class="pre">Store</span></tt> can contain one or more sections, each section is uniquely
identified by a unicode string.</p>
<p><tt class="docutils literal"><span class="pre">config.ConfigObjStore</span></tt> is an implementation that use <tt class="docutils literal"><span class="pre">ConfigObj</span></tt>.</p>
<p>Depending on the object it is associated with (or not) a <tt class="docutils literal"><span class="pre">Store</span></tt> also needs
to implement a locking mechanism. <tt class="docutils literal"><span class="pre">LockableConfigObjStore</span></tt> implements such a
mechanism for <tt class="docutils literal"><span class="pre">ConfigObj</span></tt> based stores.</p>
<p>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.</p>
</div>
<div class="section" id="filtering-sections">
<h2>Filtering sections<a class="headerlink" href="#filtering-sections" title="Permalink to this headline">¶</a></h2>
<p>For some contexts, only some sections from a given store will apply. Defining
which is what the <tt class="docutils literal"><span class="pre">SectionMatcher</span></tt> are about.</p>
<p>The main constraint here is that a <tt class="docutils literal"><span class="pre">SectionMatcher</span></tt> 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
<tt class="docutils literal"><span class="pre">get_sections</span></tt>.</p>
<p>Only <tt class="docutils literal"><span class="pre">ReadOnlySection</span></tt> objects are manipulated here but a <tt class="docutils literal"><span class="pre">SectionMatcher</span></tt>
can return dedicated <tt class="docutils literal"><span class="pre">Section</span></tt> to provide additional context (the
<tt class="docutils literal"><span class="pre">LocationSection</span></tt> add an <tt class="docutils literal"><span class="pre">extra_path</span></tt> attribute to implement the
<tt class="docutils literal"><span class="pre">appendpath</span></tt> policy for example).</p>
</div>
<div class="section" id="stacks">
<h2>Stacks<a class="headerlink" href="#stacks" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>Such a context is implemented by creating a list of <tt class="docutils literal"><span class="pre">Section</span></tt> stacked upon
each other. A <tt class="docutils literal"><span class="pre">Stack</span></tt> can then be asked for an option value and returns the
first definition found.</p>
<p>This provides a great flexibility to decide priorities between sections when
the stack is defined without to worry about them in the code itself.</p>
<p>A stack also defines a mutable section (which can be None) to handle
modifications.</p>
<p>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.</p>
<p>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.</p>
<p>A <tt class="docutils literal"><span class="pre">Stack</span></tt> defines a mutable section when there is no ambiguity. If there
is one, then the <em>user</em> should be able to decide and in this case a new
<tt class="docutils literal"><span class="pre">Stack</span></tt> can be created cheaply.</p>
<p>Different stacks can be created for different purposes, the existing
<tt class="docutils literal"><span class="pre">GlobalStack</span></tt>, <tt class="docutils literal"><span class="pre">LocationStack</span></tt> and <tt class="docutils literal"><span class="pre">BranchStack</span></tt> can be used as basis
or examples. These classes are the only ones that should be used in code,
<tt class="docutils literal"><span class="pre">Stores</span></tt> 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.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Configuring Bazaar</a><ul>
<li><a class="reference internal" href="#option">Option</a></li>
<li><a class="reference internal" href="#sections">Sections</a></li>
<li><a class="reference internal" href="#stores">Stores</a></li>
<li><a class="reference internal" href="#filtering-sections">Filtering sections</a></li>
<li><a class="reference internal" href="#stacks">Stacks</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="documenting-changes.html"
title="previous chapter">Documenting Changes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="fetch.html"
title="next chapter">Fetching data</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/configuration.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="fetch.html" title="Fetching data"
>next</a></li>
<li class="right" >
<a href="documenting-changes.html" title="Documenting Changes"
>previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li><a href="index.html">Developer Document Catalog (2.4.2)</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
