### Install canonicaljson

Source: https://github.com/matrix-org/python-canonicaljson/blob/main/README.rst

Use pip to install the canonicaljson library. This command should be run in your terminal or command prompt.

```bash
pip install canonicaljson
```

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

### Register Preserialisation Callback for Custom Class

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Demonstrates registering a callback for a custom class (`UserId`) to serialize it into a dictionary. The example also shows how a more recently registered callback for the same type will take precedence.

```python
import canonicaljson

class UserId:
    def __init__(self, uid: int):
        self.uid = uid

cannonicaljson.register_preserialisation_callback(UserId, lambda u: {"uid": u.uid})
print(canonicaljson.encode_canonical_json(UserId(42)))
```

```python
import canonicaljson

class UserId:
    def __init__(self, uid: int):
        self.uid = uid

cannonicaljson.register_preserialisation_callback(UserId, lambda u: u.uid)
print(canonicaljson.encode_canonical_json(UserId(42)))
```

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

### Get Canonical JSON Package Version

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Retrieves the installed version of the `canonicaljson` package using the `__version__` attribute.

```python
import canonicaljson

print(canonicaljson.__version__)
```

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

### Clean and Build Project

Source: https://github.com/matrix-org/python-canonicaljson/blob/main/releasing.md

Commands to clean previous build artifacts and build the project for distribution.

```bash
rm -r ./**/*.egg-info
```

```bash
rm -r dist
```

```bash
python -m build
```

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

### Upload to PyPI

Source: https://github.com/matrix-org/python-canonicaljson/blob/main/releasing.md

Command to upload the built distribution packages to the Python Package Index (PyPI).

```bash
twine upload -s dist/*
```

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

### __version__

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

The package exposes its version string as canonicaljson.__version__.

```APIDOC
## __version__

### Description
The package exposes its version string as `canonicaljson.__version__`. Current stable release is `"2.0.0"`.

### Method
`__version__`

### Request Example
```python
import canonicaljson

print(canonicaljson.__version__)
```

### Response Example
```
2.0.0
```
```

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

### Tag and Push Git Repository

Source: https://github.com/matrix-org/python-canonicaljson/blob/main/releasing.md

Commands to create a signed Git tag for the release version and push it to the remote repository.

```bash
git tag -s v<ver>
```

```bash
git push
```

```bash
git push --tags
```

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

### Iterate and Encode Pretty-Printed JSON

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Shows how to use `iterencode_pretty_printed_json` to generate pretty-printed JSON in chunks. This is useful for streaming output, such as HTTP response bodies.

```python
import canonicaljson

data = {"z": 3, "a": 1, "m": 2}

# Collect chunks
chunks = list(canonicaljson.iterencode_pretty_printed_json(data))
output = b''.join(chunks)
print(output.decode("utf-8"))
```

```python
import canonicaljson
import io

stream = io.BytesIO()
for chunk in canonicaljson.iterencode_pretty_printed_json({"status": "ok", "code": 200}):
    stream.write(chunk)
print(stream.getvalue().decode("utf-8"))
```

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

### Register Preserialisation Callback for Decimal

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Registers a callback to serialize `Decimal` objects into strings. This ensures that precise decimal values are preserved during JSON encoding.

```python
import canonicaljson
from decimal import Decimal

# --- Example 2: Decimal serialisation ---
def decimal_to_str(d: Decimal) -> str:
    return str(d)

cannonicaljson.register_preserialisation_callback(Decimal, decimal_to_str)

invoice = {"amount": Decimal("19.99"), "currency": "USD"}
print(canonicaljson.encode_canonical_json(invoice))
```

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

### register_preserialisation_callback(data_type, callback)

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Registers a preserialisation hook for a custom type. When encode_canonical_json (or any encoder) encounters an object of data_type that the standard json.JSONEncoder does not handle, it calls callback(obj) and encodes the returned value instead. Registering a new callback for the same type replaces the previous one. The base object type cannot be registered.

```APIDOC
## register_preserialisation_callback(data_type, callback)

### Description
Registers a preserialisation hook for a custom type. When `encode_canonical_json` (or any encoder) encounters an object of `data_type` that the standard `json.JSONEncoder` does not handle, it calls `callback(obj)` and encodes the returned value instead. Registering a new callback for the same type replaces the previous one. The base `object` type cannot be registered.

### Method
`register_preserialisation_callback`

### Parameters
#### Positional Arguments
- **data_type**: The custom type to register the callback for.
- **callback**: The function to call when an object of `data_type` is encountered.

### Request Example 1: datetime serialisation
```python
import canonicaljson
from datetime import datetime

def datetime_to_iso(dt: datetime) -> str:
    return dt.isoformat()

canonicaljson.register_preserialisation_callback(datetime, datetime_to_iso)

