vcti-deck 1.0.1__tar.gz

vcti_deck-1.0.1/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_deck-1.0.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: vcti-deck
+Version: 1.0.1
+Summary: Generic ordered collection with named items and policy-based compatibility
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: pyright; extra == "typecheck"
+Dynamic: license-file
+
+# Deck
+
+Generic ordered collection with named items and policy-based compatibility
+for Python.
+
+## Purpose
+
+VCollab applications need ordered collections where items are referenced
+by name, support custom ordering, and optionally enforce compatibility
+rules. `Deck` provides this as a lightweight, zero-dependency building
+block.
+
+## Installation
+
+```bash
+pip install vcti-deck
+```
+
+## Quick Start
+
+### Basic Deck
+
+```python
+from vcti.deck import Deck
+
+deck = Deck[str]()
+deck.add("header", "Welcome")
+deck.add("body", "Content")
+deck.add("footer", "Copyright")
+
+deck.get("header")    # "Welcome"
+deck.has("body")      # True
+"footer" in deck      # True
+len(deck)             # 3
+list(deck)            # ["Welcome", "Content", "Copyright"]
+```
+
+### Custom Ordering
+
+```python
+deck.set_order(["footer", "header"])
+list(deck)        # ["Copyright", "Welcome"] — body skipped
+deck.ids()        # ["footer", "header"]
+
+deck.clear_order()
+list(deck)        # ["Welcome", "Content", "Copyright"] — insertion order
+```
+
+### PolicyBoundDeck
+
+Use `PolicyBoundDeck` when items must satisfy compatibility rules:
+
+```python
+from enum import StrEnum, auto
+from vcti.deck import PolicyBoundDeck, CompatibilityPolicy
+
+class LayerKind(StrEnum):
+    IMAGE = auto()
+    VECTOR = auto()
+
+class Layer:
+    def __init__(self, kind: LayerKind):
+        self.kind = kind
+
+class SameKindPolicy(CompatibilityPolicy[LayerKind, Layer]):
+    def is_compatible(self, item: Layer, deck_type: LayerKind) -> bool:
+        return item.kind == deck_type
+
+image_deck = PolicyBoundDeck(deck_type=LayerKind.IMAGE, policy=SameKindPolicy())
+image_deck.add("photo", Layer(LayerKind.IMAGE))     # OK
+image_deck.add("lines", Layer(LayerKind.VECTOR))    # Raises ValueError
+```
+
+### Subclass Compatibility
+
+For simpler cases, override `_is_compatible` directly:
+
+```python
+from vcti.deck import Deck
+
+class PositiveOnlyDeck(Deck[int]):
+    def _is_compatible(self, item: int) -> bool:
+        return item > 0
+
+deck = PositiveOnlyDeck()
+deck.add("a", 5)    # OK
+deck.add("b", -1)   # Raises ValueError
+```
+
+## API Summary
+
+### Deck[ItemT]
+
+| Method | Description |
+|--------|-------------|
+| `add(id, item, *, replace=False)` | Add item; raise if duplicate unless replace=True |
+| `get(id)` | Return item or None |
+| `has(id)` | Check if ID exists |
+| `remove(id)` | Remove item; raise if missing |
+| `set_order(ids)` | Set custom iteration order |
+| `clear_order()` | Reset to insertion order |
+| `ids()` | IDs in effective order |
+| `items()` | Items in effective order |
+
+### PolicyBoundDeck[DeckTypeT, ItemT]
+
+Extends `Deck` with:
+
+| Attribute/Method | Description |
+|-----------------|-------------|
+| `deck_type` | The type/category this deck is bound to |
+| `policy` | The `CompatibilityPolicy` instance |
+
+### CompatibilityPolicy[DeckTypeT, ItemT]
+
+| Method | Description |
+|--------|-------------|
+| `is_compatible(item, deck_type)` | Return True if item is allowed |
+
+## Dependencies
+
+None. Standard library only.

vcti_deck-1.0.1/README.md

