Collections and Data Structures in the Sifr Stdlib

Sifr’s sifr.collections module provides the familiar Python collection types you already know — Counter, deque, defaultdict, plus set construction and operation helpers — with one important safety improvement: indexing operations that could fail return Option instead of raising KeyError or IndexError. You get compile-time visibility into every case where a lookup might not find a value.

Importing

from sifr.collections import Counter, from_list, deque, set_from_list, set_union, set_intersection, set_len

Do not use bare import collections — that triggers SIFR-IMPORT-0008. Always use from sifr.collections import ....

Lists

Standard list[T] is a first-class language type in Sifr. You do not need to import it. Lists are mutable, ordered, and support all comprehension forms:

numbers: list[int] = [1, 2, 3, 4, 5]
squares: list[int] = [x * x for x in numbers]
evens: list[int] = [x for x in numbers if x % 2 == 0]

Appending to a list requires the mut qualifier on the binding that owns it:

def append_all(mut target: list[bool], values: list[bool]):
    for value in values:
        target.append(value)

For the core language model behind lists, dictionaries, optional values, and iteration, see Values and Collections and Iteration.

Dicts and Tuples

dict[K, V] and tuple[T, ...] are built-in types. Dict literals and comprehensions work exactly as in Python:

scores: dict[str, int] = {"alice": 42, "bob": 17}
doubled: dict[str, int] = {k: v * 2 for k, v in scores.items()}

Safe access via .get(key) returns Option[V] (either the value or None). Direct indexing uses the same panic-free contract: scores["missing"] returns None instead of raising KeyError.

maybe_score: int | None = scores["charlie"]
if maybe_score is not None:
    print(maybe_score)

Sets

Sifr represents sets as deduplicated list[T] values constructed through the helper functions in sifr.collections. This keeps ownership unambiguous while providing the set operations you need:

from sifr.collections import set_from_list, set_union, set_intersection, set_len

left: list[int] = set_from_list([1, 2, 3])
right: list[int] = set_from_list([3, 4, 5])

union_set: list[int] = set_union(left, right)       # [1, 2, 3, 4, 5]
inter_set: list[int] = set_intersection(left, right) # [3]

print(set_len(union_set))        # 5
print(set_len(inter_set))        # 1

Counter

Counter[T] counts occurrences of hashable values. Build one from a list with from_list, then query counts or pull the most-common elements:

from sifr.collections import Counter, from_list

counts: Counter[str] = from_list(["x", "y", "x", "z", "x", "y"])

print(counts.get("x"))            # 3
print(counts.most_common(2))      # [("x", 3), ("y", 2)]

counts.get(key) returns the integer count for that key (0 if unseen). most_common(n) returns the top-n (value, count) pairs in descending order, exactly as Python’s Counter.most_common does.

deque

deque[T] is a double-ended queue. Pass maxlen to create a bounded deque that automatically drops the oldest element when capacity is exceeded — useful for sliding windows and ring buffers:

from sifr.collections import deque

d: deque[int] = deque(maxlen=2)
d.append(10)
d.append(20)
d.append(30)   # drops 10 because maxlen=2

print(d.len())       # 2
print(d.popleft())   # 20

pop() on an empty deque returns None rather than raising IndexError. Check the return value before using it:

value = d.pop()
if value is not None:
    print(value)

Full Demo

The following is the complete collections demo from the Sifr repository, showing sets, Counter, and deque working together:

from sifr.collections import Counter, from_list, deque, set_from_list, set_union, set_intersection, set_len

def collect_set_and_counter_checks() -> list[bool]:
    checks: list[bool] = []
    left: list[int] = set_from_list([1, 2, 3])
    right: list[int] = set_from_list([3, 4, 5])
    checks.append(set_len(set_union(left, right)) == 5)
    checks.append(set_len(set_intersection(left, right)) == 1)

    counts: Counter[str] = from_list(["x", "y", "x", "z", "x", "y"])
    checks.append(counts.get("x") == 3)
    checks.append(str(counts.most_common(2)) == "[(\"x\", 3), (\"y\", 2)]")
    return checks

def collect_deque_checks() -> list[bool]:
    checks: list[bool] = []
    d: deque[int] = deque(maxlen=2)
    d.append(10)
    d.append(20)
    d.append(30)
    checks.append(d.len() == 2 and d.popleft() == 20)

    _ = d.pop()
    checks.append(d.pop() is None)
    return checks

def append_all(mut target: list[bool], values: list[bool]):
    for value in values:
        target.append(value)

def main():
    checks: list[bool] = []
    append_all(checks, collect_set_and_counter_checks())
    append_all(checks, collect_deque_checks())

    all_passed: bool = True
    for check in checks:
        if not check:
            all_passed = False
    print("collections demo: " + ("pass" if all_passed else "FAIL"))

JSON and Serialization

For working with JSON data structures, use sifr.json alongside your collections:

from sifr.json import JsonValue, loads, dumps

try:
    parsed_obj: JsonValue = loads("{\"name\":\"sifr\"}")
    parsed_arr: JsonValue = loads("[1,2,3]")
    roundtrip: JsonValue = loads(dumps(7))

    print(str(parsed_obj))  # {"name":"sifr"}
    print(str(parsed_arr))  # [1,2,3]
    print(str(roundtrip))   # 7
except JSONDecodeError as e:
    print(e.message)

loads raises JSONDecodeError on malformed input. Use a try/except block whenever parsing untrusted data.

Get Started

Learn Sifr

CLI

Package Management

Standard Library

Concurrency

Error Codes

Collections and Data Structures in the Sifr Stdlib

Importing

Lists

Dicts and Tuples

Sets

Counter

deque

Full Demo

JSON and Serialization

​Importing

​Lists

​Dicts and Tuples

​Sets

​Counter

​deque

​Full Demo

​JSON and Serialization

Importing

Lists

Dicts and Tuples

Sets

Counter

deque

Full Demo

JSON and Serialization