Selection

Generic single-select container for keyed options.

Overview

vcti-selection provides Selection[T], a small generic container for managing a collection of options where exactly one option can be selected at a time. Options are stored by string keys and the selected option can be changed, cleared, or removed at any time.

Typical uses are modelling UI single-choice state (theme, view mode, current dataset) and tracking the "active" item among several. It has zero dependencies and is not thread-safe — callers synchronize if needed.

Installation

pip install vcti-selection

In requirements.txt

vcti-selection>=2.1.0

In pyproject.toml dependencies

dependencies = [
    "vcti-selection>=2.1.0",
]

Quick Start

from vcti.selection import Selection

# Construct from a mapping — first key is auto-selected
themes = Selection[str]({
    "dark":   "Dark Theme",
    "light":  "Light Theme",
    "system": "System Theme",
})

print(themes.selected)      # "Dark Theme"
print(themes.selected_key)  # "dark"

themes.select("light")
print(themes.selected)      # "Light Theme"

# Cycle through keys in insertion order, wrapping at the ends
themes.select_next()        # "system"
themes.select_next()        # "dark" (wrapped)

# Clear the selection; deselect() returns the previous key
previous = themes.deselect()
print(previous)             # "dark"
print(themes.selected)      # None

Holding any value type

from dataclasses import dataclass
from vcti.selection import Selection

@dataclass
class View:
    title: str
    renderer: str

views = Selection[View]({
    "plot":  View("Plot view",  "matplotlib"),
    "table": View("Table view", "pandas"),
}, selected="table")

active = views.selected  # View(title="Table view", renderer="pandas")

Dict-like access

sel = Selection[str]({"a": "Alpha", "b": "Beta"})

"a" in sel                  # True
sel["a"]                    # "Alpha"
sel.get("missing", "—")     # "—"
list(sel.keys())            # ["a", "b"]
list(sel.items())           # [("a", "Alpha"), ("b", "Beta")]
for key in sel: ...         # iterates keys

Dependencies

None. Standard library only.