Skip to content

yggdrasil.enums.byteunit

byteunit

Centralized byte-unit enum for memory / capacity / spill thresholds.

PARITY: ported to JS/TS at packages/yggdrasil/enums/byteUnit.ts — keep in sync.

Across Yggdrasil, a "size in bytes" appears in many places: Memory's spill_bytes threshold, the Arrow tabular spill cutoff, request / response body limits, codec hints, hash batch sizes. Before this module each call site rolled its own 128 * 1024 * 1024 / "128MB" parsing and the convention drifted between SI (base 1000) and IEC (base 1024).

:class:ByteUnit pins the convention to base 1024 — IEC binary units (KiB / MiB / GiB / …) and exposes:

  • canonical members for B through PiB;
  • :meth:from_ for forgiving string / int / ByteUnit input;
  • :meth:parse_size for "give me an integer byte count" — the most common need at config / API boundaries ("128 MB" → 134217728);
  • :attr:bytes (== member value) for "multiply this by N to get N units of bytes": 128 * ByteUnit.MIB is just an int and reads at the call site.

The enum subclasses :class:int so a member is interchangeable with its byte count everywhere a plain integer would land — annotations like spill_bytes: int = 128 * ByteUnit.MIB work without a cast.

SI (base-1000) units are intentionally not included. Memory sizing in this codebase is uniformly binary; mixing 10⁶ vs 2²⁰ at threshold boundaries is the kind of subtle bug this enum exists to prevent.

ByteUnit

Bases: IntEnum

Canonical IEC binary byte-unit token + scalar value.

Each member's value IS the byte count for one unit, so 128 * ByteUnit.MIB reads naturally at the call site and slots into any int field. Use :meth:parse_size when accepting external config / API input — it canonicalizes "128 MB" / "1.5 GiB" / raw integers / ByteUnit members all to a plain integer byte count.

bytes property 

bytes: int

Bytes per one of this unit (== member value).

short property 

short: str

Short colloquial token: "B" / "KB" / "MB" / ….

iec property 

iec: str

Strict IEC token: "B" / "KiB" / "MiB" / ….

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'ByteUnit'

Coerce any Python value into a :class:ByteUnit member.

Accepts:

  • :class:ByteUnit (returned as-is);
  • any string the alias table knows — B / KB / MiB / gigabyte / mixed case / trailing s;
  • an integer matching a member's byte value (1024 → :attr:KIB);
  • None — returns default if supplied, else raises.

default swallows unknown / unparseable input. Without it, unknown tokens raise :class:ValueError and unsupported types raise :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would succeed for value.

parse_size classmethod 

parse_size(
    value: Union[int, str, "ByteUnit", None], *, default: Any = ...
) -> int

Coerce a size-like value to an integer byte count.

The single entry point for "config gave me a size, give me bytes." Accepts:

  • :class:int — passed through (must be non-negative);
  • :class:ByteUnit — its scalar value;
  • a quantity string "128 MB" / "1.5 GiB" / "512" — parsed with this enum's IEC conventions;
  • a bare unit string "MiB" — yields one unit (1024**2);
  • None — returns default if supplied, else raises.

Floating-point quantities round to the nearest byte ("1.5 KiB" → 1536). Negative values raise :class:ValueError.

format classmethod 

format(n: int, *, iec: bool = True, precision: int = 1) -> str

Format an integer byte count as a human-readable string.

Picks the largest unit at which n divides cleanly into a scalar ≥ 1, defaulting to IEC tokens ("128 MiB"); pass iec=False for the colloquial short form ("128 MB"). precision controls fractional digits.

pretty classmethod 

pretty(
    v: float,
    unit: "ByteUnit | str | None" = None,
    *,
    iec: bool = True,
    precision: int = 1
) -> str

Human-readable rendering of a quantity v expressed in unit.

v is a scalar count of unit (bytes by default); it's scaled to a byte count and handed to :meth:format. The companion to :meth:format for the common "I have N MiB, show it nicely" case::

ByteUnit.pretty(1536)             # "1.5 KiB"
ByteUnit.pretty(8, ByteUnit.MIB)  # "8.0 MiB"
ByteUnit.pretty(1.5, "gb")        # "1.5 GiB"

unit defaults to :attr:B (resolved at call time so the class default is usable inside the method body); pass iec=False for the colloquial short form.