Skip to content

yggdrasil.enums.timeunit

timeunit

Centralized time-unit enum shared by every temporal DataType.

Temporal types (DateType / TimeType / TimestampType / DurationType) carry a unit field — a short string token like "us" or "ns" — that decides Arrow precision, Polars dtype mapping, Spark unit conversion, and scalar epoch math. Before this module the canonical token list lived inline in temporal.py as a loose dict, and aliases ("microsecond", "nanoseconds", "millis", …) coming in from user dicts had no one place to be normalized.

:class:TimeUnit provides:

  • canonical members for the eight units the temporal types actually understand (s, ms, us, ns, d, plus the interval forms year_month / day_time / month_day_nano);
  • :meth:parse for forgiving string / TimeUnit / None input with alias support;
  • :meth:is_valid for boolean checks without raising;
  • :attr:seconds / :attr:order for scalar conversion and precision-rank comparisons.

The enum subclasses :class:str so a TimeUnit instance is interchangeable with the string token everywhere it lands — unit: str = "us" field declarations don't need to change.

TimeUnit

Bases: str, Enum

Canonical time-unit token for temporal DataType instances.

Members carry the lowercase short form so the enum is a drop-in string replacement::

TimeType(unit=TimeUnit.MICROSECOND)
TimeType(unit="us")  # equivalent — both store ``"us"``

Use :meth:parse when accepting external input — it canonicalizes aliases ("microseconds", "micros", "µs") to a member and raises :class:ValueError for unknown tokens.

seconds property 

seconds: float

Seconds per one of this unit (used for scalar epoch math).

Calendar-style interval units (year_month / day_time / month_day_nano) have no fixed second-count and return float('nan') so comparisons surface the mismatch instead of silently truncating to zero.

order property 

order: int

Precision rank — higher = finer.

Used by TemporalType._merge_with_same_id to pick the wider of two units. Calendar interval units sit at rank -1 so they don't outrank fixed-precision ones in normal merges.

is_subsecond property 

is_subsecond: bool

True for ms / us / ns.

is_calendar property 

is_calendar: bool

True for the variable-length interval forms.

from_ classmethod 

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

Coerce any Python value into a :class:TimeUnit.

Accepts:

  • :class:TimeUnit (returned as-is);
  • any string the alias table or canonical member values know — s / ms / us / ns / d / interval forms, plurals (microseconds), long forms (millisecond), mixed case, µs, hyphens / spaces;
  • objects exposing a time_unit / unit attribute (Polars Datetime / Duration, PyArrow TimestampType / DurationType / Time32Type / Time64Type); the attribute is re-funneled through from_;
  • 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

Return True when :meth:from_ would succeed for value.