Convert between units

Where possible, IngredientAmount units are returned as a pint.Unit. This allows easy programmatic conversion between different units.

Prerequisites

Programmatic conversion of units is only possible if none of the quantity, quantity_max and unit fields are str.

The convert_to function of IngredientAmount accepts the units to convert to and, optionally, a density if the conversion is between mass and volume.

>>> amount = parse_ingredient("1.2 kg lamb shank").amount[0]
>>> amount.convert_to("lbs")
IngredientAmount(quantity=Fraction(66138678655463271, 25000000000000000),
    quantity_max=Fraction(66138678655463271, 25000000000000000),
    unit=<Unit('pound')>,
    text='2.65 pound',
    confidence=0.99986,
    starting_index=0,
    unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
    APPROXIMATE=False,
    SINGULAR=False,
    RANGE=False,
    MULTIPLIER=False,
    PREPARED_INGREDIENT=False
)

The unit parameter of convert_to must a unit recognised by Pint.

CompositeIngredientAmount also supports unit conversion. In this case, the convert_to function return a pint.Quantity object which is the combined quantity converted to the given units.

>>> amount = parse_ingredient("1lb 2 oz lamb shank").amount[0]
>>> amount.convert_to("kg")
<Quantity(255145708125000060785923700000001/500000000000000000000000000000000, 'kilogram')>

The convert_to function of CompositeIngredientAmount is the same as doing

>>> CompositeIngredientAmount.combined().to(unit)

however it also supports conversion between mass and volume as described below.

Converting between mass and volume

It is quite common for recipes that use US customary units to give amounts in units of volume for ingredients, such as flour and sugar, where other recipes more commonly use units of mass. Conversion between these units is possible, but requires a density value to enable the conversion.

The density value can be provided as an optional argument to convert_to and must be given as a pint.Quantity. The default value is the density of water: 1000 kg/m³.

>>> amount = parse_ingredient("1 cup water").amount[0]
>>> # Using default density value
>>> amount.convert_to("g")
IngredientAmount(quantity=236.58823649999997,
    quantity_max=236.58823649999997,
    unit=<Unit('gram')>,
    text='236.588 gram',
    confidence=0.999943,
    starting_index=0,
    unit_system=<UnitSystem.METRIC: 'metric'>,
    APPROXIMATE=False,
    SINGULAR=False,
    RANGE=False,
    MULTIPLIER=False,
    PREPARED_INGREDIENT=False
)

>>> amount = parse_ingredient("2 cups all purpose flour").amount[0]
>>> # Using custom density value: 1 cup flour = 120 g
>>> amount.convert_to("g", density=120 * UREG("g/cup"))
IngredientAmount(quantity=240.0,
    quantity_max=240.0,
    unit=<Unit('gram')>,
    text='240 gram',
    confidence=0.999949,
    starting_index=0,
    unit_system=<UnitSystem.METRIC: 'metric'>,
    APPROXIMATE=False,
    SINGULAR=False,
    RANGE=False,
    MULTIPLIER=False,
    PREPARED_INGREDIENT=False
)

Attention

When converting between mass and volume, the quantity values are convert to float.

This is a result of how Pint handles the conversion.

Resources such as King Arthur Baking’s Ingredient Weight Chart are helpful in providing the densities for various ingredients commonly used in baking.