8.3 Utilities

• buildbot.util.bbcollections
• buildbot.util.eventual
• buildbot.util.json

Several small utilities are available at the top-level buildbot.util package. As always, see the API documentation for more information.

natualSort

This function sorts strings "naturally", with embedded numbers sorted numerically. This ordering is good for objects which might have a numeric suffix, e.g., winslave1, winslave2, ..

formatInterval

This function will return a human-readable string describing a length of time, given a number of seconds.

ComparableMixin

This mixin class adds comparability to a subclass. Use it like this:

          class Widget(FactoryProduct, ComparableMixin):
              compare_attrs = [ 'radius', 'thickness' ]
              # ...

Any attributes not in compare_attrs 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.

safeTranslate

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.

AsyncLRUCache

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 get method that takes a key and a function to call (with the key) when the key is not in the cache. Both get and the miss function return Deferreds.

deferredLocked

This is a decorator to wrap an event-driven method (one returning a Deferred) in an acquire/release pair of a designated DeferredLock. For simple functions with a static lock, this is as easy as

          someLock = defer.DeferredLock()
          @util.deferredLocked(someLock)
          def someLockedFunction(..):
              # ..
              return d

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:

              def __init__(self):
                  self.someLock = defer.DeferredLock()
          
              @util.deferredLocked('someLock')
              def someLockedFunction(..):
                  # ..
                  return d

epoch2datetime

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).

datetime2epoch

Convert an arbitrary Python datetime object into a UNIX epoch timestamp.

UTC

A datetime.tzinfo 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:

          dt = datetime.datetime(1978, 6, 15, 12, 31, 15, tzinfo=UTC)