event = {"timestamp": datetime(2024, 3, 15, 12, 0, 0), "event": "login"}
print(canonicaljson.encode_canonical_json(event))
```

### Response Example 1
```
b'{"event":"login","timestamp":"2024-03-15T12:00:00"}'
```

### Request Example 2: Decimal serialisation
```python
import canonicaljson
from decimal import Decimal

def decimal_to_str(d: Decimal) -> str:
    return str(d)

canonicaljson.register_preserialisation_callback(Decimal, decimal_to_str)

invoice = {"amount": Decimal("19.99"), "currency": "USD"}
print(canonicaljson.encode_canonical_json(invoice))
```

### Response Example 2
```
b'{"amount":"19.99","currency":"USD"}'
```

### Request Example 3: Custom class
```python
import canonicaljson

class UserId:
    def __init__(self, uid: int):
        self.uid = uid

canonicaljson.register_preserialisation_callback(UserId, lambda u: {"uid": u.uid})
print(canonicaljson.encode_canonical_json(UserId(42)))
```

### Response Example 3
```
b'{"uid":42}'
```

### Request Example 4: Most recently registered callback wins
```python
import canonicaljson

class UserId:
    def __init__(self, uid: int):
        self.uid = uid

canonicaljson.register_preserialisation_callback(UserId, lambda u: {"uid": u.uid})
canonicaljson.register_preserialisation_callback(UserId, lambda u: u.uid) # Overwrites previous callback
print(canonicaljson.encode_canonical_json(UserId(42)))
```

### Response Example 4
```
b'42'
```

### Request Example 5: Registering for `object` raises ValueError
```python
import canonicaljson

try:
    canonicaljson.register_preserialisation_callback(object, lambda o: None)
except ValueError as e:
    print(f"Error: {e}")
```

### Response Example 5
```
Error: Cannot register callback for the `object` type
```

### Request Example 6: Unregistered types still raise TypeError
```python
import canonicaljson

class Unregistered:
    pass

try:
    canonicaljson.encode_canonical_json(Unregistered())
except TypeError as e:
    print(f"Error: {e}")
```

### Response Example 6
```
Error: Object of type Unregistered is not JSON serializable
```
```

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

### Register Preserialisation Callback for Datetime

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Registers a callback to serialize `datetime` objects into ISO 8601 format strings. This hook is invoked when `encode_canonical_json` encounters a `datetime` object.

```python
import canonicaljson
from typing import Dict
from datetime import datetime

# --- Example 1: datetime serialisation ---
def datetime_to_iso(dt: datetime) -> str:
    return dt.isoformat()

cannonicaljson.register_preserialisation_callback(datetime, datetime_to_iso)

event = {"timestamp": datetime(2024, 3, 15, 12, 0, 0), "event": "login"}
print(canonicaljson.encode_canonical_json(event))
```

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

### Error Handling for Preserialisation Callbacks

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Illustrates that registering a preserialisation callback for the base `object` type raises a `ValueError`. It also shows that unregistered custom types will still raise a `TypeError` during encoding.

```python
import canonicaljson

# --- Example 5: Registering for `object` raises ValueError ---
try:
    canonicaljson.register_preserialisation_callback(object, lambda o: None)
except ValueError as e:
    print(f"Error: {e}")
```

```python
import canonicaljson

# --- Example 6: Unregistered types still raise TypeError ---
class Unregistered:
    pass

try:
    canonicaljson.encode_canonical_json(Unregistered())
except TypeError as e:
    print(f"Error: {e}")
```

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

### Encode JSON with Unicode

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Demonstrates encoding a dictionary containing Unicode characters. The output is raw UTF-8 bytes.

```python
import canonicaljson

print(canonicaljson.encode_pretty_printed_json({"café": "☕"}))
```

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

### Register Callback for Custom Type Encoding

Source: https://github.com/matrix-org/python-canonicaljson/blob/main/README.rst

Register a preserialisation callback to handle custom types that are not natively supported by the standard JSON encoder. The callback function should return a dictionary representing the object.

```python
import canonicaljson
from typing import Dict

class CustomType:
    pass

def callback(c: CustomType) -> Dict[str, str]:
    return {"Hello": "world!"}

canonicaljson.register_preserialisation_callback(CustomType, callback)
assert canonicaljson.encode_canonical_json(CustomType()) == b'{"Hello":"world!"}'
```

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

### encode_pretty_printed_json(data)

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Encodes a Python object as human-readable, indented JSON bytes (4-space indentation). Like the canonical encoder, it sorts keys, uses UTF-8 output (no \uXXXX for non-ASCII), and rejects non-finite floats. Useful for debugging, logging, or producing readable config/fixture files.

