Add documentation on how to run benchmarks locally

benchmarks/README.md

@@ -0,0 +1,49 @@
+# Benchmarks
+
+Here we document how to run various performance benchmarks about 
+serialization, validation, struct, gc and memory usage.
+
+## Setup
+
+Benchmark additional dependencies are included in the bench extra so you will have to run this:
+```bash
+pip install -e ".[dev, bench]"
+```
+
+If you want to run the benchmarks against pydantic v1, you'll have to explicitly
+downgrade using this command:
+```bash
+pip install "pydantic<2"
+```
+
+## Running Benchmarks
+
+```bash
+# JSON Serialization & Validation
+python -m benchmarks.bench_validation
+
+# JSON/MessagePack serialization
+python benchmarks/bench_encodings.py --protocol json
+python benchmarks/bench_encodings.py --protocol msgpack
+
+# JSON Serialization - Large Data
+python benchmarks/bench_large_json.py
+
+# Structs
+python benchmarks/bench_structs.py
+
+# Garbage Collection
+python benchmarks/bench_gc.py
+
+# Library size comparison
+python benchmarks/bench_library_size.py
+```
+
+## Print versions of benchmarked libraries
+```bash
+python -m benchmarks.bench_validation --versions
+python benchmarks/bench_encodings.py --protocol json --versions 
+python benchmarks/bench_encodings.py --protocol msgpack --versions
+python benchmarks/bench_large_json.py --versions
+python benchmarks/bench_structs.py --versions
+```

benchmarks/bench_encodings.py

@@ -7,7 +7,7 @@
 import importlib.metadata
 from typing import Any, Literal, Callable
 
-from .generate_data import make_filesystem_data
+from generate_data import make_filesystem_data
 
 import msgspec
 

benchmarks/bench_validation/__main__.py

@@ -1,7 +1,7 @@
 import argparse
 import json
 import tempfile
-from ..generate_data import make_filesystem_data
+from benchmarks.generate_data import make_filesystem_data
 import sys
 import subprocess
 

setup.py

@@ -59,13 +59,31 @@
     *yaml_deps,
     *toml_deps,
 ]
-dev_deps = ["pre-commit", "coverage", "mypy", "pyright", *doc_deps, *test_deps]
+bench_deps = [
+    "cattrs",
+    "pydantic",
+    "mashumaro",
+    "orjson",
+    "ujson",
+    "python-rapidjson",
+    "pysimdjson",
+    "ormsgpack",
+]
+dev_deps = [
+    "pre-commit",
+    "coverage",
+    "mypy",
+    "pyright",
+    *doc_deps,
+    *test_deps,
+]
 
 extras_require = {
     "yaml": yaml_deps,
     "toml": toml_deps,
     "doc": doc_deps,
     "test": test_deps,
+    "bench": bench_deps,
     "dev": dev_deps,
 }