Skip to main content

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

Metadata

Release files for vcti-deck 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcti-deck 1.1.0
File Size Uploaded Provenance Actions
vcti_deck-1.1.0.tar.gz 10.0 kB With provenance Details for vcti_deck-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-deck 1.1.0
File Interpreter ABI Platform Actions
vcti_deck-1.1.0-py3-none-any.whl Python 3 none any Details for vcti_deck-1.1.0-py3-none-any.whl

Total release size: 17.4 kB

Release files / vcti_deck-1.1.0.tar.gz

Download URL vcti_deck-1.1.0.tar.gz
Size 10.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ba32202e213fa5eed851accd9ba35482d139c627b914f964d6faa91538eaefd3
BLAKE2b-256 checksum
How to use checksums
0dc9b07499be94a79baa29b9301ab42b5e1c932ddae32589fc08e97b1595704c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / vcti_deck-1.1.0-py3-none-any.whl

Download URL vcti_deck-1.1.0-py3-none-any.whl
Size 7.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fffb53cccbaf962f1435ceb3778334b4e7f7133417346f61843a7ca68fa15bd5
BLAKE2b-256 checksum
How to use checksums
017611bc9e783a7f5949c2a09d1757ee0f31473c39dc90848aac879aed9d1e39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Security for vcti-deck 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vcti_deck-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page