<!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>Utilities — Buildbot v0.8.5rc2-29-g80a524b documentation</title>
<link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.5rc2-29-g80a524b',
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/buildbot.ico"/>
<link rel="top" title="Buildbot v0.8.5rc2-29-g80a524b documentation" href="../index.html" />
<link rel="up" title="Buildbot Development" href="index.html" />
<link rel="next" title="The Buildbot Database" href="database.html" />
<link rel="prev" title="Buildbot Configuration" href="config.html" />
</head>
<body>
<div class="header-wrapper">
<div class="header">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/header-text-transparent.png" alt="Logo"/>
</a></p>
<h1><a href="../index.html">Buildbot v0.8.5rc2-29-g80a524b documentation</a></h1>
<div class="rel">
<a href="config.html" title="Buildbot Configuration"
accesskey="P">previous</a> |
<a href="database.html" title="The Buildbot Database"
accesskey="N">next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="utilities">
<h1>Utilities<a class="headerlink" href="#utilities" title="Permalink to this headline">¶</a></h1>
<p>Several small utilities are available at the top-level <tt class="xref py py-mod docutils literal"><span class="pre">buildbot.util</span></tt>
package. As always, see the API documentation for more information.</p>
<dl class="docutils">
<dt><tt class="xref py py-func docutils literal"><span class="pre">naturalSort</span></tt></dt>
<dd>This function sorts strings "naturally", with embedded numbers sorted
numerically. This ordering is good for objects which might have a numeric
suffix, e.g., <tt class="docutils literal"><span class="pre">winslave1</span></tt>, <tt class="docutils literal"><span class="pre">winslave2</span></tt></dd>
<dt><tt class="xref py py-func docutils literal"><span class="pre">formatInterval</span></tt></dt>
<dd>This function will return a human-readable string describing a length of time,
given a number of seconds.</dd>
<dt><tt class="xref py py-class docutils literal"><span class="pre">ComparableMixin</span></tt></dt>
<dd><p class="first">This mixin class adds comparability to a subclass. Use it like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Widget</span><span class="p">(</span><span class="n">FactoryProduct</span><span class="p">,</span> <span class="n">ComparableMixin</span><span class="p">):</span>
<span class="n">compare_attrs</span> <span class="o">=</span> <span class="p">[</span> <span class="s">'radius'</span><span class="p">,</span> <span class="s">'thickness'</span> <span class="p">]</span>
<span class="c"># ...</span>
</pre></div>
</div>
<p class="last">Any attributes not in <tt class="docutils literal"><span class="pre">compare_attrs</span></tt> will not be considered when
comparing objects. This is particularly useful in implementing buildbot's
reconfig logic, where a simple comparison between the new and existing objects
can determine whether the new object should replace the existing object.</p>
</dd>
<dt><tt class="xref py py-func docutils literal"><span class="pre">safeTranslate</span></tt></dt>
<dd>This function will filter out some inappropriate characters for filenames; it
is suitable for adapting strings from the configuration for use as filenames.
It is not suitable for use with strings from untrusted sources.</dd>
<dt><tt class="xref py py-class docutils literal"><span class="pre">AsyncLRUCache</span></tt></dt>
<dd>This is a simple least-recently-used cache. Its constructor takes a maximum
size. When the cache grows beyond this size, the least-recently used items
will be automatically removed from the cache. The class has a
<tt class="xref py py-meth docutils literal"><span class="pre">get</span></tt> method that takes a key and a function to call (with
the key) when the key is not in the cache. Both <tt class="xref py py-meth docutils literal"><span class="pre">get</span></tt> and
the miss function return Deferreds.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">deferredLocked</span></tt></p>
<blockquote>
<div><p>This is a decorator to wrap an event-driven method (one returning
a <tt class="docutils literal"><span class="pre">Deferred</span></tt>) in an acquire/release pair of a designated
<tt class="docutils literal"><span class="pre">DeferredLock</span></tt>. For simple functions with a static lock, this
is as easy as:</p>
<div class="highlight-python"><pre>someLock = defer.DeferredLock()
@util.deferredLocked(someLock)
def someLockedFunction(..):
# ..
return d</pre>
</div>
<p>for class methods which must access a lock that is an instance attribute, the
lock can be specified by a string, which will be dynamically resolved to the
specific instance at runtime:</p>
<div class="highlight-python"><pre>def __init__(self):
self.someLock = defer.DeferredLock()
@util.deferredLocked('someLock')
def someLockedFunction(..):
# ..
return d</pre>
</div>
</div></blockquote>
<p><tt class="xref py py-func docutils literal"><span class="pre">epoch2datetime</span></tt></p>
<blockquote>
<div>Convert a UNIX epoch timestamp (an integer) to a Python datetime
object, in the UTC timezone. Note that timestamps specify UTC
time (modulo leap seconds and a few other minor details).</div></blockquote>
<p><tt class="xref py py-func docutils literal"><span class="pre">datetime2epoch</span></tt></p>
<blockquote>
<div>Convert an arbitrary Python datetime object into a UNIX epoch timestamp.</div></blockquote>
<p><tt class="docutils literal"><span class="pre">UTC</span></tt></p>
<blockquote>
<div><p>A <tt class="docutils literal"><span class="pre">datetime.tzinfo</span></tt> subclass representing UTC time. A similar class has
finally been added to Python in version 3.2, but the implementation is simple
enough to include here. This is mostly used in tests to create timezeon-aware
datetime objects in UTC:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">1978</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">31</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">UTC</span><span class="p">)</span>
</pre></div>
</div>
</div></blockquote>
<div class="section" id="buildbot-util-bbcollections">
<h2>buildbot.util.bbcollections<a class="headerlink" href="#buildbot-util-bbcollections" title="Permalink to this headline">¶</a></h2>
<p>This package provides a few useful collection objects.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It used to be named <tt class="docutils literal"><span class="pre">collections</span></tt>, but without absolute
imports (<span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0328"><strong>PEP 328</strong></a>), this precluded using the standard library's
<tt class="docutils literal"><span class="pre">collections</span></tt> module.</p>
</div>
<p>For compatibility, it provides a clone of the Python
<tt class="xref py py-class docutils literal"><span class="pre">collections.defaultdict</span></tt> for use in Python-2.4. In later versions, this
is simply a reference to the built-in <tt class="xref py py-class docutils literal"><span class="pre">defaultdict</span></tt>, so buildbot code can
simply use <tt class="xref py py-class docutils literal"><span class="pre">buildbot.util.collections.defaultdict</span></tt> everywhere.</p>
<p>It also provides a <tt class="xref py py-class docutils literal"><span class="pre">KeyedSets</span></tt> class that can represent any numbers of
sets, keyed by name (or anything hashable, really). The object is specially
tuned to contain many different keys over its lifetime without wasting memory.
See the docstring for more information.</p>
</div>
<div class="section" id="buildbot-util-eventual">
<h2>buildbot.util.eventual<a class="headerlink" href="#buildbot-util-eventual" title="Permalink to this headline">¶</a></h2>
<p>This package provides a simple way to say "please do this later":</p>
<div class="highlight-python"><pre>from buildbot.util.eventual import eventually
def do_what_I_say(what, where):
# ...
eventually(do_what_I_say, "clean up", "your bedroom")</pre>
</div>
<p>The package defines "later" as "next time the reactor has control", so this is
a good way to avoid long loops that block other activity in the reactor.
Callables given to <tt class="xref py py-func docutils literal"><span class="pre">eventually</span></tt> are guaranteed to be called in the same
order as the calls to <tt class="xref py py-func docutils literal"><span class="pre">eventually</span></tt>. Any errors from the callable are
logged, but will not affect other callables.</p>
<p>If you need a deferred that will fire "later", use <tt class="xref py py-func docutils literal"><span class="pre">fireEventually</span></tt>. This
function returns a deferred that will not errback.</p>
</div>
<div class="section" id="buildbot-util-json">
<h2>buildbot.util.json<a class="headerlink" href="#buildbot-util-json" title="Permalink to this headline">¶</a></h2>
<p>This package is just an import of the best available JSON module. Use it
instead of a more complex conditional import of <tt class="xref py py-mod docutils literal"><span class="pre">simplejson</span></tt> or
<tt class="xref py py-mod docutils literal"><span class="pre">json</span></tt>.</p>
<span class="target" id="the-database"></span></div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Buildbot Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manual/index.html">Buildbot Manual</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Buildbot Development</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="style.html">Buildbot Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="master-overview.html">Master Organization</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html">Buildbot Configuration</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="">Utilities</a><ul class="simple">
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="database.html">The Buildbot Database</a></li>
<li class="toctree-l2"><a class="reference internal" href="results.html">Build Result Codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="formats.html">File Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="webstatus.html">Web Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="master-slave.html">Master-Slave API</a></li>
<li class="toctree-l2"><a class="reference internal" href="encodings.html">String Encodings</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="classes.html">Classes</a></li>
</ul>
</li>
</ul>
<h3 style="margin-top: 1.5em;">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>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<a href="config.html" title="Buildbot Configuration"
>previous</a> |
<a href="database.html" title="The Buildbot Database"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
<br/>
<a href="../_sources/developer/utils.txt"
rel="nofollow">Show Source</a>
</div>
<div class="right">
<div class="footer">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
