# Python Data Model Benchmarks

Comprehensive benchmarks comparing dataclasses, Pydantic, and SQLAlchemy across multiple Python versions.

## Overview

This benchmark compares three popular Python data modeling approaches:

- **dataclasses**: Python standard library (3.7+) for simple data containers
- **Pydantic**: Data validation library using Python type hints
- **SQLAlchemy**: Full-featured database ORM

## Methodology

### Test Operations

Each library is tested on three core operations:

1. **Object Creation**: Creating new instances with data
2. **Object Modification**: Updating attributes on existing instances
3. **Object Serialization**: Converting objects to dictionaries

### Test Parameters

- **Iterations**: 10,000 objects created per test
- **Modifications**: 100 objects modified 10,000 times each
- **Serialization**: 100 objects serialized 100 times each
- **SQLAlchemy**: Uses in-memory SQLite database (`:memory:`)

### Python Versions Tested

- Python 3.10.18
- Python 3.11.12
- Python 3.12.10
- Python 3.13.5
- Python 3.14.0rc1 (failed - PyO3 not yet compatible)

## Key Results

### Average Relative Performance (dataclass = 1.0x)

| Library    | Object Creation | Modification | Serialization |
| ---------- | --------------- | ------------ | ------------- |
| dataclass  | 1.0x            | 1.0x         | 1.0x          |
| pydantic   | 1.5x            | 1.1x         | 0.3x          |
| sqlalchemy | 39.5x           | 134.4x       | 0.9x          |

### Key Findings

1. **Object Creation**:
   - Dataclasses and Pydantic have similar performance
   - SQLAlchemy is ~40x slower due to database operations

2. **Object Modification**:
   - Dataclasses and Pydantic are nearly identical
   - SQLAlchemy is ~134x slower due to transaction overhead

3. **Object Serialization**:
   - Pydantic is ~3x faster than dataclasses
   - SQLAlchemy is slightly faster than dataclasses

4. **Python Version Impact**:
   - Python 3.13 shows significant improvements (especially for dataclasses)
   - Performance generally improves with newer Python versions

## Reproducing the Benchmarks

### Requirements

- Python 3.10+
- uv (Python package manager)

### Running Benchmarks

```bash
# Run for a specific Python version
uv run --python 3.13 --with pydantic,sqlalchemy python3 benchmark.py

# Run for all versions (in sequence)
for version in 3.10 3.11 3.12 3.13; do
    uv run --python $version --with pydantic,sqlalchemy python3 benchmark.py
done

# Analyze results
python3 analyze.py
```

### Output Files

- `results_python_X.Y.Z.json`: Raw benchmark data for each Python version
- `summary.json`: Aggregated results in JSON format
- `summary.md`: Markdown summary table

## Important Notes

### Benchmark Limitations

1. **SQLAlchemy includes database operations**: The timing includes actual database writes and transactions, not just object creation
2. **Pydantic includes validation**: Type checking and validation are performed during object creation
3. **Simple test case**: Real-world performance depends on data complexity and validation rules

### When to Use Each

- **dataclasses**: Internal data structures, maximum performance, no validation needed
- **Pydantic**: External data (APIs, configs), automatic validation, JSON serialization
- **SQLAlchemy**: Database persistence, complex queries, relationships

## Scripts

### benchmark.py

Main benchmark script that:

- Defines equivalent User models for each library
- Runs timed tests for creation, modification, and serialization
- Outputs results to JSON files

### analyze.py

Analysis script that:

- Loads all result files
- Calculates relative performance metrics
- Generates summary tables and markdown output

## Future Work

- Add more complex data models (nested objects, relationships)
- Test additional operations (validation errors, bulk operations)
- Compare memory usage
- Add attrs and other alternatives
- Wait for Python 3.14 support in PyO3/pydantic-core