yggdrasil.url.hive

hive

hive_encode

hive_encode(value: Any) -> str

Encode value as a filesystem-safe Hive partition value.

None → :data:HIVE_DEFAULT_PARTITION matching the Hive / Spark / Delta convention. Everything else is str(value) URL- quoted with the path-separator + = characters reserved so the encoded value can be split back unambiguously on a single = and never collides with a directory boundary.

hive_decode

hive_decode(raw: str) -> Any

Inverse of :func:hive_encode — returns the URL-decoded string.

The caller is responsible for casting the result to the partition column's declared dtype (the URL layer doesn't know the schema at parse time; see :func:hive_cast_value for the dtype-aware half).

hive_split

hive_split(name: str) -> 'tuple[str, Any] | None'

Parse a Hive-encoded segment into (column, value).

Returns None when name doesn't match the <col>=<val> convention so the caller can treat the entry as a plain (non- Hive) directory.

hive_cast_value

hive_cast_value(value: Any, dtype: 'pa.DataType | None') -> Any

Cast a :func:hive_decode-d value to dtype, leaving raw on failure.

Used when the partition column's declared dtype is in scope — int64 partition_key lands as :class:int, a timestamp partition as :class:datetime. When dtype is None or the cast raises (un-castable value), the decoded string passes through unchanged — every caller's downstream prune is conservative on undecidable shapes so a no-op cast just forces the row-level filter to run.

Fast path: the common partition dtypes (integers, floats, bool, string, the typed ints we tag on every cached response's partition_key) cast natively with the built-in constructor. Allocating a one-element pa.array and dispatching the cast kernel on every prune check shows up at the top of the cache hot path — the native path is ~50× faster. Anything outside the fast set (timestamps, decimals, lists, …) falls back to the pyarrow round-trip which still handles arbitrary types.