Alma — Time-Travel Variable Framework

"What if every variable remembered where it came from?"

Alma is a lightweight, thread-safe Python framework that wraps ordinary values in observable, auditable containers — giving you a complete mutation history and the ability to roll back to any past state.

Installation

No external dependencies. Copy alma.py into your project or install once a package is published:

pip install alma   # (future)

Quick start

import alma

# 1. Create a watched variable
score = alma.watch("score", 0)

# 2. Mutate it
score.set(10).set(20).set(30)   # fluent chaining

# 3. Inspect
print(score.get())              # 30
print(score.last_change())      # ChangeRecord(index=3, value=30, ...)

# 4. Full audit trail
for record in score.history():
    print(record)

# 5. Time-travel
score.rollback(1)               # back to 10
print(score.get())              # 10

# 6. Restore initial value
score.reset()
print(score.get())              # 0

API reference

alma.watch(name, initial_value, *, deep_copy=True, validators=None, on_change=None, overwrite=False) → AlmaVar

Create a watched variable in the global default registry.

AlmaVar

ChangeRecord

Immutable dataclass stored in every variable's history.

@dataclass(frozen=True)
class ChangeRecord:
    index:     int
    value:     Any
    timestamp: datetime   # UTC
    label:     str | None

Advanced usage

Validators

def must_be_positive(v):
    if v < 0:
        raise ValueError(f"Expected positive, got {v}")

balance = alma.watch("balance", 100.0)
balance.add_validator(must_be_positive)

balance.set(50)    # OK
balance.set(-1)    # raises ValueError

Change listeners

import logging

def audit(var, record):
    logging.info("[%s] → %r  (index=%d)", var.name, record.value, record.index)

price = alma.watch("price", 9.99, on_change=[audit])
price.set(12.49)   # logs immediately

Freeze a variable

config = alma.watch("config", {"debug": True})
config.freeze()
config.set({"debug": False})   # raises FrozenError

Working with the registry directly

from alma import AlmaRegistry

reg = AlmaRegistry()
x = reg.watch("x", 0)
y = reg.watch("y", 100)

print(reg.snapshot())      # {"x": 0, "y": 100}
print(reg.all_vars())      # {"x": AlmaVar(...), "y": AlmaVar(...)}
reg.unregister("x")

Running tests

pip install pytest
pytest test_alma.py -v

Suggested future extensions