all2md.ast.serialization

JSON serialization and deserialization for AST nodes.

This module provides utilities for converting AST structures to and from JSON format, enabling persistence, transmission, and interoperability with other tools.

The JSON format preserves: - All node types and their attributes - Metadata and source location information - Document structure and nesting - Round-trip compatibility (AST → JSON → AST produces identical structure)

Examples

Serialize AST to JSON:

>>> from all2md.ast import Document, Heading, Text
>>> from all2md.ast.serialization import ast_to_json
>>>
>>> doc = Document(children=[
...     Heading(level=1, content=[Text(content="Title")])
... ])
>>> json_str = ast_to_json(doc, indent=2)
>>> print(json_str)

Deserialize JSON back to AST:

>>> from all2md.ast.serialization import json_to_ast
>>> doc = json_to_ast(json_str)
>>> print(doc.children[0].level)
1
all2md.ast.serialization.ast_to_dict(node: Node | SourceLocation) → dict[str, Any]

Convert an AST node to a dictionary representation.

Parameters:

node (Node or SourceLocation) – The AST node to convert

Returns:

Dictionary representation of the node

Return type:

dict

Examples

>>> from all2md.ast import Text
>>> text = Text(content="Hello")
>>> ast_to_dict(text)
{'node_type': 'Text', 'content': 'Hello', 'metadata': {}, 'source_location': None}
all2md.ast.serialization.dict_to_ast(data: dict[str, Any], strict_mode: bool = True) → Node | SourceLocation

Convert a dictionary representation back to an AST node.

Parameters:

  • data (dict) – Dictionary representation of a node

  • strict_mode (bool, default True) – If True, raise ValueError on unknown node types. If False, skip unknown nodes (useful for forward compatibility).

Returns:

Reconstructed AST node

Return type:

Node or SourceLocation

Raises:

ValueError – If the dictionary contains an unknown node type and strict_mode is True

Examples

>>> data = {'node_type': 'Text', 'content': 'Hello', 'metadata': {}, 'source_location': None}
>>> node = dict_to_ast(data)
>>> print(node.content)
Hello
all2md.ast.serialization.ast_to_json(node: Node, indent: int | None = None) → str

Serialize an AST node to JSON string with schema versioning.

The serialized JSON includes a schema_version field to enable migration paths for future AST evolution. Unicode characters are preserved without escape sequences for improved readability.

Parameters:

  • node (Node) – The AST node to serialize

  • indent (int or None, default = None) – Number of spaces for indentation (None for compact format)

Returns:

JSON string representation with schema version

Return type:

str

Notes

The output format includes a schema_version field:

{“schema_version”: 1, “node_type”: “…”, …}

Examples

>>> from all2md.ast import Document, Paragraph, Text
>>> doc = Document(children=[
...     Paragraph(content=[Text(content="Hello")])
... ])
>>> json_str = ast_to_json(doc, indent=2)
>>> print(json_str)
all2md.ast.serialization.json_to_ast(json_str: str, validate_schema: bool = True, strict_mode: bool = True) → Node

Deserialize a JSON string to an AST node.

This function handles schema versioning to support future AST evolution. If no schema_version is present in the JSON (for backward compatibility), it assumes version 1.

Parameters:

  • json_str (str) – JSON string representation

  • validate_schema (bool, default True) – If True, validate schema version and raise errors on unsupported versions. If False, skip schema validation (useful for forward compatibility).

  • strict_mode (bool, default True) – If True, raise ValueError on unknown node types or attributes. If False, log warnings and skip unknown elements (useful for forward compatibility).

Returns:

Reconstructed AST node

Return type:

Node

Raises:

  • ValueError – If JSON is invalid, contains unknown node types, or has an unsupported schema version (when validate_schema=True or strict_mode=True)

  • json.JSONDecodeError – If JSON string is malformed

Notes

Backward compatibility is maintained for JSON without schema_version field.

Examples

>>> json_str = '{"schema_version": 1, "node_type": "Text", "content": "Hello"}'
>>> node = json_to_ast(json_str)
>>> print(node.content)
Hello

Optional validation allows forward compatibility:

>>> # With validation disabled, can load newer schema versions
>>> node = json_to_ast(future_json, validate_schema=False, strict_mode=False)