<html lang="en">
<head>
<title>Utilities - BuildBot Manual - 0.8.4p1</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="BuildBot Manual - 0.8.4p1">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Developer-Information.html#Developer-Information" title="Developer Information">
<link rel="prev" href="Access-to-Configuration.html#Access-to-Configuration" title="Access to Configuration">
<link rel="next" href="The-Database.html#The-Database" title="The Database">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This is the BuildBot manual for Buildbot version 0.8.4p1.
Copyright (C) 2005, 2006, 2009, 2010 Brian Warner
Copying and distribution of this file, with or without
modification, are permitted in any medium without royalty
provided the copyright notice and this notice are preserved.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Utilities"></a>
<p>
Next: <a rel="next" accesskey="n" href="The-Database.html#The-Database">The Database</a>,
Previous: <a rel="previous" accesskey="p" href="Access-to-Configuration.html#Access-to-Configuration">Access to Configuration</a>,
Up: <a rel="up" accesskey="u" href="Developer-Information.html#Developer-Information">Developer Information</a>
<hr>
</div>
<h3 class="section">8.3 Utilities</h3>
<ul class="menu">
<li><a accesskey="1" href="buildbot_002eutil_002ebbcollections.html#buildbot_002eutil_002ebbcollections">buildbot.util.bbcollections</a>
<li><a accesskey="2" href="buildbot_002eutil_002eeventual.html#buildbot_002eutil_002eeventual">buildbot.util.eventual</a>
<li><a accesskey="3" href="buildbot_002eutil_002ejson.html#buildbot_002eutil_002ejson">buildbot.util.json</a>
</ul>
<p>Several small utilities are available at the top-level <code>buildbot.util</code>
package. As always, see the API documentation for more information.
<dl>
<dt><code>natualSort</code><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., <code>winslave1</code>, <code>winslave2</code>, ..
<br><dt><code>formatInterval</code><dd>
This function will return a human-readable string describing a length of time,
given a number of seconds.
<br><dt><code>ComparableMixin</code><dd>
This mixin class adds comparability to a subclass. Use it like this:
<pre class="example"> class Widget(FactoryProduct, ComparableMixin):
compare_attrs = [ 'radius', 'thickness' ]
# ...
</pre>
<p>Any attributes not in <code>compare_attrs</code> 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.
<br><dt><code>safeTranslate</code><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.
<br><dt><code>AsyncLRUCache</code><dd>
This is a 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 <code>get</code> method that
takes a key and a function to call (with the key) when the key is not in the
cache. Both <code>get</code> and the miss function return Deferreds.
<br><dt><code>deferredLocked</code><dd>
This is a decorator to wrap an event-driven method (one returning a
<code>Deferred</code>) in an acquire/release pair of a designated
<code>DeferredLock</code>. For simple functions with a static lock, this is as easy as
<pre class="example"> someLock = defer.DeferredLock()
@util.deferredLocked(someLock)
def someLockedFunction(..):
# ..
return d
</pre>
<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:
<pre class="example"> def __init__(self):
self.someLock = defer.DeferredLock()
@util.deferredLocked('someLock')
def someLockedFunction(..):
# ..
return d
</pre>
<br><dt><code>epoch2datetime</code><dd>
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).
<br><dt><code>datetime2epoch</code><dd>
Convert an arbitrary Python datetime object into a UNIX epoch timestamp.
<br><dt><code>UTC</code><dd>
A <code>datetime.tzinfo</code> 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:
<pre class="example"> dt = datetime.datetime(1978, 6, 15, 12, 31, 15, tzinfo=UTC)
</pre>
</dl>
</body></html>