@@ -0,0 +1,122 @@
+# Deck
+
+Generic ordered collection with named items and policy-based compatibility
+for Python.
+
+## Purpose
+
+VCollab applications need ordered collections where items are referenced
+by name, support custom ordering, and optionally enforce compatibility
+rules. `Deck` provides this as a lightweight, zero-dependency building
+block.
+
+## Installation
+
+```bash
+pip install vcti-deck
+```
+
+## Quick Start
+
+### Basic Deck
+
+```python
+from vcti.deck import Deck
+
+deck = Deck[str]()
+deck.add("header", "Welcome")
+deck.add("body", "Content")
+deck.add("footer", "Copyright")
+
+deck.get("header")    # "Welcome"
+deck.has("body")      # True
+"footer" in deck      # True
+len(deck)             # 3
+list(deck)            # ["Welcome", "Content", "Copyright"]
+```
+
+### Custom Ordering
+
+```python
+deck.set_order(["footer", "header"])
+list(deck)        # ["Copyright", "Welcome"] — body skipped
+deck.ids()        # ["footer", "header"]
+
+deck.clear_order()
+list(deck)        # ["Welcome", "Content", "Copyright"] — insertion order
+```
+
+### PolicyBoundDeck
+
+Use `PolicyBoundDeck` when items must satisfy compatibility rules:
+
+```python
+from enum import StrEnum, auto
+from vcti.deck import PolicyBoundDeck, CompatibilityPolicy
+
+class LayerKind(StrEnum):
+    IMAGE = auto()
+    VECTOR = auto()
+
+class Layer:
+    def __init__(self, kind: LayerKind):
+        self.kind = kind
+
+class SameKindPolicy(CompatibilityPolicy[LayerKind, Layer]):
+    def is_compatible(self, item: Layer, deck_type: LayerKind) -> bool:
+        return item.kind == deck_type
+
+image_deck = PolicyBoundDeck(deck_type=LayerKind.IMAGE, policy=SameKindPolicy())
+image_deck.add("photo", Layer(LayerKind.IMAGE))     # OK
+image_deck.add("lines", Layer(LayerKind.VECTOR))    # Raises ValueError
+```
+
+### Subclass Compatibility
+
+For simpler cases, override `_is_compatible` directly:
+
+```python
+from vcti.deck import Deck
+
+class PositiveOnlyDeck(Deck[int]):
+    def _is_compatible(self, item: int) -> bool:
+        return item > 0
+
+deck = PositiveOnlyDeck()
+deck.add("a", 5)    # OK
+deck.add("b", -1)   # Raises ValueError
+```
+
+## API Summary
+
+### Deck[ItemT]
+
+| Method | Description |
+|--------|-------------|
+| `add(id, item, *, replace=False)` | Add item; raise if duplicate unless replace=True |
+| `get(id)` | Return item or None |
+| `has(id)` | Check if ID exists |
+| `remove(id)` | Remove item; raise if missing |
+| `set_order(ids)` | Set custom iteration order |
+| `clear_order()` | Reset to insertion order |
+| `ids()` | IDs in effective order |
+| `items()` | Items in effective order |
+
+### PolicyBoundDeck[DeckTypeT, ItemT]
+
+Extends `Deck` with:
+
+| Attribute/Method | Description |
+|-----------------|-------------|
+| `deck_type` | The type/category this deck is bound to |
+| `policy` | The `CompatibilityPolicy` instance |
+
+### CompatibilityPolicy[DeckTypeT, ItemT]
+
+| Method | Description |
+|--------|-------------|
+| `is_compatible(item, deck_type)` | Return True if item is allowed |
+
+## Dependencies
+
+None. Standard library only.

vcti_deck-1.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-deck"
+version = "1.0.1"
+description = "Generic ordered collection with named items and policy-based compatibility"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.deck", "vcti.deck.*"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["pyright"]
+
+[tool.setuptools.package-data]
+"vcti.deck" = ["py.typed"]
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.deck --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_deck-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_deck-1.0.1/src/vcti/deck/__init__.py

