### orjson Serialization and Deserialization Example

Source: https://github.com/ijl/orjson/blob/master/README.md

A quickstart example demonstrating how to serialize Python objects with specific options and then deserialize the resulting JSON bytes.

```APIDOC
## Quickstart Example

This example shows basic serialization with options and deserialization.

### Code
```python
import orjson, datetime, numpy

data = {
    "type": "job",
    "created_at": datetime.datetime(1970, 1, 1),
    "status": "🆗",
    "payload": numpy.array([[1, 2], [3, 4]]),
}

# Serialize with specific options
serialized_data = orjson.dumps(data, option=orjson.OPT_NAIVE_UTC | orjson.OPT_SERIALIZE_NUMPY)
print(serialized_data)

# Deserialize the JSON bytes
deserialized_data = orjson.loads(serialized_data)
print(deserialized_data)
```

### Expected Output
```
b'{"type":"job","created_at":"1970-01-01T00:00:00+00:00","status":"\xf0\x9f\x86\x97","payload":[[1,2],[3,4]]}'
{'type': 'job', 'created_at': '1970-01-01T00:00:00+00:00', 'status': '🆗', 'payload': [[1, 2], [3, 4]]}
```
```

--------------------------------

### orjson Migration Guide

Source: https://github.com/ijl/orjson/blob/master/README.md

Guidance for migrating from previous versions of orjson or the standard `json` library.

```APIDOC
## Migration Guide

### Version 3 Changes
- **Serialization**: orjson version 3 serializes more types natively than version 2. Subclasses of `str`, `int`, `dict`, and `list` are now serialized by default. `dataclasses.dataclass` and `uuid.UUID` instances are also serialized by default.
- **`OPT_PASSTHROUGH_SUBCLASS`**: Use this option to disable the default serialization of subclasses.
- **`OPT_PASSTHROUGH_DATACLASS`**: Use this option to prevent default serialization of dataclasses, allowing customization via a `default` function.

### Differences from `json` library
- **Return Type**: `orjson.dumps` returns `bytes`, while `json.dumps` returns `str`.

### Option Replacements
- `sort_keys`: Replaced by `option=orjson.OPT_SORT_KEYS`.
- `indent`: Replaced by `option=orjson.OPT_INDENT_2` (only basic indentation is supported).
- `ensure_ascii`: This option is not relevant in orjson as UTF-8 characters are not escaped to ASCII.

### Handling Non-String Keys
- For `dict` objects with non-`str` keys, specify `option=orjson.OPT_NON_STR_KEYS`.
```

--------------------------------

### Install orjson via requirements file

Source: https://github.com/ijl/orjson/blob/master/README.md

Specify the orjson package version range in a requirements.txt or requirements.in file.

```txt
orjson >= 3.10,<4
```

--------------------------------

### Install orjson via pyproject.toml

Source: https://github.com/ijl/orjson/blob/master/README.md

Specify the orjson package version constraint in a pyproject.toml file.

```toml
orjson = "^3.10"
```

--------------------------------

### Build orjson with Maturin

Source: https://github.com/ijl/orjson/blob/master/README.md

Use this command to build orjson from source. Ensure Rust and a C compiler are installed. The --release flag optimizes for performance, and --strip removes debugging symbols.

```sh
maturin build --release --strip
```

--------------------------------

### Serialize Dataclasses with orjson

Source: https://github.com/ijl/orjson/blob/master/README.md

orjson natively serializes dataclasses efficiently. Dataclasses are serialized as maps with attributes in the order defined in the class. This example shows serialization of nested dataclasses.

```python
>>> import dataclasses, orjson, typing

@dataclasses.dataclass
class Member:
    id: int
    active: bool = dataclasses.field(default=False)

@dataclasses.dataclass
class Object:
    id: int
    name: str
    members: typing.List[Member]

>>> orjson.dumps(Object(1, "a", [Member(1, True), Member(2)]))
b'{"id":1,"name":"a","members":[{"id":1,"active":true},{"id":2,"active":false}]}'
```

--------------------------------

### Serialize and Deserialize with Options

Source: https://github.com/ijl/orjson/blob/master/README.md

Demonstrates serializing a dictionary with datetime and numpy array, including specific options for UTC and numpy serialization, followed by deserialization.

```python
>>> import orjson, datetime, numpy
>>> data = {
    "type": "job",
    "created_at": datetime.datetime(1970, 1, 1),
    "status": "✅",
    "payload": numpy.array([[1, 2], [3, 4]]),
}
>>> orjson.dumps(data, option=orjson.OPT_NAIVE_UTC | orjson.OPT_SERIALIZE_NUMPY)
b'{"type":"job","created_at":"1970-01-01T00:00:00+00:00","status":"
f0	9f	a6	97","payload":[[1,2],[3,4]]}'
>>> orjson.loads(_)
{'type': 'job', 'created_at': '1970-01-01T00:00:00+00:00', 'status': '🆗', 'payload': [[1, 2], [3, 4]]}
```

--------------------------------

