Spectate: Track Mutable Data Changes

1.0.1 · active · verified Fri Apr 17

Spectate (v1.0.1) is a Python library designed to track changes to mutable data types, providing undo/redo capabilities for operations on objects like dictionaries and lists. It achieves this by wrapping functions that modify tracked objects, recording events for each change. The library is currently feature-complete and in maintenance mode, with a slow release cadence.

Common errors

```
AttributeError: 'dict' object has no attribute 'some_attribute'
```
cause Attempting attribute access on an event object (e.g., `event.foo`) after upgrading to spectate v1.0.0+, where event objects are standard Python dictionaries.

fix Access event data using dictionary key notation: `event['some_attribute']`.
```
ImportError: cannot import name 'Immutable' from 'spectate.utils'
```
cause Trying to import the `Immutable` class, which was removed from `spectate.utils` in v1.0.0.

fix Remove the `from spectate.utils import Immutable` statement. Spectate no longer uses this class internally, and event objects are now standard dictionaries.
```
TypeError: rollback() missing 1 required positional argument: 'undo'
```
cause Calling `spectate.events.rollback()` without providing the mandatory `undo` argument, which was introduced in v1.0.0.

fix Pass the `undo` argument when calling `spectate.events.rollback()`, for example: `spectate.events.rollback(my_undo_function)`.

Warnings

breaking Event objects returned by Spectate (e.g., from `spectate.events.current_event()`) are now standard Python dictionaries, not `Immutable` (dict-like) objects with attribute access.
Fix: Access event data using standard dictionary key notation (e.g., `event['key']`) instead of attribute access (e.g., `event.key`).
breaking The `spectate.utils.Immutable` class has been completely removed.
Fix: Remove any direct imports or references to `spectate.utils.Immutable`. If you were creating custom immutable objects, you'll need to refactor to use standard Python dicts or create your own immutable wrappers.
breaking The `undo` parameter for `spectate.events.rollback()` is now required.
Fix: Ensure `spectate.events.rollback()` is called with the `undo` parameter, e.g., `spectate.events.rollback(undo_action_function)`.

Install

pip install spectate Install stable version

Imports

track
```
from spectate import track
```
undo
```
from spectate import undo
```
redo
```
from spectate import redo
```
rollback
```
from spectate import rollback
```
Immutable
wrong:
```
from spectate.utils import Immutable
```
correct:
```
N/A (removed)
```
The `Immutable` class was removed in v1.0.0. Event objects are now standard Python dicts.

Quickstart

This example demonstrates how to use `spectate.track` to observe changes to a dictionary, and then `undo` and `redo` those changes. The `@track` decorator wraps the `add_entry` function, automatically recording each modification to the dictionary `a`.

from spectate import track, undo, redo

a = {}

@track(a)
def add_entry(key, value):
    a[key] = value

add_entry('x', 1)
add_entry('y', 2)
print(f"Initial state: {a}")

undo()
print(f"After first undo: {a}")

undo()
print(f"After second undo: {a}")

redo()
print(f"After first redo: {a}")

redo()
print(f"After second redo: {a}")

view raw JSON →