@@ -0,0 +1,17 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.deck — generic ordered collection with named items and policy-based compatibility."""
+
+from importlib.metadata import version
+
+from .deck import Deck
+from .policy_bound_deck import CompatibilityPolicy, PolicyBoundDeck
+
+__version__ = version("vcti-deck")
+
+__all__ = [
+    "__version__",
+    "CompatibilityPolicy",
+    "Deck",
+    "PolicyBoundDeck",
+]

vcti_deck-1.0.1/src/vcti/deck/deck.py

@@ -0,0 +1,183 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Deck — a generic ordered collection with custom ordering support.
+
+A Deck maintains items in order with support for both insertion order and
+user-defined custom ordering. Each item is associated with a unique string
+identifier, making it suitable for collections where items need to be
+referenced by name and reordered flexibly.
+
+Example::
+
+    from vcti.deck import Deck
+
+    deck = Deck[str]()
+    deck.add("first", "Item 1")
+    deck.add("second", "Item 2")
+    deck.set_order(["second", "first"])
+    list(deck)  # Custom order: ['Item 2', 'Item 1']
+"""
+
+from collections import OrderedDict
+from collections.abc import Iterable, Iterator
+
+_MISSING: object = object()
+
+
+class Deck[ItemT]:
+    """A generic ordered collection of named items with compatibility and custom ordering.
+
+    This class provides a container that maintains items in a specific order,
+    with support for both insertion order and user-defined custom ordering.
+    Each item is associated with a unique string identifier.
+
+    This class is **not** thread-safe. External synchronisation is required
+    when a single ``Deck`` instance is accessed from multiple threads.
+
+    Items may be any value allowed by *ItemT*, including ``None``.  The
+    deck places no constraints on item values — only on item IDs (which
+    must be non-empty strings) and compatibility (via ``_is_compatible``).
+
+    Type Parameters:
+        ItemT: The type of items stored in the deck.
+    """
+
+    __slots__ = ("_items", "_user_order")
+
+    def __init__(self) -> None:
+        """Initialize an empty deck with no custom ordering."""
+        self._items: OrderedDict[str, ItemT] = OrderedDict()
+        self._user_order: list[str] | None = None
+
+    def add(self, item_id: str, item: ItemT, *, replace: bool = False) -> None:
+        """Add an item by ID, ensuring compatibility and maintaining insertion order.
+
+        Args:
+            item_id: Unique identifier for the item.
+            item: The item to add.
+            replace: If True, replace existing item with same ID; otherwise raise.
+
+        Raises:
+            ValueError: If item_id is not a non-empty string.
+            ValueError: If the item is incompatible (as determined by _is_compatible).
+            KeyError: If an item with the same ID already exists and replace is False.
+        """
+        if not isinstance(item_id, str) or not item_id:
+            raise ValueError(f"item_id must be a non-empty string, got {item_id!r}")
+
+        if not self._is_compatible(item):
+            raise ValueError(f"Incompatible item {item!r} can't be added.")
+
+        if item_id in self._items and not replace:
+            raise KeyError(f"Item with id '{item_id}' already exists.")
+
+        self._items[item_id] = item
+
+        if self._user_order is not None and item_id not in self._user_order:
+            self._user_order.append(item_id)
+
+    def get(self, item_id: str, default: ItemT | None = None) -> ItemT | None:
+        """Return an item by ID, or *default* if not found.
+
+        Args:
+            item_id: The identifier to look up.
+            default: Value to return when *item_id* is absent (default ``None``).
+        """
+        return self._items.get(item_id, default)
+
+    def has(self, item_id: str) -> bool:
+        """Check whether an item with the given ID exists."""
+        return item_id in self._items
+
+    def remove(self, item_id: str) -> None:
+        """Remove an item by ID.
+
+        Raises:
+            KeyError: If no item with the given ID exists.
+        """
+        try:
+            del self._items[item_id]
+        except KeyError:
+            raise KeyError(f"Item with id '{item_id}' not found.") from None
+
+        if self._user_order is not None and item_id in self._user_order:
+            self._user_order.remove(item_id)
+
+    def set_order(self, order: Iterable[str]) -> None:
+        """Define a custom user-specified order for iteration.
+
+        Only items listed in the provided order will be included in iteration.
+        Items not listed will be skipped.
+
+        Args:
+            order: Iterable of item IDs in the desired order.
+
+        Raises:
+            KeyError: If any ID in the order doesn't exist in the deck.
+            ValueError: If any ID appears more than once in the order.
+        """
+        order_list = list(order)
+
+        unknown = [oid for oid in order_list if oid not in self._items]
+        if unknown:
+            raise KeyError(f"Unknown item IDs in custom order: {unknown}")
+
+        seen: set[str] = set()
+        duplicates: list[str] = []
+        for oid in order_list:
+            if oid in seen:
+                duplicates.append(oid)
+            seen.add(oid)
+        if duplicates:
+            raise ValueError(f"Duplicate item IDs in custom order: {duplicates}")
+
+        self._user_order = order_list
+
+    def clear_order(self) -> None:
+        """Reset to insertion order, removing any custom ordering."""
+        self._user_order = None
+
+    def ids(self) -> list[str]:
+        """Return item IDs in the effective order (user-defined or insertion)."""
+        if self._user_order is not None:
+            return [oid for oid in self._user_order if oid in self._items]
+        return list(self._items.keys())
+
+    def items(self) -> list[ItemT]:
+        """Return items in the effective order."""
+        return [self._items[oid] for oid in self.ids()]
+
+    def _is_compatible(self, item: ItemT) -> bool:
+        """Hook for subclasses to implement item compatibility checks.
+
+        Override this method to enforce type-specific compatibility rules
+        when adding items to the deck. Returns True by default.
+        """
+        return True
+
+    def __iter__(self) -> Iterator[ItemT]:
+        """Iterate over items in the effective order.
+
+        Iteration uses a snapshot of the current order taken when iteration
+        begins. Items removed from the deck after the snapshot is taken are
+        silently skipped. Items added after the snapshot are not visited.
+        """
+        for oid in self.ids():
+            if oid in self._items:
+                yield self._items[oid]
+
+    def __len__(self) -> int:
+        """Return the number of items in the deck."""
+        return len(self._items)
+
+    def __contains__(self, item_id: object) -> bool:
+        """Check if an item ID exists in the deck.
+
+        Accepts any object to conform to the ``__contains__`` protocol.
+        Non-string values always return ``False``.
+        """
+        return item_id in self._items
+
+    def __repr__(self) -> str:
+        """Return a string representation showing item IDs."""
+        return f"{self.__class__.__name__}({list(self._items.keys())})"

