gavo.base.unitconv module

A python module to parse VOUnit strings and compute conversion factors.

We believe this implements the full VOUnit specification.

To use this, you must have the gavo utils package installed. For details, see The changes required to make this work without gavo.utils are minute, though. If you want that, talk to the authors.

Unit tests for this are at

exception gavo.base.unitconv.BadUnit(msg: str = '', hint: Optional[str] = None)[source]

Bases: Error

class gavo.base.unitconv.Expression(term, scaleFactor)[source]

Bases: _Node

The root node of an expression tree.

This contains a term and optionally a scale factor.

classmethod fromToks(s, p, toks)[source]

returns a pair of a numeric factor and a dict mapping SI units to their powers.

class gavo.base.unitconv.Factor(unit, power)[source]

Bases: _Node

A UnitNode with a power.

classmethod fromToks(s, p, toks)[source]

see Term.getFactorWithUnit.

class gavo.base.unitconv.FunctionApplication(funcName, term)[source]

Bases: _Node

A function applied to a term.

classmethod fromToks(s, p, toks)[source]

see this method in Term.

We don’t simplify any units here, as that’s a bit hard in the current logic – though there’s something to be won, in particular with sqrt. Ah well.

exception gavo.base.unitconv.IncompatibleUnits(msg: str = '', hint: Optional[str] = None)[source]

Bases: Error

class gavo.base.unitconv.QuotedUnitNode(unit)[source]

Bases: _Node

a quoted (“defined unknown”) unit.

classmethod fromToks(s, p, toks)[source]
class gavo.base.unitconv.Term(op1, operator, op2)[source]

Bases: _Node

A Node containing two factors and an operator.

The operator here is either . (product) or / (division).

classmethod fromToks(s, p, toks)[source]

returns a factor within self with unit if it exists.

Actually, it will return that factor and the exponentiation factor, which is -1 if that factor is in the denominator, 1 otherwise. This returns None, None if no such factor exists.

class gavo.base.unitconv.UnitNode(unit, prefix='')[source]

Bases: _Node

a terminal node containing a unit, possibly with a prefix

This is normally constructed through the fromToks constructor.

Check out the unit, prefix, and isUnknown attributes. The prefix can be turned to a factor using the PREFIXES dictionary. An empty prefix (factor 1) is represented by an empty string.

There is also isValid; that’s isUnknown except if an unknown unit is quoted.

classmethod fromToks(s, p, toks)[source]

returns a pair of factor and basic unit.

Basic units are what’s in the defining pairs in the PLAIN_UNITS dict.


returns a sorted tuple of (si, power) for a result of getSI().

These should be more suitable for dimensional analysis.

gavo.base.unitconv.computeColumnConversions(newColumns, oldColumns)[source]

returns a dict of conversion factors between newColumns and oldColumns.

Both arguments are iterables of columns.

For every column in newColumn, the function sees if the units of newColumn and oldColumn match. If they don’t, compute a conversion factor to be multiplied to oldColumns values to make them newColumns values and add it to the result dict.

The function raises a DataError if a column in newColumns has no match in oldColumns.

gavo.base.unitconv.computeConversionFactor(unitStr1, unitStr2)[source]

returns the factor needed to get from quantities given in unitStr1 to unitStr2.

Both must be given in VOUnits form.

This function may raise a BadUnit if one of the strings are malformed, or an IncompatibleUnit exception if the units don’t have the same SI base.

If the function is successful, unitStr1 = result*unitStr2

gavo.base.unitconv.evalAll(s, p, toks)[source]

a parse action evaluating the whole match as a python expression.

Obviously, this should only be applied to carefully screened nonterminals.


returns a reasonable decorative but python-readable representation of aFloat.

Floats looking good as simple decimals (modulus between 0.01 and 1000) are returned without exponent.


the grammar to parse VOUnits.

After initialization, the class has a “symbols” dictionary containing the individual nonterminals.

gavo.base.unitconv.parseUnit(unitStr, unitGrammar=unit expression)[source]