Metadata-Version: 2.4
Name: snaplet
Version: 0.1.1
Summary: Faster JSON Mapping with Just-In-Time codegen
Project-URL: Homepage, https://github.com/AmaseCocoa/snaplet
Project-URL: Repository, https://github.com/AmaseCocoa/snaplet
Project-URL: Issues, https://github.com/AmaseCocoa/snaplet/issues
Author-email: AmaseCocoa <cocoa@amase.cc>
License: MIT License
        
        Copyright (c) 2026 AmaseCocoa
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: dataclass,jit,json,mapping,performance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: orjson>=3.11.7
Description-Content-Type: text/markdown

# Snaplet
Faster JSON Mapping, the only dependency is orjson.

## Features
* **Just-In-Time (JIT) Codegen**:
Snaplet generates specialized property accessors at runtime using `exec()`. By eliminating `getattr` calls 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 `Annotated` and `Field(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.


## Installation
```bash
uv add snaplet
```

## Usage
```python
from 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.

```python
class User(SnapletBase, jit=False):
    user_id: int
    internal_id: Annotated[int, Field(alias="ID")]
    tags: Annotated[list[str], Field(alias="Tags-List-V1")]
```

## Performance

Snaplet is designed for high-performance applications that handle large JSON datasets with minimal overhead.

### Benchmark (1,000 items)
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 |

### Why so fast?
- **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.

## LICENSE
MIT License