angee.uom.models

Units of measure: a category tree of convertible units.

A :class:UomCategory groups the units that measure one physical quantity (weight, volume, time, temperature, …); a :class:Uom is one unit within a category. Each unit records its size as an affine map onto the category's reference unit: value_in_reference = qty * ratio + offset. ratio is the number of reference units contained in one of this unit (12 for a dozen when the reference is a single unit, 0.001 for a gram when the reference is a kilogram); offset is zero for ordinary multiplicative units and carries the zero-point shift for interval scales (273.15 for Celsius against a Kelvin reference). Exactly one unit per category is the reference (is_reference with ratio == 1 and offset == 0), enforced by a partial unique constraint plus a check constraint.

Conversion is reference-neutral: (qty * self.ratio + self.offset - to_uom.offset) / to_uom.ratio re-expresses qty of this unit in the other unit of the same category (the plain ratio quotient when both offsets are zero). The result is quantized to the destination unit's rounding step with ROUND_HALF_UP — half rounds away from zero. That mode is this addon's stated policy for quantity rounding, deliberately fixed here rather than caller-supplied (unlike the money/tax owners, whose amount rounding takes an explicit mode from company policy). rounding is a decimal step and, because unit steps are powers of ten, is read as a number of fractional digits by :func:angee.base.numeric.quantize.

UomCategory

class UomCategory(AngeeDataModel)

A family of units that measure the same quantity (weight, volume, time).

Meta

class Meta()

Django model options for a unit-of-measure category.

__str__

def __str__() -> str

Return the category name for Django displays.

UomQuerySet

class UomQuerySet(ArchiveQuerySet[Any], AngeeQuerySet[Any])

Archive read scopes layered over the REBAC-scoped unit queryset.

Uom

class Uom(ArchiveMixin, AngeeDataModel)

One unit within a category, mapped affinely onto the reference unit.

value_in_reference = qty * ratio + offset: ratio is the number of reference units in one of this unit, offset the zero-point shift for interval scales (temperature) and 0 everywhere else. The reference unit itself carries ratio == 1, offset == 0 and is_reference == True; at most one reference exists per category (the partial unique constraint below) and its identity map is check-enforced. rounding is the decimal step conversions into this unit are quantized to.

Meta

class Meta()

Django model options for a unit of measure.

__str__

def __str__() -> str

Return the unit name for Django displays.

rounding_places

@property
def rounding_places() -> int

Return the fractional-digit count of this unit's rounding step.

rounding is a decimal step (0.001 rounds to a milligram, 1 to a whole unit). :func:angee.base.numeric.quantize rounds to a number of places, so the step is read as its normalized scale — exact because unit steps are powers of ten (a non-power-of-ten step such as 0.5 is not representable this way; see the module docstring).

quantize

def quantize(qty: Decimal) -> Decimal

Return qty quantized to this unit's rounding step (ROUND_HALF_UP).

The one place a quantity meets this unit's precision: :meth:convert quantizes its result through it, and a consumer comparing a remaining quantity against zero quantizes here first so sub-step dust (a converted counter that landed a hair off the entered quantity) never reads as a real remainder.

convert

def convert(qty: Decimal, to_uom: Uom) -> Decimal

Return qty of this unit expressed in to_uom (same category only).

Both units map affinely onto their category's reference (value_in_reference = qty * ratio + offset), so the conversion goes through the reference and back: (qty * self.ratio + self.offset - to_uom.offset) / to_uom.ratio — the plain ratio quotient when both offsets are zero. The result is quantized to to_uom's rounding step via :meth:quantize (half away from zero) — quantity rounding is this addon's fixed policy, not a caller-supplied mode. Raises :class:ValueError across categories.

UomRole

The uom/role anchor: its const admin arm resolves a platform admin as an effective uom manager. See :func:angee.base.models.role_anchor.