### Sort Dictionary Keys with OPT_SORT_KEYS

Source: https://github.com/ijl/orjson/blob/master/README.md

Illustrates how to use the OPT_SORT_KEYS option to serialize dictionary keys in a deterministic, sorted order. This is useful for testing and hashing but incurs a performance penalty.

```python
>>> import orjson
>>> orjson.dumps({"b": 1, "c": 2, "a": 3})
b'{"b":1,"c":2,"a":3}'
>>> orjson.dumps({"b": 1, "c": 2, "a": 3}, option=orjson.OPT_SORT_KEYS)
b'{"a":3,"b":1,"c":2}'
```

--------------------------------

### Configure Integer Serialization

Source: https://github.com/ijl/orjson/blob/master/README.md

Demonstrates default 64-bit integer support and the option to restrict integers to the 53-bit range.

```python
>>> import orjson
>>> orjson.dumps(9007199254740992)
b'9007199254740992'
>>> orjson.dumps(9007199254740992, option=orjson.OPT_STRICT_INTEGER)
JSONEncodeError: Integer exceeds 53-bit range
>>> orjson.dumps(-9007199254740992, option=orjson.OPT_STRICT_INTEGER)
JSONEncodeError: Integer exceeds 53-bit range
```

--------------------------------

### Serialize Enums with orjson

Source: https://github.com/ijl/orjson/blob/master/README.md

Demonstrates native serialization of enums and the use of options to modify output format.

```python
>>> import enum, datetime, orjson
>>>
class DatetimeEnum(enum.Enum):
    EPOCH = datetime.datetime(1970, 1, 1, 0, 0, 0)
>>> orjson.dumps(DatetimeEnum.EPOCH)
b'"1970-01-01T00:00:00"'
>>> orjson.dumps(DatetimeEnum.EPOCH, option=orjson.OPT_NAIVE_UTC)
b'"1970-01-01T00:00:00+00:00"'
```

--------------------------------

### Format UTC Datetime with Z Notation using OPT_UTC_Z

Source: https://github.com/ijl/orjson/blob/master/README.md

Demonstrates how to use OPT_UTC_Z to format UTC timezone information as 'Z' instead of '+00:00' for datetime objects.

```python
>>> import orjson, datetime, zoneinfo
>>> orjson.dumps(
        datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
    )
b'"1970-01-01T00:00:00+00:00"'
>>> orjson.dumps(
        datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
        option=orjson.OPT_UTC_Z
    )
b'"1970-01-01T00:00:00Z"'
```

--------------------------------

### Pretty-Print JSON with `OPT_INDENT_2`

Source: https://github.com/ijl/orjson/blob/master/README.md

Employ `orjson.OPT_INDENT_2` for pretty-printing JSON output with an indent of two spaces, similar to `indent=2` in the standard `json` library. This option increases output size and reduces serialization speed.

```python
import orjson
orjson.dumps(
    {"a": "b", "c": {"d": True}, "e": [1, 2]},
    option=orjson.OPT_INDENT_2
)
```

--------------------------------

### OPT_PASSTHROUGH_DATETIME

Source: https://context7.com/ijl/orjson/llms.txt

Enables passing datetime.datetime, datetime.date, and datetime.time instances to the default function for custom formatting.

```APIDOC
## OPT_PASSTHROUGH_DATETIME

Passes `datetime.datetime`, `datetime.date`, and `datetime.time` instances to the `default` function, enabling custom date/time formatting such as HTTP dates, Unix timestamps, or locale-specific formats.

### Request Example (HTTP Date Format)
```python
import orjson
import datetime

def http_date_serializer(obj):
    if isinstance(obj, datetime.datetime):
        return obj.strftime("%a, %d %b %Y %H:%M:%S GMT")
    if isinstance(obj, datetime.date):
        return obj.strftime("%d %b %Y")
    if isinstance(obj, datetime.time):
        return obj.strftime("%I:%M %p")
    raise TypeError

event = {
    "created": datetime.datetime(2024, 1, 15, 14, 30, 0),
    "date": datetime.date(2024, 1, 15),
    "time": datetime.time(14, 30)
}

orjson.dumps(event, option=orjson.OPT_PASSTHROUGH_DATETIME, default=http_date_serializer)
```

### Response Example (HTTP Date Format)
```
b'{"created":"Mon, 15 Jan 2024 14:30:00 GMT","date":"15 Jan 2024","time":"02:30 PM"}'
```

### Request Example (Unix Timestamp)
```python
import orjson
import datetime

def unix_timestamp_serializer(obj):
    if isinstance(obj, datetime.datetime):
        return int(obj.timestamp())
    if isinstance(obj, datetime.date):
        return int(datetime.datetime.combine(obj, datetime.time()).timestamp())
    raise TypeError

orjson.dumps(
    {"timestamp": datetime.datetime(2024, 1, 15, 0, 0, 0)},
    option=orjson.OPT_PASSTHROUGH_DATETIME,
    default=unix_timestamp_serializer
)
```

### Response Example (Unix Timestamp)
```
b'{"timestamp":1705276800}'
```

### Request Example (ISO Format with Milliseconds)
```python
import orjson
import datetime

