kodo.quantities
Physical Quantities
This package provides types for representing physical quantities, which have a magnitude and a unit.
An in-depth usage guide is available in the module’s docstring.
Quick Start
Create units by creating an enum class subclassing QuantityUnit. The value of each item
is scaled to its siblings, with an appropriate value chosen as the smallest representable
quantity which forms the base precision when scaling quantities. For example, units of
distance where the smallest possible quantity is 0.1mm:
from kodo.quantities import QuantityUnit
class Distance(QuantityUnit):
MILLIMETERS = 10
CENTIMETERS = 10 * MILLIMETERS
METERS = 100 * CENTIMETERS
KILOMETERS = 1000 * METERS
SIXTEENTH_INCH = 15 # 1/16" == 1.5mm
QUARTER_INCH = 4 * SIXTEENTH_INCH
HALF_INCH = 8 * SIXTEENTH_INCH
INCH = 16 * SIXTEENTH_INCH
FOOT = 12 * INCH
class Time(QuantityUnit):
MILLISECONDS = 1
SECONDS = 1000 * MILLISECONDS
MINUTES = 60 * SECONDS
Quantities are then created with the ‘@’ operator, using a numeric value and the desired unit, for example 3m:
from kodo.quantities import Quantity
distance: Quantity[Distance] = 3 @ Distance.METERS
Quantities can be compared with, added to, and subtracted from other quantities of the same
type. Note that while use of different types of quantities together will not be caught at
run time, a type checker will report it as an error. The following examples use quantities
of the Distance type, so all work:
assert (3 @ Distance.METERS) == (300 @ Distance.CENTIMETERS) == (3000 @ Distance.MILLIMETERS)
assert (3 @ Distance.METERS) + (2.5 @ Distance.METERS) == (5.5 @ Distance.METERS)
Scaling with multiplication and division must be with unitless values:
assert (3 @ Distance.METERS) * 2.0 == (6 @ Distance.METERS)
assert (3 @ Distance.METERS) / 2 == (1.5 @ Distance.METERS)
Division with the floor division operator ‘//’ and finding the remainder with the modulus operator ‘%’ work a little differently; the second argument must be another quantity:
# 10m divides into 3m three times…
assert (10 @ Distance.METERS) // (3 @ Distance.METERS) == 3
# … with 1m left over
assert (10 @ Distance.METERS) % (3 @ Distance.METERS) == (1 @ Distance.METERS)
Finally, for most uses the quantity will eventually have to be converted back to a unitless
value of a known fixed unit, for example to pass to an external API, or store in a database.
This is done with the right shift operator ‘>>’:
import time
def get_delay() -> Quantity[Time]:
return 10000 @ Time.MILLISECONDS
# time.sleep() takes a single float argument for the sleep time in seconds
time.sleep( get_delay() >> Time.SECONDS )
If for some reason an integer value is needed instead, the floor division operator can be used as described above with a value of 1 of the desired unit. As a convenience the unit item itself can be used, matching the ‘>>’ operator:
assert (3.6 @ Time.SECONDS) // (1 @ Time.SECONDS) is 3
assert (3.6 @ Time.SECONDS) // Time.SECONDS is 3