Base Cell Digit Toolkit

Utilities for manually constructing and dissecting H3 cell indexes using base cell numbers and digit sequences instead of coordinate-based helpers. The module must validate inputs, keep digit ordering intact, and make it easy to inspect individual resolution steps for an index.

Capabilities

Build indexes from digits

• Building from base cell 7 with digits [3, 0, 2] returns a resolution-3 index string; decomposing the result must report base cell 7 and the exact digit list. @test

Decompose indexes to parts

• Given an index assembled from base cell 1 and digits [6, 1], decomposition reports base cell 1, digit list [6, 1], and resolution 2. @test

Inspect a specific digit

• For an index built from base cell 10 and digits [2, 5, 0], requesting the digit at resolution 2 returns 5, and at resolution 3 returns 0; asking for resolution 4 raises a validation error. @test

Reject invalid inputs

• Supplying an empty digit list, any digit outside 0–6, or a base cell outside 0–121 produces a clear error instead of constructing an index. @test

Implementation

@generates

API

from collections.abc import Sequence
from typing import TypedDict


class CellParts(TypedDict):
    base_cell: int
    digits: list[int]
    resolution: int


def build_cell(base_cell: int, digits: Sequence[int]) -> str:
    """
    Create an H3 cell index where the digit sequence (values 0-6) defines the path from the base cell.
    The length of digits sets the target resolution; raise ValueError on invalid base cell or digits.
    """


def decompose_cell(cell: str) -> CellParts:
    """
    Break an H3 cell index into its base cell, digit sequence, and resolution (digit count).
    Preserve digit ordering exactly as encoded by the index.
    """


def digit_at(cell: str, resolution: int) -> int:
    """
    Return the digit at the given 1-based resolution step; raise ValueError when resolution exceeds the cell's depth.
    """

Dependencies { .dependencies }

h3 { .dependency }

Provides H3 index construction and deconstruction helpers for working with base cells and digit sequences.