def iso_millis_serializer(obj):
    if isinstance(obj, datetime.datetime):
        return obj.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
    raise TypeError

orjson.dumps(
    {"event_time": datetime.datetime(2024, 1, 15, 10, 30, 45, 123456)},
    option=orjson.OPT_PASSTHROUGH_DATETIME,
    default=iso_millis_serializer
)
```

### Response Example (ISO Format with Milliseconds)
```
b'{"event_time":"2024-01-15T10:30:45.123Z"}'
```
```

--------------------------------

### Custom Datetime Serialization with OPT_PASSTHROUGH_DATETIME

Source: https://context7.com/ijl/orjson/llms.txt

Use OPT_PASSTHROUGH_DATETIME with a custom default function to serialize datetime, date, and time objects into various formats like HTTP dates, Unix timestamps, or ISO format with milliseconds.

```python
import orjson
import datetime
from zoneinfo import ZoneInfo

def http_date_serializer(obj):
    if isinstance(obj, datetime.datetime):
        # HTTP date format: Thu, 01 Jan 1970 00:00:00 GMT
        return obj.strftime("%a, %d %b %Y %H:%M:%S GMT")
    if isinstance(obj, datetime.date):
        return obj.strftime("%d %b %Y")
    if isinstance(obj, datetime.time):
        return obj.strftime("%I:%M %p")
    raise TypeError

event = {
    "created": datetime.datetime(2024, 1, 15, 14, 30, 0),
    "date": datetime.date(2024, 1, 15),
    "time": datetime.time(14, 30)
}

# Default RFC 3339 format
orjson.dumps(event)
# b'{"created":"2024-01-15T14:30:00","date":"2024-01-15","time":"14:30:00"}'

# Custom HTTP date format
orjson.dumps(event, option=orjson.OPT_PASSTHROUGH_DATETIME, default=http_date_serializer)
# b'{"created":"Mon, 15 Jan 2024 14:30:00 GMT","date":"15 Jan 2024","time":"02:30 PM"}'
```

```python
# Unix timestamp serializer
def unix_timestamp_serializer(obj):
    if isinstance(obj, datetime.datetime):
        return int(obj.timestamp())
    if isinstance(obj, datetime.date):
        return int(datetime.datetime.combine(obj, datetime.time()).timestamp())
    raise TypeError

orjson.dumps(
    {"timestamp": datetime.datetime(2024, 1, 15, 0, 0, 0)},
    option=orjson.OPT_PASSTHROUGH_DATETIME,
    default=unix_timestamp_serializer
)
# b'{"timestamp":1705276800}'
```

```python
# ISO format with milliseconds
def iso_millis_serializer(obj):
    if isinstance(obj, datetime.datetime):
        return obj.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
    raise TypeError

orjson.dumps(
    {"event_time": datetime.datetime(2024, 1, 15, 10, 30, 45, 123456)},
    option=orjson.OPT_PASSTHROUGH_DATETIME,
    default=iso_millis_serializer
)
# b'{"event_time":"2024-01-15T10:30:45.123Z"}'
```

--------------------------------

### Serialize Passthrough Subclasses with Custom Default

Source: https://github.com/ijl/orjson/blob/master/README.md

Demonstrates how to use OPT_PASSTHROUGH_SUBCLASS with a custom default function to serialize subclasses of built-in types. Without a custom default, subclasses are not serializable.

```python
>>> import orjson
>>> 
class Secret(str):
    pass

def default(obj):
    if isinstance(obj, Secret):
        return "******"
    raise TypeError

>>> orjson.dumps(Secret("zxc"))
b'"zxc"'
>>> orjson.dumps(Secret("zxc"), option=orjson.OPT_PASSTHROUGH_SUBCLASS)
TypeError: Type is not JSON serializable: Secret
>>> orjson.dumps(Secret("zxc"), option=orjson.OPT_PASSTHROUGH_SUBCLASS, default=default)
b'"******"'
```

--------------------------------

### Handle Unsupported Types with `default`

Source: https://github.com/ijl/orjson/blob/master/README.md

Specify a `default` callable to serialize unsupported types. If a type is not handled, raise a `TypeError`. Otherwise, `None` is implicitly returned and serialized as `null`.

```python
import orjson, decimal
def default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError

orjson.dumps(decimal.Decimal("0.0842389659712649442845"), default=default)
```

```python
import orjson, decimal
def default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError

orjson.dumps({1, 2}, default=default)
```

```python
import orjson, json
def default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)

orjson.dumps({"set":{1, 2}}, default=default)
```

```python
import orjson, json
def default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)

json.dumps({"set":{1, 2}}, default=default)
```

--------------------------------

### orjson.dumps() - option parameter

Source: https://github.com/ijl/orjson/blob/master/README.md

Configures serialization behavior using integer constants, which can be combined using bitwise OR.

