yr.tree_selector

tree_selector(
    tree: TreeSelectorSource,
    label: str | None = None,
    min_selections: int = 1,
    max_selections: int | None = None,
    cancel_label: str | None = None,
) → list[str] | None

Present a nested tree and return the selected leaf values.

Parameters

tree
type: TreeSelectorSource

Nested option mapping or an object implementing __yera_tree__().

label
type: str | None = None

Optional prompt shown above the tree.

min_selections
type: int = 1

Minimum number of leaves that must be selected.

max_selections
type: int | None = None

Optional maximum number of leaves that may be selected.

cancel_label
type: str | None = None

Optional label for an action that returns None without validating the selection.

Raises

TypeError

If the source cannot provide a valid tree mapping.

ValueError

If the supplied tree is malformed.

InputValueError

If the submitted selection violates its cardinality, contains duplicates, or includes a value outside the requested tree.

Returns

type: list[str] | None

The canonical values of the selected leaves in submitted order, or None when cancellation is enabled and selected.

Examples

Select values supplied by an object implementing __yera_tree__():

python
import yera as yr

class AnimalChoices:
    def __yera_tree__(self) -> dict[str, object]:
        return {
            "Mammals": {
                "Red panda": "red-panda",
                "Sea otter": "sea-otter",
            },
            "Birds": {
                "Puffin": "puffin",
                "Kingfisher": "kingfisher",
            },
        }

animals = yr.tree_selector(
    AnimalChoices(),
    label="Choose one or two favourite animals",
    min_selections=1,
    max_selections=2,
    cancel_label="Cancel",
)

if animals is None:
    yr.markdown("No animals were selected.")