# serialization

URL: /patitas/api/serialization/
Section: api
Description: AST serialization — JSON round-trip for Patitas AST nodes.

Converts typed AST nodes to/from JSON-compatible dicts. Useful for:
- Caching parsed ASTs to disk (Bengal incremental builds)
- Sending AST diffs over the wire (Purr SSE)
- Debugging and inspection

All output is deterministic (sorted keys) for cache-key stability.

Example:
    from patitas import parse
    from patitas.serialization import to_json, from_json

    doc = parse("# Hello **World**")
    json_str = to_json(doc)
    restored = from_json(json_str)
    assert doc == restored

Thread Safety:
    All functions are pure — safe to call from any thread.

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/serialization/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fserialization%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fserialization%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fserialization%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fserialization%2Findex.txt)

Module

#
`serialization`

AST serialization — JSON round-trip for Patitas AST nodes.

Converts typed AST nodes to/from JSON-compatible dicts. Useful for:

- Caching parsed ASTs to disk (Bengal incremental builds)

- Sending AST diffs over the wire (Purr SSE)

- Debugging and inspection

All output is deterministic (sorted keys) for cache-key stability.

Example:

```
from patitas import parse
from patitas.serialization import to_json, from_json

doc = parse("# Hello **World**")
json_str = to_json(doc)
restored = from_json(json_str)
assert doc == restored
```

Thread Safety:

```
All functions are pure — safe to call from any thread.
```

6Functions

## Functions

`to_dict`

1

`dict[str, Any]`

▼

Convert an AST node to a JSON-compatible dict.

Includes a ``_type`` discrimina…

`def to_dict(node: Node) -> dict[str, Any]`

Convert an AST node to a JSON-compatible dict.

Includes a`_type`discriminator field for deserialization.
Recursively serializes child nodes and SourceLocation objects.

##### Parameters

Name
Type
Description

`node`
`Node (/patitas/api/nodes/#Node)`

Any Patitas AST node.

##### Returns

`dict[str, Any]`

`_serialize_value`

2

`Any`

▼

Serialize a single field value.

`def _serialize_value(value: Any, field_name: str = '') -> Any`

##### Parameters

Name
Type
Description

`value`
`Any`

`field_name`
`str`

Default:`''`

##### Returns

`Any`

`from_dict`

1

`Node (/patitas/api/nodes/#Node)`

▼

Reconstruct a typed AST node from a dict.

Uses the ``_type`` discriminator to …

`def from_dict(data: dict[str, Any]) -> Node`

Reconstruct a typed AST node from a dict.

Uses the`_type`discriminator to determine the node class.
Recursively deserializes child nodes and SourceLocation objects.

##### Parameters

Name
Type
Description

`data`
`dict[str, Any]`

Dict with`_type`and node fields (as produced by to_dict).

##### Returns

`Node (/patitas/api/nodes/#Node)`

`_deserialize_value`

2

`Any`

▼

Deserialize a single field value.

`def _deserialize_value(value: Any, field_name: str = '') -> Any`

##### Parameters

Name
Type
Description

`value`
`Any`

`field_name`
`str`

Default:`''`

##### Returns

`Any`

`to_json`

2

`str`

▼

Serialize a Document AST to a JSON string.

Output is deterministic (sorted key…

`def to_json(doc: Document, *, indent: int | None = None) -> str`

Serialize a Document AST to a JSON string.

Output is deterministic (sorted keys) for cache-key stability.

##### Parameters

Name
Type
Description

`doc`
`Document (/patitas/api/nodes/#Document)`

Document to serialize.

`indent`
`int | None`

JSON indentation level (None for compact).

Default:`None`

##### Returns

`str`

`from_json`

1

`Document (/patitas/api/nodes/#Document)`

▼

Deserialize a Document AST from a JSON string.

`def from_json(data: str) -> Document`

##### Parameters

Name
Type
Description

`data`
`str`

JSON string (as produced by to_json).

##### Returns

`Document (/patitas/api/nodes/#Document)`