002. Immutable State Management¶
Status¶
Accepted
Context¶
Application frameworks must manage global state including configuration, platform directories, distribution information, and resource handles. Mutable global state creates thread safety issues, debugging complexity, and unexpected side effects.
Python’s dataclass system provides immutable patterns, and accretive data structures offer append-only dictionary implementations. The framework needs predictable state management that supports concurrent access patterns.
Decision¶
Use immutable dataclasses for all application state management. The Globals
dataclass contains all framework state as immutable fields. Configuration is
stored as accretive dictionary objects that are immutable after assignment.
State updates create new instances rather than modifying existing ones.
Alternatives¶
- Mutable global state with locking
Rejected: Would require complex locking strategies and error-prone thread safety
Rejected: Would create debugging difficulties and unpredictable behavior
- Traditional singleton patterns
Rejected: Would prevent testing with different configurations
Rejected: Would create hidden dependencies and coupling
- Context manager state isolation
Rejected: Would complicate API and require complex context propagation
Considered but rejected due to integration complexity with CLI patterns
Consequences¶
- Positive
Thread safety guaranteed without explicit locking
Predictable behavior and easier debugging
State updates are explicit and traceable
Testing isolation through independent state instances
Clear dependency injection patterns
- Negative
Slight memory overhead from creating new instances for updates
Learning curve for developers expecting mutable global state
Requires careful design of state update patterns
- Neutral
Aligns with functional programming principles increasingly common in Python
Immutable patterns becoming standard in modern application frameworks