```APIDOC
## encode_pretty_printed_json(data)

### Description
Encodes a Python object as human-readable, indented JSON bytes (4-space indentation). Like the canonical encoder, it sorts keys, uses UTF-8 output (no \uXXXX for non-ASCII), and rejects non-finite floats. Useful for debugging, logging, or producing readable config/fixture files while still maintaining key sort order.

### Parameters
* **data** (any JSON-serialisable Python object) - The Python object to encode.

### Returns
* **bytes** - The pretty-printed UTF-8 byte representation of the input data.

### Request Example
```python
import canonicaljson

data = {
    "name": "Alice",
    "roles": ["admin", "editor"],
    "metadata": {"created": "2024-01-15", "active": True},
}

result = canonicaljson.encode_pretty_printed_json(data)
print(result.decode("utf-8"))
# {
#     "metadata": {
#         "active": true,
#         "created": "2024-01-15"
#     },
#     "name": "Alice",
#     "roles": [
#         "admin",
#         "editor"
#     ]
# }

# Empty containers
assert canonicaljson.encode_pretty_printed_json({}) == b'{}'
assert canonicaljson.encode_pretty_printed_json([]) == b'[]'
```

### Error Handling
* **ValueError**: Raised if non-finite float values (inf, -inf, NaN) are encountered.
```

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

### Iteratively Encode Object to Canonical JSON

Source: https://github.com/matrix-org/python-canonicaljson/blob/main/README.rst

Use the iterencode_canonical_json function for an iterator-based approach to encoding objects into canonical JSON. This can be more memory-efficient for large objects.

```python
import canonicaljson
assert b''.join(canonicaljson.iterencode_canonical_json({})) == b'{}'
```

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

### iterencode_pretty_printed_json(data)

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

An iterator variant of encode_pretty_printed_json that yields bytes chunks forming the full pretty-printed encoding when concatenated. Follows the same semantics as iterencode_canonical_json but with 4-space indentation applied.

```APIDOC
## iterencode_pretty_printed_json(data)

### Description
An iterator variant of `encode_pretty_printed_json` that yields `bytes` chunks forming the full pretty-printed encoding when concatenated. Follows the same semantics as `iterencode_canonical_json` but with 4-space indentation applied.

### Method
`iterencode_pretty_printed_json`

### Parameters
#### Positional Arguments
- **data**: The data structure to encode.

### Request Example
```python
import canonicaljson

data = {"z": 3, "a": 1, "m": 2}

# Collect chunks
chunks = list(canonicaljson.iterencode_pretty_printed_json(data))
output = b''.join(chunks)
print(output.decode("utf-8"))
```

### Response Example
```
{
    "a": 1,
    "m": 2,
    "z": 3
}
```

## Streaming Output Example

### Description
Use for streaming output (e.g., HTTP response body).

### Request Example
```python
import canonicaljson
import io

stream = io.BytesIO()
for chunk in canonicaljson.iterencode_pretty_printed_json({"status": "ok", "code": 200}):
    stream.write(chunk)
print(stream.getvalue().decode("utf-8"))
```

### Response Example
```
{
    "code": 200,
    "status": "ok"
}
```
```

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

### encode_canonical_json(data)

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Encodes any JSON-serialisable Python object into its canonical UTF-8 byte representation. Object keys are sorted lexicographically, no whitespace is added, and only essential characters are escaped. Non-ASCII Unicode characters are preserved as raw UTF-8 bytes.

```APIDOC
## encode_canonical_json(data)

### Description
Encodes any JSON-serialisable Python object into its canonical UTF-8 byte representation. Object keys are sorted lexicographically, no whitespace is added, only the minimum required characters are escaped (control characters U+0000–U+001F, \", and \\), and non-ASCII Unicode is passed through as raw UTF-8 bytes rather than \uXXXX escapes.

### Parameters
* **data** (any JSON-serialisable Python object) - The Python object to encode.

### Returns
* **bytes** - The canonical UTF-8 byte representation of the input data.

### Request Example
```python
import canonicaljson

data = {"zebra": 1, "apple": 2, "mango": 3}
result = canonicaljson.encode_canonical_json(data)
# result will be b'{"apple":2,"mango":3,"zebra":1}'

nested = {
    "user": {"name": "Alice", "id": 42},
    "active": True,
    "tags": ["admin", "beta"],
}
print(canonicaljson.encode_canonical_json(nested))
# b'{"active":true,"tags":["admin","beta"],"user":{"id":42,"name":"Alice"}}'

emoji_data = {"emoji": "\ud83d\udca9", "caf\u00e9": "oui"}
print(canonicaljson.encode_canonical_json(emoji_data))
# b'{"caf\xc3\xa9":"oui","emoji":"\xf0\x9f\x92\xa9"}'
```

### Error Handling
* **ValueError**: Raised if non-finite float values (inf, -inf, NaN) are encountered.
```

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

