kodo.quantities 0.1.2

Types for representing physical quantities, which have a magnitude and a unit

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