```APIDOC
## orjson.dumps(obj, option=int)

### Description
Modifies the serialization output using predefined integer constants. Multiple options can be combined using the bitwise OR operator (e.g., `orjson.OPT_STRICT_INTEGER | orjson.OPT_NAIVE_UTC`).

### Parameters
#### Request Body
- **option** (int) - Optional - Bitmask of serialization options.

### Available Options
- **OPT_APPEND_NEWLINE**: Appends a newline character to the output.
- **OPT_INDENT_2**: Pretty-prints the output with two-space indentation.
- **OPT_NAIVE_UTC**: Serializes naive datetime objects as UTC.

### Request Example
```python
orjson.dumps([], option=orjson.OPT_APPEND_NEWLINE)
orjson.dumps({"a": "b"}, option=orjson.OPT_INDENT_2)
```
```

--------------------------------

### orjson Deserialization

Source: https://github.com/ijl/orjson/blob/master/README.md

Information regarding the deserialization process using `orjson.loads`.

```APIDOC
## POST /loads

### Description
Deserializes JSON bytes into Python objects.

### Method
`loads`

### Parameters
#### `data`
- **type**: `bytes` - The JSON data to deserialize.

### Returns
- **type**: `dict` or `list` (or other Python object representing the JSON structure) - The deserialized Python object.

### Notes
- There were no changes in deserialization behavior between orjson versions 2 and 3.
- The output format is consistent with standard Python data structures.
```

--------------------------------

### Custom Serialization for Decimal with 'default'

Source: https://context7.com/ijl/orjson/llms.txt

Use the 'default' parameter with a callable to serialize unsupported types like decimal.Decimal. The callable must return a JSON-serializable value or raise TypeError.

```python
import orjson
import decimal

# Custom serialization for Decimal
def decimal_default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError(f"Type {type(obj)} is not serializable")

orjson.dumps({"price": decimal.Decimal("19.99")}, default=decimal_default)
```

--------------------------------

### orjson.dumps() - default parameter

Source: https://github.com/ijl/orjson/blob/master/README.md

Configures how orjson handles types that are not natively serializable by providing a custom callable.

```APIDOC
## orjson.dumps(obj, default=callable)

### Description
Serializes a Python object to JSON. The `default` parameter accepts a callable (function, lambda, or class instance) to handle types not natively supported by orjson. If the callable cannot handle the type, it must raise an exception (e.g., TypeError).

### Parameters
#### Request Body
- **obj** (any) - Required - The object to serialize.
- **default** (callable) - Optional - A function that returns a supported type for non-serializable objects.

### Request Example
```python
def default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError

orjson.dumps(decimal.Decimal("0.0842389659712649442845"), default=default)
```

### Response
#### Success Response (200)
- **bytes** - The serialized JSON string as a bytes object.
```

--------------------------------

### Native NumPy Array Serialization with OPT_SERIALIZE_NUMPY

Source: https://context7.com/ijl/orjson/llms.txt

Enable native serialization of NumPy arrays and scalar types using OPT_SERIALIZE_NUMPY. Ensure arrays are C-contiguous for optimal performance. Supports various numeric and datetime64 types.

```python
import orjson
import numpy as np

# 1D array
arr1d = np.array([1, 2, 3, 4, 5], dtype=np.int32)
orjson.dumps(arr1d, option=orjson.OPT_SERIALIZE_NUMPY)
# b'[1,2,3,4,5]'
```

```python
# 2D array
arr2d = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.float64)
orjson.dumps(arr2d, option=orjson.OPT_SERIALIZE_NUMPY)
# b'[[1.0,2.0,3.0],[4.0,5.0,6.0]]'
```

```python
# 3D array
arr3d = np.zeros((2, 3, 4), dtype=np.int8)
orjson.dumps(arr3d, option=orjson.OPT_SERIALIZE_NUMPY)
# b'[[[0,0,0,0],[0,0,0,0],[0,0,0,0]],[[0,0,0,0],[0,0,0,0],[0,0,0,0]]]' 
```

```python
# Individual numpy scalars
data = {
    "float64": np.float64(3.14159),
    "int32": np.int32(42),
    "bool": np.bool_(True)
}
orjson.dumps(data, option=orjson.OPT_SERIALIZE_NUMPY)
# b'{"float64":3.14159,"int32":42,"bool":true}'
```

```python
# numpy.datetime64 serialization (RFC 3339)
timestamps = np.array(["2024-01-15T10:30:00", "2024-01-16T14:00:00"], dtype="datetime64[s]")
orjson.dumps(timestamps, option=orjson.OPT_SERIALIZE_NUMPY)
# b'["2024-01-15T10:30:00","2024-01-16T14:00:00"]'
```

```python
# Combining with datetime options
orjson.dumps(
    np.datetime64("2024-01-15T10:30:00"),
    option=orjson.OPT_SERIALIZE_NUMPY | orjson.OPT_NAIVE_UTC | orjson.OPT_UTC_Z
)
# b'"2024-01-15T10:30:00Z"'
```