### Encode Python objects to Canonical JSON bytes

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Encodes any JSON-serialisable Python object into its canonical UTF-8 byte representation. Object keys are sorted lexicographically, and non-ASCII Unicode is passed through as raw UTF-8 bytes. Non-finite floats raise ValueError.

```python
import canonicaljson

# Basic types
assert canonicaljson.encode_canonical_json({}) == b'{}'
assert canonicaljson.encode_canonical_json([1, 2, 3]) == b'[1,2,3]'
assert canonicaljson.encode_canonical_json(True) == b'true'
assert canonicaljson.encode_canonical_json(None) == b'null'

# Keys are ALWAYS sorted — output is deterministic regardless of insertion order
data = {"zebra": 1, "apple": 2, "mango": 3}
result = canonicaljson.encode_canonical_json(data)
assert result == b'{"apple":2,"mango":3,"zebra":1}'

# Nested structures
nested = {
    "user": {"name": "Alice", "id": 42},
    "active": True,
    "tags": ["admin", "beta"],
}
print(canonicaljson.encode_canonical_json(nested))
# b'{"active":true,"tags":["admin","beta"],"user":{"id":42,"name":"Alice"}}'

# Unicode: non-ASCII passes through as UTF-8, not \uXXXX escapes
emoji_data = {"emoji": "💩", "café": "oui"}
print(canonicaljson.encode_canonical_json(emoji_data))
# b'{"caf\xc3\xa9":"oui","emoji":"\xf0\x9f\x92\xa9"}'

# Control characters and special chars ARE escaped
print(canonicaljson.encode_canonical_json("line1\nline2\ttabbed"))
# b'"line1\\nline2\\ttabbed"'

# Non-finite floats raise ValueError
from math import inf, nan
try:
    canonicaljson.encode_canonical_json(inf)
except ValueError as e:
    print(f"Rejected: {e}")  # Out of range float values are not JSON compliant
```

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

### Encode Python objects to pretty-printed JSON bytes

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

Encodes a Python object as human-readable, indented JSON bytes with 4-space indentation. Like the canonical encoder, it sorts keys, uses UTF-8 output, and rejects non-finite floats. Useful for debugging or readable config files.

```python
import canonicaljson

data = {
    "name": "Alice",
    "roles": ["admin", "editor"],
    "metadata": {"created": "2024-01-15", "active": True},
}

result = canonicaljson.encode_pretty_printed_json(data)
print(result.decode("utf-8"))
# {
#     "metadata": {
#         "active": true,
#         "created": "2024-01-15"
#     },
#     "name": "Alice",
#     "roles": [
#         "admin",
#         "editor"
#     ]
# }

# Empty containers
assert canonicaljson.encode_pretty_printed_json({}) == b'{}'
assert canonicaljson.encode_pretty_printed_json([]) == b'[]'
```

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

### iterencode_canonical_json(data)

Source: https://context7.com/matrix-org/python-canonicaljson/llms.txt

An iterator variant of encode_canonical_json that yields one or more bytes chunks. Concatenating all yielded chunks produces the full canonical encoding. This is useful for encoding large objects incrementally without building the entire byte string in memory at once.

```APIDOC
## iterencode_canonical_json(data)

### Description
An iterator variant of `encode_canonical_json` that yields one or more `bytes` chunks. Concatenating all yielded chunks produces the full canonical encoding. This is useful for encoding large objects incrementally without building the entire byte string in memory at once, allowing cooperative multitasking or streaming writes.

### Parameters
* **data** (any JSON-serialisable Python object) - The Python object to encode.

### Returns
* **iterator** - An iterator yielding bytes chunks of the canonical JSON encoding.

### Request Example
```python
import canonicaljson
import io

# Simple usage — collect all chunks
chunks = list(canonicaljson.iterencode_canonical_json({"key": "value"}))
assert b''.join(chunks) == b'{"key":"value"}'

# Streaming write to a file-like object
large_payload = {
    "records": [{"id": i, "value": f"item_{i}"} for i in range(1000)]
}

buf = io.BytesIO()
for chunk in canonicaljson.iterencode_canonical_json(large_payload):
    buf.write(chunk)

full_bytes = buf.getvalue()
print(f"Encoded {len(full_bytes)} bytes")

# Verify determinism: same output every time
run1 = b''.join(canonicaljson.iterencode_canonical_json(large_payload))
run2 = b''.join(canonicaljson.iterencode_canonical_json(large_payload))
assert run1 == run2  # Always true — canonical encoding is deterministic
```
```

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

### Encode Object to Canonical JSON

Source: https://github.com/matrix-org/python-canonicaljson/blob/main/README.rst

Use the encode_canonical_json function to convert a Python object into its canonical JSON byte representation. This is useful for ensuring consistent JSON output.

```python
import canonicaljson
assert canonicaljson.encode_canonical_json({}) == b'{}'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.