vcti_deck-1.0.1/src/vcti/deck/policy_bound_deck.py

@@ -0,0 +1,99 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""PolicyBoundDeck — a Deck that enforces item compatibility via a pluggable policy.
+
+Example::
+
+    from vcti.deck import Deck, PolicyBoundDeck, CompatibilityPolicy
+
+    class PositiveOnly(CompatibilityPolicy[str, int]):
+        def is_compatible(self, item: int, deck_type: str) -> bool:
+            return item > 0
+
+    deck = PolicyBoundDeck(deck_type="positive", policy=PositiveOnly())
+    deck.add("a", 5)   # OK
+    deck.add("b", -1)  # Raises ValueError
+"""
+
+from abc import ABC, abstractmethod
+
+from .deck import Deck
+
+
+class CompatibilityPolicy[DeckTypeT, ItemT](ABC):
+    """Abstract base for compatibility policies.
+
+    Implement ``is_compatible`` to define rules governing which items
+    can be added to a deck of a given type.
+
+    Type Parameters:
+        DeckTypeT: The type/category of the deck.
+        ItemT: The type of items to validate.
+    """
+
+    @abstractmethod
+    def is_compatible(self, item: ItemT, deck_type: DeckTypeT) -> bool:
+        """Check if *item* is compatible with *deck_type*.
+
+        Returns:
+            True if the item may be added, False otherwise.
+        """
+        ...
+
+
+class PolicyBoundDeck[DeckTypeT, ItemT](Deck[ItemT]):
+    """A Deck bound to a compatibility policy.
+
+    Extends :class:`Deck` by delegating ``_is_compatible`` to an external
+    :class:`CompatibilityPolicy` instance. The policy is set at construction
+    time and cannot be changed.
+
+    Type Parameters:
+        DeckTypeT: The type/category of this deck.
+        ItemT: The type of items stored in this deck.
+
+    Example::
+
+        from enum import StrEnum, auto
+        from vcti.deck import PolicyBoundDeck, CompatibilityPolicy
+
+        class LayerKind(StrEnum):
+            IMAGE = auto()
+            VECTOR = auto()
+
+        class Layer:
+            def __init__(self, kind: LayerKind):
+                self.kind = kind
+
+        class SameKindPolicy(CompatibilityPolicy[LayerKind, Layer]):
+            def is_compatible(self, item: Layer, deck_type: LayerKind) -> bool:
+                return item.kind == deck_type
+
+        image_deck = PolicyBoundDeck(deck_type=LayerKind.IMAGE, policy=SameKindPolicy())
+        image_deck.add("img1", Layer(LayerKind.IMAGE))    # OK
+        image_deck.add("vec1", Layer(LayerKind.VECTOR))   # Raises ValueError
+    """
+
+    __slots__ = ("deck_type", "policy")
+
+    def __init__(
+        self,
+        deck_type: DeckTypeT,
+        policy: CompatibilityPolicy[DeckTypeT, ItemT],
+    ) -> None:
+        """Initialize with a deck type and a bound compatibility policy.
+
+        Args:
+            deck_type: The type/category of this deck, forwarded to the policy.
+            policy: The compatibility policy that governs item admission.
+        """
+        super().__init__()
+        self.deck_type = deck_type
+        self.policy = policy
+
+    def _is_compatible(self, item: ItemT) -> bool:
+        """Delegate compatibility check to the bound policy."""
+        return self.policy.is_compatible(item, self.deck_type)
+
+    def __repr__(self) -> str:
+        return f"PolicyBoundDeck(type={self.deck_type}, items={len(self)})"

vcti_deck-1.0.1/src/vcti_deck.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: vcti-deck
+Version: 1.0.1
+Summary: Generic ordered collection with named items and policy-based compatibility
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: pyright; extra == "typecheck"
+Dynamic: license-file
+
+# Deck
+
+Generic ordered collection with named items and policy-based compatibility
+for Python.
+
+## Purpose
+
+VCollab applications need ordered collections where items are referenced
+by name, support custom ordering, and optionally enforce compatibility
+rules. `Deck` provides this as a lightweight, zero-dependency building
+block.
+
+## Installation
+
+```bash
+pip install vcti-deck
+```
+
+## Quick Start
+
+### Basic Deck
+
+```python
+from vcti.deck import Deck
+
+deck = Deck[str]()
+deck.add("header", "Welcome")
+deck.add("body", "Content")
+deck.add("footer", "Copyright")
+
+deck.get("header")    # "Welcome"
+deck.has("body")      # True
+"footer" in deck      # True
+len(deck)             # 3
+list(deck)            # ["Welcome", "Content", "Copyright"]
+```
+
+### Custom Ordering
+
+```python
+deck.set_order(["footer", "header"])
+list(deck)        # ["Copyright", "Welcome"] — body skipped
+deck.ids()        # ["footer", "header"]
+
+deck.clear_order()
+list(deck)        # ["Welcome", "Content", "Copyright"] — insertion order
+```
+
+### PolicyBoundDeck
+
+Use `PolicyBoundDeck` when items must satisfy compatibility rules:
+
+```python
+from enum import StrEnum, auto
+from vcti.deck import PolicyBoundDeck, CompatibilityPolicy
+
+class LayerKind(StrEnum):
+    IMAGE = auto()
+    VECTOR = auto()
+
+class Layer:
+    def __init__(self, kind: LayerKind):
+        self.kind = kind
+
+class SameKindPolicy(CompatibilityPolicy[LayerKind, Layer]):
+    def is_compatible(self, item: Layer, deck_type: LayerKind) -> bool:
+        return item.kind == deck_type
+
+image_deck = PolicyBoundDeck(deck_type=LayerKind.IMAGE, policy=SameKindPolicy())
+image_deck.add("photo", Layer(LayerKind.IMAGE))     # OK
+image_deck.add("lines", Layer(LayerKind.VECTOR))    # Raises ValueError
+```
+
+### Subclass Compatibility
+
+For simpler cases, override `_is_compatible` directly:
+
+```python
+from vcti.deck import Deck
+
+class PositiveOnlyDeck(Deck[int]):
+    def _is_compatible(self, item: int) -> bool:
+        return item > 0
+
+deck = PositiveOnlyDeck()
+deck.add("a", 5)    # OK
+deck.add("b", -1)   # Raises ValueError
+```
+
+## API Summary
+
+### Deck[ItemT]
+
+| Method | Description |
+|--------|-------------|
+| `add(id, item, *, replace=False)` | Add item; raise if duplicate unless replace=True |
+| `get(id)` | Return item or None |
+| `has(id)` | Check if ID exists |
+| `remove(id)` | Remove item; raise if missing |
+| `set_order(ids)` | Set custom iteration order |
+| `clear_order()` | Reset to insertion order |
+| `ids()` | IDs in effective order |
+| `items()` | Items in effective order |
+
+### PolicyBoundDeck[DeckTypeT, ItemT]
+
+Extends `Deck` with:
+
+| Attribute/Method | Description |
+|-----------------|-------------|
+| `deck_type` | The type/category this deck is bound to |
+| `policy` | The `CompatibilityPolicy` instance |
+
+### CompatibilityPolicy[DeckTypeT, ItemT]
+
+| Method | Description |
+|--------|-------------|
+| `is_compatible(item, deck_type)` | Return True if item is allowed |
+
+## Dependencies
+
+None. Standard library only.

vcti_deck-1.0.1/src/vcti_deck.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/deck/__init__.py
+src/vcti/deck/deck.py
+src/vcti/deck/policy_bound_deck.py
+src/vcti/deck/py.typed
+src/vcti_deck.egg-info/PKG-INFO
+src/vcti_deck.egg-info/SOURCES.txt
+src/vcti_deck.egg-info/dependency_links.txt
+src/vcti_deck.egg-info/requires.txt
+src/vcti_deck.egg-info/top_level.txt
+src/vcti_deck.egg-info/zip-safe
+tests/test_deck.py
+tests/test_policy_bound_deck.py

vcti_deck-1.0.1/src/vcti_deck.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_deck-1.0.1/src/vcti_deck.egg-info/requires.txt

@@ -0,0 +1,10 @@
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov
+
+[typecheck]
+pyright

vcti_deck-1.0.1/src/vcti_deck.egg-info/top_level.txt

@@ -0,0 +1 @@
+vcti

vcti_deck-1.0.1/src/vcti_deck.egg-info/zip-safe

@@ -0,0 +1 @@
+

vcti_deck-1.0.1/tests/test_deck.py

@@ -0,0 +1,404 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for Deck."""
+
+import re
+
+import pytest
+
+import vcti.deck
+from vcti.deck import Deck
+
+
+class TestVersion:
+    def test_version_exists(self):
+        assert hasattr(vcti.deck, "__version__")
+
+    def test_version_is_valid_semver(self):
+        assert re.match(r"^\d+\.\d+\.\d+", vcti.deck.__version__)
+
+
+class TestDeckAdd:
+    def test_add_single(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        assert deck.get("a") == "alpha"
+        assert len(deck) == 1
+
+    def test_add_multiple_preserves_insertion_order(self):
+        deck = Deck[int]()
+        deck.add("x", 1)
+        deck.add("y", 2)
+        deck.add("z", 3)
+        assert deck.ids() == ["x", "y", "z"]
+        assert deck.items() == [1, 2, 3]
+
+    def test_add_duplicate_raises(self):
+        deck = Deck[str]()
+        deck.add("a", "first")
+        with pytest.raises(KeyError, match="already exists"):
+            deck.add("a", "second")
+
+    def test_add_duplicate_with_replace(self):
+        deck = Deck[str]()
+        deck.add("a", "first")
+        deck.add("a", "second", replace=True)
+        assert deck.get("a") == "second"
+        assert len(deck) == 1
+
+    def test_add_during_custom_order(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.set_order(["b", "a"])
+        deck.add("c", "gamma")
+        assert deck.ids() == ["b", "a", "c"]
+
+    def test_add_non_string_id_raises(self):
+        deck = Deck[str]()
+        with pytest.raises(ValueError, match="non-empty string"):
+            deck.add(123, "alpha")  # type: ignore[arg-type]
+
+    def test_add_none_id_raises(self):
+        deck = Deck[str]()
+        with pytest.raises(ValueError, match="non-empty string"):
+            deck.add(None, "alpha")  # type: ignore[arg-type]
+
+    def test_add_empty_string_id_raises(self):
+        deck = Deck[str]()
+        with pytest.raises(ValueError, match="non-empty string"):
+            deck.add("", "alpha")
+
+
+class TestDeckGet:
+    def test_get_existing(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        assert deck.get("a") == "alpha"
+
+    def test_get_missing_returns_none(self):
+        deck = Deck[str]()
+        assert deck.get("missing") is None
+
+    def test_get_missing_returns_default(self):
+        deck = Deck[str]()
+        assert deck.get("missing", "fallback") == "fallback"
+
+    def test_get_existing_ignores_default(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        assert deck.get("a", "fallback") == "alpha"
+
+    def test_get_distinguishes_none_value_from_missing(self):
+        sentinel = object()
+        deck = Deck[object | None]()
+        deck.add("a", None)
+        assert deck.get("a", sentinel) is None
+        assert deck.get("missing", sentinel) is sentinel
+
+
+class TestDeckHas:
+    def test_has_existing(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        assert deck.has("a") is True
+
+    def test_has_missing(self):
+        deck = Deck[str]()
+        assert deck.has("missing") is False
+
+
+class TestDeckContains:
+    def test_contains(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        assert "a" in deck
+        assert "b" not in deck
+
+    def test_contains_non_string_returns_false(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        assert 123 not in deck  # type: ignore[operator]
+        assert None not in deck  # type: ignore[operator]
+
+
+class TestDeckRemove:
+    def test_remove_existing(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.remove("a")
+        assert len(deck) == 0
+        assert deck.get("a") is None
+
+    def test_remove_missing_raises(self):
+        deck = Deck[str]()
+        with pytest.raises(KeyError, match="not found"):
+            deck.remove("missing")
+
+    def test_remove_updates_custom_order(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.set_order(["b", "a"])
+        deck.remove("b")
+        assert deck.ids() == ["a"]
+
+
+class TestDeckOrder:
+    def test_default_insertion_order(self):
+        deck = Deck[str]()
+        deck.add("c", "gamma")
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        assert deck.ids() == ["c", "a", "b"]
+
+    def test_set_order(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.add("c", "gamma")
+        deck.set_order(["c", "a", "b"])
+        assert deck.ids() == ["c", "a", "b"]
+        assert deck.items() == ["gamma", "alpha", "beta"]
+
+    def test_set_order_partial(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.add("c", "gamma")
+        deck.set_order(["b"])
+        assert deck.ids() == ["b"]
+
+    def test_set_order_unknown_id_raises(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        with pytest.raises(KeyError, match="Unknown"):
+            deck.set_order(["a", "missing"])
+
+    def test_set_order_duplicate_ids_raises(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        with pytest.raises(ValueError, match="Duplicate"):
+            deck.set_order(["a", "b", "a"])
+
+    def test_set_order_empty(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.set_order([])
+        assert deck.ids() == []
+        assert deck.items() == []
+        assert list(deck) == []
+
+    def test_clear_order(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.set_order(["b", "a"])
+        deck.clear_order()
+        assert deck.ids() == ["a", "b"]
+
+    def test_clear_order_noop_when_no_custom_order(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.clear_order()
+        assert deck.ids() == ["a"]
+
+
+class TestDeckIteration:
+    def test_iter(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        assert list(deck) == ["alpha", "beta"]
+
+    def test_iter_with_custom_order(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.set_order(["b", "a"])
+        assert list(deck) == ["beta", "alpha"]
+
+    def test_len(self):
+        deck = Deck[str]()
+        assert len(deck) == 0
+        deck.add("a", "alpha")
+        assert len(deck) == 1
+
+    def test_repr(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        assert "Deck" in repr(deck)
+        assert "'a'" in repr(deck)
+
+
+class TestDeckIterationMutation:
+    def test_remove_during_iteration_skips_removed(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.add("c", "gamma")
+        collected = []
+        for item in deck:
+            collected.append(item)
+            if item == "alpha":
+                deck.remove("b")
+        assert collected == ["alpha", "gamma"]
+
+    def test_add_during_iteration_not_visited(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        collected = []
+        for item in deck:
+            collected.append(item)
+            if item == "alpha":
+                deck.add("c", "gamma")
+        assert collected == ["alpha", "beta"]
+        assert deck.has("c")
+
+    def test_set_order_during_iteration_no_effect(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.add("c", "gamma")
+        collected = []
+        for item in deck:
+            collected.append(item)
+            if item == "alpha":
+                deck.set_order(["c", "b", "a"])
+        assert collected == ["alpha", "beta", "gamma"]
+
+    def test_clear_order_during_iteration_no_effect(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.set_order(["b", "a"])
+        collected = []
+        for item in deck:
+            collected.append(item)
+            if item == "beta":
+                deck.clear_order()
+        assert collected == ["beta", "alpha"]
+
+    def test_remove_all_during_iteration(self):
+        deck = Deck[str]()
+        deck.add("a", "alpha")
+        deck.add("b", "beta")
+        deck.add("c", "gamma")
+        collected = []
+        for item in deck:
+            collected.append(item)
+            deck.remove("a")
+            deck.remove("b")
+            deck.remove("c")
+            break
+        assert collected == ["alpha"]
+        assert len(deck) == 0
+
+
+class TestDeckEmpty:
+    def test_empty_iter(self):
+        assert list(Deck()) == []
+
+    def test_empty_ids(self):
+        assert Deck().ids() == []
+
+    def test_empty_items(self):
+        assert Deck().items() == []
+
+    def test_empty_len(self):
+        assert len(Deck()) == 0
+
+    def test_empty_repr(self):
+        assert repr(Deck()) == "Deck([])"
+
+
+class TestDeckCompatibility:
+    def test_default_compatibility_accepts_all(self):
+        deck = Deck[object]()
+        deck.add("a", 42)
+        deck.add("b", "hello")
+        deck.add("c", [1, 2, 3])
+        assert len(deck) == 3
+
+    def test_subclass_can_reject(self):
+        class PositiveOnlyDeck(Deck[int]):
+            def _is_compatible(self, item: int) -> bool:
+                return item > 0
+
+        deck = PositiveOnlyDeck()
+        deck.add("a", 5)
+        with pytest.raises(ValueError, match="Incompatible"):
+            deck.add("b", -1)
+
+    def test_none_item_allowed(self):
+        deck = Deck[None]()
+        deck.add("a", None)
+        assert deck.get("a") is None
+        assert list(deck) == [None]
+
+
+class TestDeckReentrant:
+    def test_set_order_inside_is_compatible(self):
+        """Calling set_order from within _is_compatible must not corrupt state."""
+
+        class ReorderingDeck(Deck[str]):
+            def _is_compatible(self, item: str) -> bool:
+                if len(self._items) >= 2:
+                    self.set_order(sorted(self._items.keys()))
+                return True
+
+        deck = ReorderingDeck()
+        deck.add("b", "beta")
+        deck.add("a", "alpha")
+        deck.add("c", "gamma")
+        # set_order was called inside _is_compatible for "c"
+        assert deck.has("c")
+        assert set(deck.ids()) == {"a", "b", "c"}
+
+    def test_remove_inside_is_compatible(self):
+        """Calling remove from within _is_compatible must not corrupt state."""
+
+        class EvictingDeck(Deck[str]):
+            def _is_compatible(self, item: str) -> bool:
+                if self.has("evict_me"):
+                    self.remove("evict_me")
+                return True
+
+        deck = EvictingDeck()
+        deck.add("evict_me", "temporary")
+        deck.add("keeper", "permanent")
+        assert not deck.has("evict_me")
+        assert deck.has("keeper")
+
+
+class TestDeckScale:
+    def test_add_and_iterate_1000_items(self):
+        deck = Deck[int]()
+        n = 1_000
+        for i in range(n):
+            deck.add(f"item{i}", i)
+        assert len(deck) == n
+        assert list(deck) == list(range(n))
+
+    def test_custom_order_1000_items(self):
+        deck = Deck[int]()
+        n = 1_000
+        for i in range(n):
+            deck.add(f"item{i}", i)
+        reversed_ids = [f"item{i}" for i in reversed(range(n))]
+        deck.set_order(reversed_ids)
+        assert deck.ids() == reversed_ids
+        assert deck.items() == list(reversed(range(n)))
+
+    def test_add_remove_cycle_1000(self):
+        deck = Deck[int]()
+        n = 1_000
+        for i in range(n):
+            deck.add(f"item{i}", i)
+        for i in range(n):
+            deck.remove(f"item{i}")
+        assert len(deck) == 0
+        assert list(deck) == []

vcti_deck-1.0.1/tests/test_policy_bound_deck.py

@@ -0,0 +1,123 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for PolicyBoundDeck."""
+
+from enum import StrEnum, auto
+
+import pytest
+
+from vcti.deck import CompatibilityPolicy, PolicyBoundDeck
+
+
+class Kind(StrEnum):
+    ALPHA = auto()
+    BETA = auto()
+
+
+class Item:
+    def __init__(self, kind: Kind):
+        self.kind = kind
+
+
+class SameKindPolicy(CompatibilityPolicy[Kind, Item]):
+    def is_compatible(self, item: Item, deck_type: Kind) -> bool:
+        return item.kind == deck_type
+
+
+class AcceptAllPolicy(CompatibilityPolicy[str, int]):
+    def is_compatible(self, item: int, deck_type: str) -> bool:
+        return True
+
+
+class RejectAllPolicy(CompatibilityPolicy[str, int]):
+    def is_compatible(self, item: int, deck_type: str) -> bool:
+        return False
+
+
+class TestPolicyBoundDeckBasic:
+    def test_compatible_item_accepted(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        item = Item(Kind.ALPHA)
+        deck.add("a", item)
+        assert deck.get("a") is item
+
+    def test_incompatible_item_rejected(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        item = Item(Kind.BETA)
+        with pytest.raises(ValueError, match="Incompatible"):
+            deck.add("b", item)
+
+    def test_accept_all_policy(self):
+        deck = PolicyBoundDeck(deck_type="any", policy=AcceptAllPolicy())
+        deck.add("a", 1)
+        deck.add("b", 2)
+        assert len(deck) == 2
+
+    def test_reject_all_policy(self):
+        deck = PolicyBoundDeck(deck_type="none", policy=RejectAllPolicy())
+        with pytest.raises(ValueError, match="Incompatible"):
+            deck.add("a", 1)
+
+
+class TestPolicyBoundDeckAttributes:
+    def test_deck_type_stored(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        assert deck.deck_type == Kind.ALPHA
+
+    def test_policy_stored(self):
+        policy = SameKindPolicy()
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=policy)
+        assert deck.policy is policy
+
+
+class TestPolicyBoundDeckInheritsOrdering:
+    def test_custom_order(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        deck.add("a", Item(Kind.ALPHA))
+        deck.add("b", Item(Kind.ALPHA))
+        deck.add("c", Item(Kind.ALPHA))
+        deck.set_order(["c", "a", "b"])
+        assert deck.ids() == ["c", "a", "b"]
+
+    def test_remove(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        deck.add("a", Item(Kind.ALPHA))
+        deck.remove("a")
+        assert len(deck) == 0
+
+    def test_replace(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        item1 = Item(Kind.ALPHA)
+        item2 = Item(Kind.ALPHA)
+        deck.add("a", item1)
+        deck.add("a", item2, replace=True)
+        assert deck.get("a") is item2
+
+
+class TestCompatibilityPolicyIsAbstract:
+    def test_cannot_instantiate_base(self):
+        with pytest.raises(TypeError, match="abstract"):
+            CompatibilityPolicy()
+
+    def test_incomplete_subclass_cannot_instantiate(self):
+        class Incomplete(CompatibilityPolicy[str, int]):
+            pass
+
+        with pytest.raises(TypeError, match="abstract"):
+            Incomplete()
+
+    def test_replace_still_checks_compatibility(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        deck.add("a", Item(Kind.ALPHA))
+        with pytest.raises(ValueError, match="Incompatible"):
+            deck.add("a", Item(Kind.BETA), replace=True)
+
+
+class TestPolicyBoundDeckRepr:
+    def test_repr(self):
+        deck = PolicyBoundDeck(deck_type=Kind.ALPHA, policy=SameKindPolicy())
+        deck.add("a", Item(Kind.ALPHA))
+        r = repr(deck)
+        assert "PolicyBoundDeck" in r
+        assert "alpha" in r
+        assert "items=1" in r