```python
# Fallback for non-contiguous arrays
def numpy_default(obj):
    if isinstance(obj, np.ndarray):
        return obj.tolist()
    raise TypeError

non_contiguous = np.array([[1, 2], [3, 4]])[:, 0]  # Non-contiguous slice
orjson.dumps(non_contiguous, option=orjson.OPT_SERIALIZE_NUMPY, default=numpy_default)
# b'[1,3]'
```

```python
# Large array performance example
large_array = np.random.rand(10000, 100).astype(np.float64)
json_bytes = orjson.dumps(large_array, option=orjson.OPT_SERIALIZE_NUMPY)
# Serializes ~92MB of JSON data efficiently
```

--------------------------------

### Serialize Multiple Custom Types with 'default'

Source: https://context7.com/ijl/orjson/llms.txt

Provide a 'default' callable that handles various unsupported types such as Decimal, set, frozenset, Path, bytes, and complex numbers.

```python
import orjson
import decimal
from datetime import datetime
from pathlib import Path

def custom_default(obj):
    if isinstance(obj, decimal.Decimal):
        return float(obj)
    if isinstance(obj, set):
        return list(obj)
    if isinstance(obj, frozenset):
        return list(obj)
    if isinstance(obj, Path):
        return str(obj)
    if isinstance(obj, bytes):
        return obj.decode("utf-8")
    if isinstance(obj, complex):
        return {"real": obj.real, "imag": obj.imag}
    raise TypeError(f"Type {type(obj)} is not serializable")

data = {
    "price": decimal.Decimal("29.99"),
    "tags": {"python", "json", "fast"},
    "config_path": Path("/etc/app/config.json"),
    "raw_data": b"hello world",
    "complex_num": complex(3, 4)
}
orjson.dumps(data, default=custom_default)
```

--------------------------------

### orjson.Fragment

Source: https://context7.com/ijl/orjson/llms.txt

Includes pre-serialized JSON in the output without re-parsing or re-serializing.

```APIDOC
## orjson.Fragment

Includes pre-serialized JSON in the output without re-parsing or re-serializing. Useful for caching JSON blobs, embedding JSONB fields from databases, or combining separately serialized components. Accepts `bytes` or `str` input.

### Request Example (Basic Usage)
```python
import orjson

cached_json = b'{"cached": true, "data": [1, 2, 3]}'
result = orjson.dumps({
    "fresh": "value",
    "from_cache": orjson.Fragment(cached_json)
})
```

### Response Example (Basic Usage)
```
b'{"fresh":"value","from_cache":{"cached": true, "data": [1, 2, 3]}}'
```

### Request Example (String Fragment)
```python
import orjson

json_str = '{"string": "fragment"}'
orjson.dumps({"embedded": orjson.Fragment(json_str)})
```

### Response Example (String Fragment)
```
b'{"embedded":{"string": "fragment"}}'
```
```

--------------------------------

### Using orjson.Fragment for Pre-serialized JSON

Source: https://context7.com/ijl/orjson/llms.txt

Embed pre-serialized JSON (as bytes or string) directly into the output using orjson.Fragment without re-parsing. This is efficient for caching or combining JSON components.

```python
import orjson

# Basic Fragment usage
cached_json = b'{"cached": true, "data": [1, 2, 3]}'
result = orjson.dumps({
    "fresh": "value",
    "from_cache": orjson.Fragment(cached_json)
})
# b'{"fresh":"value","from_cache":{"cached": true, "data": [1, 2, 3]}}'
```

```python
# String Fragment
json_str = '{"string": "fragment"}'
orjson.dumps({"embedded": orjson.Fragment(json_str)})
# b'{"embedded":{"string": "fragment"}}'
```

--------------------------------

### Serialize Naive Datetimes as UTC with `OPT_NAIVE_UTC`

Source: https://github.com/ijl/orjson/blob/master/README.md

Utilize `orjson.OPT_NAIVE_UTC` to serialize `datetime.datetime` objects without timezone information as UTC. This option does not affect timezone-aware datetime objects.

```python
import orjson, datetime
orjson.dumps(
        datetime.datetime(1970, 1, 1, 0, 0, 0),
        option=orjson.OPT_NAIVE_UTC,
    )
```

--------------------------------

### Passthrough Dataclass Instances with orjson

Source: https://github.com/ijl/orjson/blob/master/README.md

Use OPT_PASSTHROUGH_DATACLASS to allow dataclasses to be handled by a custom default function. This is slower than default serialization but enables custom output formatting.

```python
>>> import orjson, dataclasses
>>>
@dataclasses.dataclass
class User:
    id: str
    name: str
    password: str

def default(obj):
    if isinstance(obj, User):
        return {"id": obj.id, "name": obj.name}
    raise TypeError

>>> orjson.dumps(User("3b1", "asd", "zxc"))
b'{"id":"3b1","name":"asd","password":"zxc"}'
```

```python
>>> orjson.dumps(User("3b1", "asd", "zxc"), option=orjson.OPT_PASSTHROUGH_DATACLASS)
TypeError: Type is not JSON serializable: User
```

```python
>>> orjson.dumps(
        User("3b1", "asd", "zxc"),
        option=orjson.OPT_PASSTHROUGH_DATACLASS,
        default=default,
    )
b'{"id":"3b1","name":"asd"}'
```

--------------------------------

### Non-Collation Aware Sorting with OPT_SORT_KEYS

Source: https://github.com/ijl/orjson/blob/master/README.md

Shows that OPT_SORT_KEYS performs byte-wise sorting, which is not collation or locale-aware, similar to the standard library's behavior.

```python
>>> import orjson
>>> orjson.dumps({"a": 1, "ä": 2, "A": 3}, option=orjson.OPT_SORT_KEYS)
b'{"A":3,"a":1,"\xc3\xa4":2}'
```

--------------------------------

### Serialize Python objects with orjson.dumps()

Source: https://context7.com/ijl/orjson/llms.txt

Serializes various Python types to JSON bytes. Use the 'option' parameter to configure output formatting like indentation, sorting, or specific type handling.

```python
import orjson
import datetime
import dataclasses
import uuid
import numpy

# Basic serialization
data = {"name": "Alice", "age": 30, "active": True}
result = orjson.dumps(data)
# b'{"name":"Alice","age":30,"active":true}'

# Datetime serialization (RFC 3339 format)
event = {
    "created_at": datetime.datetime(2024, 1, 15, 10, 30, 0),
    "date": datetime.date(2024, 1, 15),
    "time": datetime.time(10, 30, 0)
}
orjson.dumps(event)
# b'{"created_at":"2024-01-15T10:30:00","date":"2024-01-15","time":"10:30:00"}'

# With timezone and UTC "Z" suffix
from zoneinfo import ZoneInfo
event_utc = {"timestamp": datetime.datetime(2024, 1, 15, 10, 30, tzinfo=ZoneInfo("UTC"))}
orjson.dumps(event_utc, option=orjson.OPT_UTC_Z)
# b'{"timestamp":"2024-01-15T10:30:00Z"}'

# Dataclass serialization
@dataclasses.dataclass
class User:
    id: int
    name: str
    email: str

user = User(1, "Alice", "alice@example.com")
orjson.dumps(user)
# b'{"id":1,"name":"Alice","email":"alice@example.com"}'

# UUID serialization (RFC 4122 format)
orjson.dumps({"user_id": uuid.UUID("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")})
# b'{"user_id":"f81d4fae-7dec-11d0-a765-00a0c91e6bf6"}'

# NumPy array serialization (requires OPT_SERIALIZE_NUMPY)
arr = numpy.array([[1, 2, 3], [4, 5, 6]], dtype=numpy.int32)
orjson.dumps(arr, option=orjson.OPT_SERIALIZE_NUMPY)
# b'[[1,2,3],[4,5,6]]'

# Pretty printing with 2-space indentation
orjson.dumps({"a": 1, "b": [2, 3]}, option=orjson.OPT_INDENT_2)
# b'{\n  "a": 1,\n  "b": [\n    2,\n    3\n  ]\n}'

# Sorted keys for deterministic output
orjson.dumps({"c": 3, "a": 1, "b": 2}, option=orjson.OPT_SORT_KEYS)
# b'{"a":1,"b":2,"c":3}'

# Append newline (useful for NDJSON patterns)
orjson.dumps({"event": "log"}, option=orjson.OPT_APPEND_NEWLINE)
# b'{"event":"log"}\n'

# Combining multiple options with bitwise OR
orjson.dumps(
    {"timestamp": datetime.datetime(2024, 1, 1), "data": [1, 2]},
    option=orjson.OPT_NAIVE_UTC | orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS
)
# Pretty printed, sorted, with naive datetime as UTC

# Non-string keys (requires OPT_NON_STR_KEYS)
orjson.dumps({1: "one", 2: "two"}, option=orjson.OPT_NON_STR_KEYS)
# b'{"1":"one","2":"two"}'

# Error handling
try:
    orjson.dumps({"invalid": set([1, 2, 3])})
except orjson.JSONEncodeError as e:
    print(f"Serialization error: {e}")
    # Type is not JSON serializable: set
```

--------------------------------

### Serialize Special Float Values

Source: https://github.com/ijl/orjson/blob/master/README.md

Shows how orjson serializes NaN and Infinity values as null, contrasting with standard library behavior.

```python
>>> import orjson, json
>>> orjson.dumps([float("NaN"), float("Infinity"), float("-Infinity")])
b'[null,null,null]'
>>> json.dumps([float("NaN"), float("Infinity"), float("-Infinity")])
'[NaN, Infinity, -Infinity]'
```

--------------------------------

### orjson.dumps Function

Source: https://github.com/ijl/orjson/blob/master/README.md

Documentation for the `dumps` function used for serializing Python objects into JSON bytes.

```APIDOC
## POST /dumps

### Description
Serializes Python objects to JSON bytes.

### Method
`dumps`

### Parameters
#### `__obj`
- **type**: `Any` - The Python object to serialize.

#### `default`
- **type**: `Optional[Callable[[Any], Any]]` - Optional function to handle types not natively supported.

#### `option`
- **type**: `Optional[int]` - Bitmask of options to control serialization behavior (e.g., `orjson.OPT_NAIVE_UTC`, `orjson.OPT_SERIALIZE_NUMPY`).

### Returns
- **type**: `bytes` - A bytes object containing the UTF-8 encoded JSON string.

### Raises
- `JSONEncodeError`: If the object is not JSON serializable, contains invalid UTF-8, exceeds integer limits, has non-string keys (without `OPT_NON_STR_KEYS`), or if `default` recurses too deeply or encounters circular references.

### Supported Types
`str`, `dict`, `list`, `tuple`, `int`, `float`, `bool`, `None`, `dataclasses.dataclass`, `typing.TypedDict`, `datetime.datetime`, `datetime.date`, `datetime.time`, `uuid.UUID`, `numpy.ndarray`, and `orjson.Fragment` instances. Also supports subclasses of `str`, `int`, `dict`, `list`, `dataclasses.dataclass`, and `enum.Enum` by default. Use `orjson.OPT_PASSTHROUGH_SUBCLASS` to disable subclass serialization.

### Options
- `orjson.OPT_NAIVE_UTC`: Serialize datetime objects as naive UTC.
- `orjson.OPT_SERIALIZE_NUMPY`: Serialize numpy arrays.
- `orjson.OPT_NON_STR_KEYS`: Allow dictionary keys that are not strings.
- `orjson.OPT_SORT_KEYS`: Sort dictionary keys alphabetically.
- `orjson.OPT_INDENT_2`: Indent output with 2 spaces (basic indentation support).
- `orjson.OPT_PASSTHROUGH_SUBCLASS`: Prevent serialization of subclasses for supported types.
- `orjson.OPT_PASSTHROUGH_DATACLASS`: Prevent default serialization of dataclasses.
```

--------------------------------

### Custom Dataclass Serialization with OPT_PASSTHROUGH_DATACLASS

Source: https://context7.com/ijl/orjson/llms.txt

Use OPT_PASSTHROUGH_DATACLASS with a custom 'default' serializer to exclude sensitive fields or transform data during dataclass serialization.

```python
import orjson
import dataclasses
from typing import Optional

@dataclasses.dataclass
class User:
    id: int
    username: str
    email: str
    password_hash: str
    is_admin: bool = False
    last_login: Optional[str] = None

def user_serializer(obj):
    if isinstance(obj, User):
        # Exclude sensitive fields
        return {
            "id": obj.id,
            "username": obj.username,
            "email": obj.email,
            "is_admin": obj.is_admin
        }
    raise TypeError

user = User(1, "alice", "alice@example.com", "hash123", True, "2024-01-15")

# With passthrough, use custom serializer to exclude sensitive data
orjson.dumps(user, option=orjson.OPT_PASSTHROUGH_DATACLASS, default=user_serializer)
```

--------------------------------

### orjson.loads()

Source: https://context7.com/ijl/orjson/llms.txt

Deserializes JSON data into Python objects. Accepts various input types and performs strict UTF-8 validation.

```APIDOC
## orjson.loads()

### Description
Deserializes JSON to Python objects. Accepts `bytes`, `bytearray`, `memoryview`, or `str` input. Returns standard Python types: `dict`, `list`, `int`, `float`, `str`, `bool`, and `None`.

### Parameters
#### Request Body
- **data** (bytes|bytearray|memoryview|str) - Required - The JSON data to deserialize.

### Response
#### Success Response (200)
- **object** - The deserialized Python object (dict, list, etc.).
```

--------------------------------

### Serialize Datetime Date Objects with orjson

Source: https://github.com/ijl/orjson/blob/master/README.md

Serializes `datetime.date` objects to a string format.

```python
>>> import orjson, datetime
>>> orjson.dumps(datetime.date(1900, 1, 2))
b'"1900-01-02"'
```

--------------------------------

### Transform Dataclass Field Names with OPT_PASSTHROUGH_DATACLASS

Source: https://context7.com/ijl/orjson/llms.txt

Customize dataclass serialization by transforming field names (e.g., to camelCase) using OPT_PASSTHROUGH_DATACLASS and a custom 'default' serializer.

```python
import orjson
import dataclasses
from typing import Optional

@dataclasses.dataclass
class User:
    id: int
    username: str
    email: str
    password_hash: str
    is_admin: bool = False
    last_login: Optional[str] = None

def camel_case_serializer(obj):
    if isinstance(obj, User):
        return {
            "userId": obj.id,
            "userName": obj.username,
            "userEmail": obj.email,
            "isAdmin": obj.is_admin
        }
    raise TypeError

user = User(1, "alice", "alice@example.com", "hash123", True, "2024-01-15")

orjson.dumps(user, option=orjson.OPT_PASSTHROUGH_DATACLASS, default=camel_case_serializer)
```

