Deck
Generic ordered collection with named items and policy-based compatibility for Python.
Overview
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
pip install vcti-deck
Quick Start
Basic Deck
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
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:
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:
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.
Documentation
| If you want to… | Read |
|---|---|
| Get started using the package | Quick Start above |
| Understand the architecture and design decisions | docs/design.md |
| See practical, real-world usage | docs/patterns.md |
| Navigate and understand the source | docs/source-guide.md |
| Extend the library with custom policies | docs/extending.md |
| Look up a specific function or type | docs/api.md |
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
vcti_deck-1.1.0.tar.gz
(10.0 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file vcti_deck-1.1.0.tar.gz.
File metadata
- Download URL: vcti_deck-1.1.0.tar.gz
- Upload date:
- Size: 10.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ba32202e213fa5eed851accd9ba35482d139c627b914f964d6faa91538eaefd3
|
|
| MD5 |
033e6da9cf540ed7fe4281892d33ceda
|
|
| BLAKE2b-256 |
0dc9b07499be94a79baa29b9301ab42b5e1c932ddae32589fc08e97b1595704c
|
Provenance
The following attestation bundles were made for vcti_deck-1.1.0.tar.gz:
Publisher:
release.yml on vcollab/vcti-python-deck
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
vcti_deck-1.1.0.tar.gz -
Subject digest:
ba32202e213fa5eed851accd9ba35482d139c627b914f964d6faa91538eaefd3 - Sigstore transparency entry: 2195639376
- Sigstore integration time:
-
Permalink:
vcollab/vcti-python-deck@858b8fe2916b40faabe57907c5f749fa7e8b0797 -
Branch / Tag:
refs/tags/v1.1.0 - Owner: https://github.com/vcollab
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@858b8fe2916b40faabe57907c5f749fa7e8b0797 -
Trigger Event:
push
-
Statement type:
File details
Details for the file vcti_deck-1.1.0-py3-none-any.whl.
File metadata
- Download URL: vcti_deck-1.1.0-py3-none-any.whl
- Upload date:
- Size: 7.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fffb53cccbaf962f1435ceb3778334b4e7f7133417346f61843a7ca68fa15bd5
|
|
| MD5 |
21ca408bdf794db354e0f4df9726b923
|
|
| BLAKE2b-256 |
017611bc9e783a7f5949c2a09d1757ee0f31473c39dc90848aac879aed9d1e39
|
Provenance
The following attestation bundles were made for vcti_deck-1.1.0-py3-none-any.whl:
Publisher:
release.yml on vcollab/vcti-python-deck
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
vcti_deck-1.1.0-py3-none-any.whl -
Subject digest:
fffb53cccbaf962f1435ceb3778334b4e7f7133417346f61843a7ca68fa15bd5 - Sigstore transparency entry: 2195639382
- Sigstore integration time:
-
Permalink:
vcollab/vcti-python-deck@858b8fe2916b40faabe57907c5f749fa7e8b0797 -
Branch / Tag:
refs/tags/v1.1.0 - Owner: https://github.com/vcollab
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@858b8fe2916b40faabe57907c5f749fa7e8b0797 -
Trigger Event:
push
-
Statement type:
