Faster JSON Mapping, the only dependency is orjson.
- Just-In-Time (JIT) Codegen:
Snaplet generates specialized property accessors at runtime using
exec(). By eliminatinggetattrcalls and internal dictionary lookups during access, it achieves near-native attribute access speeds. - Zero-Copy Lazy Instantiation: Nested models and lists are only instantiated when accessed. This minimizes the performance impact when processing large JSON payloads where only specific fields are required.
- High-Throughput Bulk Loading:
Bypasses the standard
__init__constructor and leverages__slots__with__new__to mass-produce instances. This enables high-speed loading by reducing Python-level overhead during object creation. - Explicit Validation Control: Snaplet does not perform eager validation on load. This design allows developers to implement custom validation logic only where necessary, avoiding global performance bottlenecks.
- Transparent Alias Mapping:
Supports
AnnotatedandField(alias=...)to map complex JSON keys to Pythonic names. JIT compilation ensures that using aliases does not incur additional runtime performance costs. - Minimal Dependency:
The only requirement is
orjson. It operates as a pure Python library utilizing JIT logic, ensuring high portability across different environments without the need for complex build chains.
uv add snapletfrom typing import Annotated
from snaplet import SnapletBase
from snaplet import Field
class User(SnapletBase):
user_id: int
internal_id: Annotated[int, Field(alias="ID")]
tags: Annotated[list[str], Field(alias="Tags-List-V1")]
data = {"userId": 1, "ID": 999, "Tags-List-V1": ["python", "snaplet"]}
user = User(data)
print(user.internal_id)
print(user.user_id)You can disable JIT with jit=False but, this is not recommended as it may significantly degrade performance.
class User(SnapletBase, jit=False):
user_id: int
internal_id: Annotated[int, Field(alias="ID")]
tags: Annotated[list[str], Field(alias="Tags-List-V1")]Snaplet is designed for high-performance applications that handle large JSON datasets with minimal overhead.
Measured on Python 3.12.
| Operation | Time | Notes |
|---|---|---|
| Bulk Load | ~108 μs | Using orjson + __new__ bypass |
| Attribute Access | ~115 ns | Powered by JIT Property Access |
| Lazy Export (dict) | ~165 ns | Zero-cost for unaccessed fields |
- JIT Property Access: Specialized property accessors are compiled at runtime using
exec(), eliminating branch overhead. - Lazy Instantiation: Nested objects are only instantiated when accessed.
- Minimal Overhead: Bypassing
__init__during bulk loading to achieve near-native speeds.
MIT License