<!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>Bazaar Architectural Overview — Bazaar v2.2.4 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.2.4',
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.2.4 documentation" href="index.html" />
<link rel="next" title="Integrating with Bazaar" href="integration.html" />
<link rel="prev" title="Bazaar Windows EC2 Server" href="ec2.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="integration.html" title="Integrating with Bazaar"
accesskey="N">next</a></li>
<li class="right" >
<a href="ec2.html" title="Bazaar Windows EC2 Server"
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.2.4)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="bazaar-architectural-overview">
<h1>Bazaar Architectural Overview<a class="headerlink" href="#bazaar-architectural-overview" title="Permalink to this headline">¶</a></h1>
<p>This document describes the key classes and concepts within Bazaar. It is
intended to be useful to people working on the Bazaar codebase, or to
people writing plugins. People writing plugins may also like to read the
guide to <a class="reference external" href="integrating.html">Integrating with Bazaar</a> for some specific
recipes.</p>
<p>If you have any questions, or if something seems to be incorrect, unclear
or missing, please talk to us in <tt class="docutils literal"><span class="pre">irc://irc.freenode.net/#bzr</span></tt>, or write
to the Bazaar mailing list.</p>
<div class="section" id="using-bzrlib">
<h2>Using bzrlib<a class="headerlink" href="#using-bzrlib" title="Permalink to this headline">¶</a></h2>
<div class="section" id="within-bzr">
<h3>Within bzr<a class="headerlink" href="#within-bzr" title="Permalink to this headline">¶</a></h3>
<p>When using bzrlib within the <tt class="docutils literal"><span class="pre">bzr</span></tt> program (for instance as a bzr
plugin), bzrlib’s global state is already available for use.</p>
</div>
<div class="section" id="from-outside-bzr">
<h3>From outside bzr<a class="headerlink" href="#from-outside-bzr" title="Permalink to this headline">¶</a></h3>
<p>To use bzrlib outside of <tt class="docutils literal"><span class="pre">bzr</span></tt> some global state needs to be setup.
bzrlib needs ways to handle user input, passwords, a place to emit
progress bars, logging setup appropriately for your program. The easiest
way to set all this up in the same fashion <tt class="docutils literal"><span class="pre">bzr</span></tt> does is to call
<tt class="docutils literal"><span class="pre">bzrlib.initialize</span></tt>. This returns a context manager within which bzrlib
functions will work correctly. See the pydoc for <tt class="docutils literal"><span class="pre">bzrlib.initialize</span></tt> for
more information. In Python 2.4 the <tt class="docutils literal"><span class="pre">with</span></tt> keyword is not supported and
so you need to use the context manager manually:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># This sets up your ~/.bzr.log, ui factory and so on and so forth. It is</span>
<span class="c"># not safe to use as a doctest.</span>
<span class="n">library_state</span> <span class="o">=</span> <span class="n">bzrlib</span><span class="o">.</span><span class="n">initialize</span><span class="p">()</span>
<span class="n">library_state</span><span class="o">.</span><span class="n">__enter__</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">pass</span>
<span class="c"># do stuff here</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">library_state</span><span class="o">.</span><span class="n">__exit__</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="bp">None</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="core-classes">
<h2>Core classes<a class="headerlink" href="#core-classes" title="Permalink to this headline">¶</a></h2>
<div class="section" id="transport">
<h3>Transport<a class="headerlink" href="#transport" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">Transport</span></tt> layer handles access to local or remote directories.
Each Transport object acts as a logical connection to a particular
directory, and it allows various operations on files within it. You can
<em>clone</em> a transport to get a new Transport connected to a subdirectory or
parent directory.</p>
<p>Transports are not used for access to the working tree. At present
working trees are always local and they are accessed through the regular
Python file I/O mechanisms.</p>
<div class="section" id="filenames-vs-urls">
<h4>Filenames vs URLs<a class="headerlink" href="#filenames-vs-urls" title="Permalink to this headline">¶</a></h4>
<p>Transports work in terms of URLs. Take note that URLs are by definition
only ASCII - the decision of how to encode a Unicode string into a URL
must be taken at a higher level, typically in the Store. (Note that
Stores also escape filenames which cannot be safely stored on all
filesystems, but this is a different level.)</p>
<p>The main reason for this is that it’s not possible to safely roundtrip a
URL into Unicode and then back into the same URL. The URL standard
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
doesn’t say how those bytes represent non-ASCII characters. (They’re not
guaranteed to be UTF-8 – that is common but doesn’t happen everywhere.)</p>
<p>For example, if the user enters the URL <tt class="docutils literal"><span class="pre">http://example/%e0</span></tt>, there’s no
way to tell whether that character represents “latin small letter a with
grave” in iso-8859-1, or “latin small letter r with acute” in iso-8859-2,
or malformed UTF-8. So we can’t convert the URL to Unicode reliably.</p>
<p>Equally problematic is if we’re given a URL-like string containing
(unescaped) non-ASCII characters (such as the accented a). We can’t be
sure how to convert that to a valid (i.e. ASCII-only) URL, because we
don’t know what encoding the server expects for those characters.
(Although it is not totally reliable, we might still accept these and
assume that they should be put into UTF-8.)</p>
<p>A similar edge case is that the URL <tt class="docutils literal"><span class="pre">http://foo/sweet%2Fsour</span></tt> contains
one directory component whose name is “sweet/sour”. The escaped slash is
not a directory separator, but if we try to convert the URL to a regular
Unicode path, this information will be lost.</p>
<p>This implies that Transports must natively deal with URLs. For simplicity
they <em>only</em> deal with URLs; conversion of other strings to URLs is done
elsewhere. Information that Transports return, such as from <tt class="docutils literal"><span class="pre">list_dir</span></tt>,
is also in the form of URL components.</p>
</div>
</div>
<div class="section" id="workingtree">
<h3>WorkingTree<a class="headerlink" href="#workingtree" title="Permalink to this headline">¶</a></h3>
<p>A workingtree is a special type of Tree that’s associated with a working
directory on disk, where the user can directly modify the files.</p>
<p>Responsibilities:</p>
<blockquote>
<div><ul class="simple">
<li>Maintaining a WorkingTree on disk at a file path.</li>
<li>Maintaining the basis inventory (the inventory of the last commit done)</li>
<li>Maintaining the working inventory.</li>
<li>Maintaining the pending merges list.</li>
<li>Maintaining the stat cache.</li>
<li>Maintaining the last revision the working tree was updated to.</li>
<li>Knows where its Branch is located.</li>
</ul>
</div></blockquote>
<p>Dependencies:</p>
<blockquote>
<div><ul class="simple">
<li>a Branch</li>
<li>an MutableInventory</li>
<li>local access to the working tree</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="branch">
<h3>Branch<a class="headerlink" href="#branch" title="Permalink to this headline">¶</a></h3>
<p>A Branch is a key user concept - its a single line of history that one or
more people have been committing to.</p>
<p>A Branch is responsible for:</p>
<blockquote>
<div><ul class="simple">
<li>Holding user preferences that are set in a Branch.</li>
<li>Holding the ‘tip’: the last revision to be committed to this Branch. (And the revno of that revision.)</li>
<li>Knowing how to open the Repository that holds its history.</li>
<li>Allowing write locks to be taken out to prevent concurrent alterations to the branch.</li>
</ul>
</div></blockquote>
<dl class="docutils">
<dt>Depends on:</dt>
<dd><ul class="first last simple">
<li>URL access to its base directory.</li>
<li>A Transport to access its files.</li>
<li>A Repository to hold its history.</li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="repository">
<h3>Repository<a class="headerlink" href="#repository" title="Permalink to this headline">¶</a></h3>
<p>Repositories store committed history: file texts, revisions, inventories,
and graph relationships between them. A repository holds a bag of
revision data that can be pointed to by various branches:</p>
<blockquote>
<div><ul class="simple">
<li>Maintains storage of various history data at a URL:
* Revisions (Must have a matching inventory)
* Digital Signatures
* Inventories for each Revision. (Must have all the file texts available).
* File texts</li>
<li>Synchronizes concurrent access to the repository by different
processes. (Most repository implementations use a physical
mutex only for a short period, and effectively support multiple readers
and writers.)</li>
</ul>
</div></blockquote>
<div class="section" id="stacked-repositories">
<h4>Stacked Repositories<a class="headerlink" href="#stacked-repositories" title="Permalink to this headline">¶</a></h4>
<p>A repository can be configured to refer to a list of “fallback”
repositories. If a particular revision is not present in the original
repository, it refers the query to the fallbacks.</p>
<p>Compression deltas don’t span physical repository boundaries. So the
first commit to a new, empty repository with fallback repositories will
store a full text of the inventory, and of every new file text.</p>
<p>At runtime, repository stacking is actually configured by the branch, not
the repository. So doing <tt class="docutils literal"><span class="pre">a_bzrdir.open_repository()</span></tt>
gets you just the single physical repository, while
<tt class="docutils literal"><span class="pre">a_bzrdir.open_branch().repository</span></tt> gets one configured with a stacking.
Therefore, to permanently change the fallback repository stored on disk,
you must use <tt class="docutils literal"><span class="pre">Branch.set_stacked_on_url</span></tt>.</p>
<p>Changing away from an existing stacked-on URL will copy across any
necessary history so that the repository remains usable.</p>
<p>A repository opened from an HPSS server is never stacked on the server
side, because this could cause complexity or security problems with the
server acting as a proxy for the client. Instead, the branch on the
server exposes the stacked-on URL and the client can open that.</p>
</div>
</div>
</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="#">Bazaar Architectural Overview</a><ul>
<li><a class="reference internal" href="#using-bzrlib">Using bzrlib</a><ul>
<li><a class="reference internal" href="#within-bzr">Within bzr</a></li>
<li><a class="reference internal" href="#from-outside-bzr">From outside bzr</a></li>
</ul>
</li>
<li><a class="reference internal" href="#core-classes">Core classes</a><ul>
<li><a class="reference internal" href="#transport">Transport</a><ul>
<li><a class="reference internal" href="#filenames-vs-urls">Filenames vs URLs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#workingtree">WorkingTree</a></li>
<li><a class="reference internal" href="#branch">Branch</a></li>
<li><a class="reference internal" href="#repository">Repository</a><ul>
<li><a class="reference internal" href="#stacked-repositories">Stacked Repositories</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="ec2.html"
title="previous chapter">Bazaar Windows EC2 Server</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="integration.html"
title="next chapter">Integrating with Bazaar</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/overview.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="integration.html" title="Integrating with Bazaar"
>next</a></li>
<li class="right" >
<a href="ec2.html" title="Bazaar Windows EC2 Server"
>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.2.4)</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009, Canonical Ltd.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
