Metadata-Version: 2.4
Name: vcti-selection
Version: 2.1.0
Summary: VCollab Selection - generic single-select container for keyed options
Author-email: "Visual Collaboration Technologies Inc." <support@vcollab.com>
Maintainer-email: "Visual Collaboration Technologies Inc." <support@vcollab.com>
License: Proprietary
Project-URL: Homepage, https://github.com/vcollab/vcti-python-selection
Project-URL: Source, https://github.com/vcollab/vcti-python-selection
Project-URL: Issues, https://github.com/vcollab/vcti-python-selection/issues
Project-URL: Changelog, https://github.com/vcollab/vcti-python-selection/blob/main/CHANGELOG.md
Keywords: selection,single-select,container,generic,typed,vcti,vcollab
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: hypothesis; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: hypothesis; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install vcti-selection
```

### In `requirements.txt`

```
vcti-selection>=2.1.0
```

### In `pyproject.toml` dependencies

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

---

## Quick Start

```python
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

```python
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

```python
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.
