util — Contains assorted utility functions¶

String Formatting¶

util.stringFromFloat(n, fractionalDigits=2, trimTrailingZeros=False)¶

Returns a string that shows n with fractionalDigits fractional digits, optionally with any trailing zeros removed. If the string would end with a ., that is removed as well.

>>> stringFromFloat(1.001, 2, True)
'1'
>>> stringFromFloat(1.001, 2, False)
'1.00'
>>> stringFromFloat(1.101, 2, True)
'1.1'
>>> stringFromFloat(1.101, 2, False)
'1.10'

util.stringFromTimePeriod(seconds)¶

Returns a string that expresses a period of seconds seconds in the form "H hours, M minutes, S seconds", or a localized equivalent, with unneeded elements omitted and correct pluralization. Fractions of a second are rounded up.

>>> stringFromTimePeriod(83)
'1 minute, 23 seconds'

Math¶

util.limit(value, minValue, maxValue)¶

Returns the value in the interval [minValue, maxValue] that is closest to value. None may be passed for minValue or maxValue to signify negative infinity and positive infinty, respectively.

>>> limit(0.5, 0.0, 1.0)
0.5
>>> limit(-0.2, 0.0, 1.0)
0.0
>>> limit(1.5, 0.0, 1.0)
1.0
>>> limit(1.5, 0.0, None)
1.5

util.roundToMultiple(n, m)¶

Returns the multiple of m that is closest to n. If two multiples are equally close, the function rounds away from zero. If both arguments are integers, the return value is an integer as well.

>>> roundToMultiple(28, 6)
30

Weak References¶

class util.WeakMethod(method, callback=None)¶

A weak reference to an instance method. Keeping a reference to WeakMethod(object.method) does not prevent object from being reclaimed as garbage.

When a WeakMethod is called, it forwards the call to the method it wraps if the object it is bound to is still alive. Otherwise, it raises a ReferenceError:

>>> class Object(object):
...     def method(self):
...         return 'Success!'
...
>>> o = Object()
>>> weakMethod = WeakMethod(o.method)
>>> weakMethod()
'Success!'
>>> o = None
>>> weakMethod()
Traceback (most recent call last):
    ...
ReferenceError: weakly-referenced object no longer exists

If callback is given, it will be called when the object the method is bound to is about to be finalized, using the WeakMethod instance as the only parameter, but calling the WeakMethod at that point will raise a RefernceError.

This class does not duplicate functionality already provided by weakref.proxy(). An instancemethod referenced only by a regular weak reference can be reclaimed even if the object it is bound to is still alive:

>>> import weakref
>>> class Object(object):
...     def method(self):
...         return 'Success!'
...
>>> o = Object()
>>> proxy = weakref.proxy(o.method)
>>> proxy()
Traceback (most recent call last):
    ...
ReferenceError: weakly-referenced object no longer exists

WeakMethod.isSameMethod(method)¶

Indicates whether method is the same method, bound to the same object, as the method wrapped by the instance.

Internationalization¶

util.TRANSLATIONS¶

The gettext translations class used for localization. See the documentation of the gettext module for details. Used by gettext() and ngettext().

util.gettext(string)¶

Returns the localized equivalent of string, using TRANSLATIONS.

Note

In order for the automatic extraction of translatable strings to work, string must be a string literal: gettext('foo') can be extracted; foo = 'foo', gettext(foo) cannot.

See the documentation of the gettext module for details.

util.ngettext(singular, plural, number)¶

Returns the localized equivalent of what is expressed using singular or plural in English, pluralized according to number, and using TRANSLATIONS.

text = ngettext('bar', 'bars', barCount)

is not simply a more convenient way for writing

if barCount == 1:
    text = gettext('bar')
else:
    text = gettext('bars')

since the target language may have more complex pluralization rules.

Note

In order for the automatic extraction of translatable strings to work, singular and plural must be a string literals: ngettext('bar', 'bars', barCount) can be extracted; bar, bars = 'bar', 'bars', ngettext(bar, bars, barCount) cannot.

See the documentation of the gettext module for details.

Exception Classes¶

class util.ApplicationError¶

The base class for all exceptions specific to NOSE.