resolve

def children(cgtype: type[CGType]) -> list[tuple[str, type[CGType]]]:
    """The child types ``cgtype`` declares, each labelled by its position.

    A struct field is ``.name``, a container element ``[*]``, and a ``Path``
    target shares its address (``""``).
    """
    return cgtype._children()

def is_container(cgtype: object) -> bool:
    """Whether ``cgtype`` is a composite directory type (Struct / Map / Array)."""
    return isinstance(cgtype, type) and issubclass(cgtype, (Struct, Map, Array))

def is_schema_child(container: type[CGType], name: str) -> bool:
    """Whether ``name`` is a declared on-disk child entry of ``container``."""
    try:
        _descend(container, name)
    except SchemaPathError:
        return False
    return True

def is_storable_scalar(cgtype: object) -> bool:
    """Whether ``cgtype`` is a storable leaf scalar, not a composite container."""
    return is_storable(cgtype) and not is_container(cgtype)

def positions(
    cgtype: type[CGType],
    predicate: Callable[[type[CGType]], bool],
    prefix: str = "",
) -> list[tuple[str, type[CGType]]]:
    """Every position under ``cgtype`` whose type satisfies ``predicate``.

    Args:
        cgtype: The schema to search, ``cgtype`` itself included.
        predicate: Selects the types to report.
        prefix: The label of ``cgtype``'s own position.

    Returns:
        ``(label, type)`` pairs in declaration order; a matching type is not
        searched further.
    """
    if predicate(cgtype):
        return [(prefix, cgtype)]
    return [
        found
        for label, child in children(cgtype)
        for found in positions(child, predicate, prefix + label)
    ]

def resolve_schema_container(
    schema: type[CGType],
    components: Sequence[str],
) -> type[CGType]:
    """The type addressed by ``components`` from ``schema``; empty is ``schema`` itself.

    Raises:
        SchemaPathError: If a component is not a declared entry.
    """
    current: type[CGType] = schema
    for component in components:
        current = _descend(current, component)
    return current

def resolve_schema_leaf(
    schema: type[CGType],
    components: Sequence[str],
) -> type[Scalar]:
    """The leaf scalar addressed by ``components`` from ``schema``.

    Raises:
        SchemaPathError: If a component is invalid or the path ends at a container.
    """
    if not components:
        raise SchemaPathError("a leaf path needs at least one component")
    container = resolve_schema_container(schema, components[:-1])
    leaf = _descend(container, components[-1])
    if not (isinstance(leaf, type) and issubclass(leaf, Scalar)):
        raise SchemaPathError(
            f"{'/'.join(components)} is not a file leaf "
            f"(resolved to {getattr(leaf, '__name__', leaf)!r})"
        )
    return leaf