--------------------------------

### Serialize uuid.UUID with orjson

Source: https://github.com/ijl/orjson/blob/master/README.md

orjson serializes `uuid.UUID` instances to RFC 4122 format.

```python
>>> import orjson, uuid
>>> orjson.dumps(uuid.uuid5(uuid.NAMESPACE_DNS, "python.org"))
b'"886313e1-3b8a-5372-9b90-0c9aee199e5d"'
```

--------------------------------

### Serialize Non-String Dictionary Keys with orjson

Source: https://github.com/ijl/orjson/blob/master/README.md

Use OPT_NON_STR_KEYS to serialize dictionary keys of types other than strings, such as UUIDs and datetimes. This option can be slower for string keys and carries a risk of creating duplicate keys.

```python
>>> import orjson, datetime, uuid
>>> orjson.dumps(
        {uuid.UUID("7202d115-7ff3-4c81-a7c1-2a1f067b1ece"): [1, 2, 3]},
        option=orjson.OPT_NON_STR_KEYS,
    )
b'{"7202d115-7ff3-4c81-a7c1-2a1f067b1ece":[1,2,3]}'
```

```python
>>> orjson.dumps(
        {datetime.datetime(1970, 1, 1, 0, 0, 0): [1, 2, 3]},
        option=orjson.OPT_NON_STR_KEYS | orjson.OPT_NAIVE_UTC,
    )
b'{"1970-01-01T00:00:00+00:00":[1,2,3]}'
```

```python
>>> import orjson, datetime
>>> orjson.dumps(
    {"other": 1, datetime.date(1970, 1, 5): 2, datetime.date(1970, 1, 3): 3},
    option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SORT_KEYS)
b'{"1970-01-03":3,"1970-01-05":2,"other":1}'
```

--------------------------------

### Recursive Default Handling

Source: https://context7.com/ijl/orjson/llms.txt

The 'default' parameter supports recursive handling of custom types up to 254 levels. Ensure the default callable returns serializable types or raises TypeError.

```python
import orjson

class Wrapper:
    def __init__(self, value):
        self.value = value

def recursive_default(obj):
    if isinstance(obj, Wrapper):
        return obj.value  # May return another Wrapper
    raise TypeError

nested = Wrapper(Wrapper(Wrapper({"data": "value"})))
orjson.dumps(nested, default=recursive_default)
```

--------------------------------

### Serialize Datetime Time Objects with orjson

Source: https://github.com/ijl/orjson/blob/master/README.md

Serializes `datetime.time` objects to a string format. `datetime.time` objects must not have timezone information.

```python
>>> import orjson, datetime
>>> orjson.dumps(datetime.time(12, 0, 15, 290))
b'"12:00:15.000290"'
```

--------------------------------

### Compose JSON with orjson.Fragment

Source: https://context7.com/ijl/orjson/llms.txt

Use orjson.Fragment to embed pre-serialized JSON bytes directly into a larger structure without re-parsing or re-formatting.

```python
user_cache = b'{"id": 1, "name": "Alice"}'
posts_cache = b'[{"id": 101, "title": "Hello"}, {"id": 102, "title": "World"}]'

response = orjson.dumps({
    "user": orjson.Fragment(user_cache),
    "posts": orjson.Fragment(posts_cache),
    "request_time": "2024-01-15T10:30:00"
})
```

```python
def serialize_with_jsonb(record):
    return orjson.dumps({
        "id": record["id"],
        "metadata": orjson.Fragment(record["jsonb_column"])  # Already JSON from DB
    })

record = {"id": 1, "jsonb_column": b'{"key": "value", "nested": {"a": 1}}'}
serialize_with_jsonb(record)
```

```python
fragments = [
    orjson.Fragment(b'{"type": "A"}'),
    orjson.Fragment(b'{"type": "B"}'),
    orjson.Fragment(b'{"type": "C"}')
]
orjson.dumps({"items": fragments})
```

```python
compact = orjson.Fragment(b'{"a":1}')
orjson.dumps({"data": compact}, option=orjson.OPT_INDENT_2)
```

--------------------------------

### Native Type Serialization

Source: https://github.com/ijl/orjson/blob/master/README.md

Overview of how orjson handles complex Python types like dataclasses and datetime objects.

```APIDOC
## Native Type Serialization

### Dataclasses
- Serializes `dataclasses.dataclass` instances natively as maps.
- Supports `__slots__`, frozen dataclasses, and default attributes.

### Datetime
- `datetime.datetime`: Serializes to RFC 3339 format.
- `datetime.time`: Must not have `tzinfo`.
- `datetime.date`: Always serializes to YYYY-MM-DD format.

### Options
- `OPT_PASSTHROUGH_DATETIME`: Disable datetime serialization.
- `OPT_UTC_Z`: Use 'Z' suffix for UTC instead of '+00:00'.
- `OPT_NAIVE_UTC`: Assume naive datetimes are UTC.
```