bigbrother

Mutation callbacks for Python objects.

bigbrother watches mutable Python objects and calls your callback when they change. It is useful when another layer needs to mark state dirty, schedule a refresh, or react to model changes without replacing every mutation call.

Install

pip install bigbrother

Example

from bigbrother import watch

changes = []


def track_change(obj, method, ref, call_args, call_kwargs):
    changes.append((method, call_args, call_kwargs))


state = watch({"items": []}, track_change, deepstate=True)
state["items"].append("alpha")

assert changes[-1] == ("append", ("alpha",), {})

Keep the object returned by watch(). Built-in containers are observed by returning watched container instances.

Supported Objects

bigbrother supports:

• list, dict, and set
• pydantic.BaseModel
• plain Python objects and dataclasses with a __dict__

Objects without a __dict__, such as slot-only classes, are returned unchanged. Callbacks fire before the underlying mutation completes.

Documentation

• API reference

Development

make develop
python -m pytest bigbrother/tests -q

License

bigbrother is licensed under Apache-2.0.