Mental Model: TUI Spreadsheet in Python

A beginner spreadsheet is not a giant table. It’s a dictionary plus rules.

Core Mental Model

Two pieces power the whole tool:

1. Storage: dict[str, str] maps cell key to raw content.
2. Evaluation: formulas convert raw content into computed values.

Raw content is what users typed. Evaluated value is what users see.

Why dict Is the Right Primitive

Python’s dict is perfect for sparse sheets.

• only store touched cells
• fast lookup by cell name (A1, B3)
• easy save/load serialization

No need for a pre-sized grid when learning fundamentals.

Formula Evaluation as Pipeline

Treat evaluation like a pipeline:

• normalize expression
• split tokens (left + right)
• resolve each token to a number
• compute or return error code

That pipeline mindset transfers directly to parser work later.

Python-Specific Insight

Small helper functions keep complexity down.

• normalize_cell protects the storage boundary
• _number_value isolates conversion
• _evaluate focuses only on formula logic

This is Pythonic decomposition: small functions, clear intent.

Debugging Order

When value output is wrong, inspect in order:

1. normalized key
2. stored raw string
3. token conversion
4. final arithmetic

You’ll usually find the bug quickly.

Good Next Steps

Add one feature at a time:

• subtraction and multiplication
• parentheses support
• circular reference protection

Just keep the same model: store raw, evaluate safely, display clearly.