python-immutable-accumulator

What problem does it solve?

Mutable state accumulation is a common source of bugs, making debugging, reasoning about code, and concurrent execution unpredictable. This pattern uses a frozen dataclass with slots and a tuple to store records so that every update yields a new, immutable instance, eliminating shared mutable state and enabling safer reasoning about state changes.

Core Features & Use Cases

• Core Pattern: immutable accumulation by returning a new instance from add(), enabled by frozen=True and slots=True dataclasses.
• Safe totals and iteration: lightweight, hashable containers support straightforward aggregation and traversal.
• Pydantic Variant: optional model-based variant for environments that rely on Pydantic for validation.
• Thread-safe and functional style: natural fit for pipelines and parallel processing without side effects.
• Practical guidance: designed for use in cost tracking, event sourcing, and stateful workflows requiring reproducibility.

Quick Start

Create an empty Accumulator and repeatedly call add() with Record instances to build an immutable sequence.