[frames] | no frames]

# Module firkin

source code

firkin is a python module to convert between different measurement units.

# Usage

First we create an instance of UnitManager:
`>>> um=UnitManager()`
Next we create two families of units. The first one ist `liter` and uses SIFamily to automatically create units with the SI prefixes:
`>>> um.add(SIFamily(base='l', name='liter'))`

Now our UnitManager knows about fl, pl, nl, ..., Ml, Gl, Tl.

How many liters are 10000 ml?
```>>> um.convert_to_unit(1e4, 'ml', 'l')
(Decimal("10.0000"), 'l')```
Next we create a family by hand:
```>>> f=Family(name='f', base='gallon')
>>> f.add('barrel', 36, 'gallon')
>>> f.add('kilderkin', 0.5, 'barrel')
>>> f.add('firkin', 0.5, 'kilderkin')```

Now we have a family called `f` that uses gallon as its base and knows about barrel, kilderkin and firkin, too.

How much gallons is one firkin?
```>>> f.convert(1, 'firkin', 'gallon')
(Decimal("9.00"), 'gallon')```
What's the best way to express 3 kilderkin?
```>>> f.autoconvert(3, 'kilderkin')
(Decimal("1.50"), 'barrel')```
To convert between family `f` and family `liter` we need to add `f` to our UnitManager and tell how much liters (base unit of family `liter`) a gallon (base unit of family `f`) is:
`>>> um.add(f, other='liter',  factor=4.54609)`
Of course the UnitManager can convert firkin to gallon, too:
```>>> um.convert_to_unit(1, 'firkin', 'gallon')
(Decimal("9.00"), 'gallon')```
But it also can convert firkin to liters:
```>>> um.convert_to_unit(1, 'firkin', 'l')
(Decimal("40.9148100"), 'l')```
Or find the best way to express one liter in one of the units from family `f`:
```>>> um.convert_to_family(1, 'l', 'f')
(Decimal("0.219969248299"), 'gallon')```
That works with barrels, too:
```>>> um.convert_to_family(1, 'barrel', 'f')
(Decimal("1.00"), 'barrel')```

A classical example: How to convert between °C and °F?

We need a family for °C:
`>>> um.add(Family(base='°C'))`

and for °F.

°F is (°C-32)/1.8:
`>>> um.add(Family(base='°F'), other='°C', offset=(-32/1.8), factor=5.0/9)`
Now we can convert:
```>>> um.convert_to_unit(32, '°F', '°C')
(Decimal("-8E-12"), '°C')
>>> um.convert_to_unit(100, '°C', '°F')
(Decimal("212.0"), '°F')```
Converting between °C and ml isn't useful:
```>>> um.convert_to_unit(1, '°C', 'ml')
(None, None)```

Warning:

firkin is alpha software. So far it seems to work for me but it may have severe bugs I didn't noticed yet. Use it at your own risk.

Firkin is still under development and the API may change in the future.

 Classes
Family
A Family is a collection of units which are derived from a common base unit.
SIFamily
Family that uses SI prefixes:
Item
Holds an item in UnitManager
UnitManager
A UnitManager hold a collection of Family objects and allows to convert between their units.
 Functions

 to_decimal(value) Convert value to decimal.Decimal source code
 Function Details

### to_decimal(value)

source code
Convert value to decimal.Decimal

 Generated by Epydoc 3.0beta1 on Tue Oct 14 17:48:04 2008 http://epydoc.sourceforge.net