tiptap-python-utils 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

tiptap_python_utils/__init__.py

@@ -2,7 +2,6 @@
 
 from .contract import key, kind
 from .content import Content
-from .edit import append_node, replace_node
 from .exceptions import TiptapValidationError
 from .model import (
     Blockquote,
@@ -60,7 +59,6 @@ __all__ = [
     "TiptapValidationError",
     "Unknown",
     "Walker",
-    "append_node",
     "content_id",
     "fingerprint_shared",
     "has_open_tasks",
@@ -72,7 +70,6 @@ __all__ = [
     "node_id",
     "open_tasks",
     "registry",
-    "replace_node",
     "shared_families",
     "shared_id",
     "stamp_shared",

tiptap_python_utils/codec/__init__.py

@@ -1,18 +1,19 @@
 """Raw JSON codec exports."""
 
-from .json import (
-    dump,
-    dumps,
+from .raw import (
     normalize_text,
     parse_raw,
     raw_node_id,
     raw_text,
+    require_object,
+)
+from .reader import (
     read_children,
     read_doc,
     read_node,
     read_node_input,
-    require_object,
 )
+from .writer import dump, dumps
 
 __all__ = [
     "dump",

tiptap_python_utils/codec/{json.py → raw.py}

@@ -1,17 +1,19 @@
-"""TipTap raw JSON codec."""
+"""Raw TipTap JSON I/O and dict-shaped helpers.
+
+This module is intentionally free of any ``..model`` import so that raw
+validation can be exercised without hydrating the typed AST.
+"""
 
 from __future__ import annotations
 
 import json
 from copy import deepcopy
-from typing import Any, Dict, Mapping, Optional
+from typing import Any, Dict, Iterator, Mapping, Optional
 
+from ..contract import key, kind, policy
 from ..exceptions import TiptapValidationError
 from ..types import DocumentContent
 
-from ..contract import key, kind, policy
-from ..model import ContentTuple, Doc, Node, registry
-
 
 def parse_raw(raw: Optional[DocumentContent]) -> Optional[Dict[str, Any]]:
     """Leniently parse a raw document payload."""
@@ -45,46 +47,6 @@ def require_object(
     return parsed
 
 
-def read_doc(raw: Mapping[str, Any]) -> Doc | None:
-    """Read a raw TipTap document root."""
-    if raw.get(key.TYPE) != kind.DOC:
-        return None
-    parsed = read_node(raw)
-    return parsed if isinstance(parsed, Doc) else None
-
-
-def read_node(raw: Mapping[str, Any]) -> Node:
-    """Read a raw TipTap node by delegating to the registry."""
-    children = read_children(raw.get(key.CONTENT, []))
-    return registry.read(raw, children)
-
-
-def read_children(raw_children: Any) -> ContentTuple:
-    if not isinstance(raw_children, list):
-        return ()
-    return tuple(read_node(child) for child in raw_children if isinstance(child, dict))
-
-
-def read_node_input(node_or_raw: Any, *, label: str) -> Node:
-    """Read either a typed node or a raw node payload."""
-    if isinstance(node_or_raw, Node):
-        return node_or_raw
-
-    parsed = require_object(node_or_raw, label=label)
-    node = read_doc(parsed) if parsed.get(key.TYPE) == kind.DOC else read_node(parsed)
-    if node is None:
-        raise TiptapValidationError(f"{label} must be a valid TipTap node")
-    return node
-
-
-def dump(node: Node) -> Dict[str, Any]:
-    return node.raw()
-
-
-def dumps(node: Node) -> str:
-    return json.dumps(dump(node))
-
-
 def raw_node_id(node: Mapping[str, Any]) -> str:
     return policy.content_id(node.get(key.ATTRS, {}))
 
@@ -97,7 +59,7 @@ def normalize_text(value: str) -> str:
     return " ".join(value.split())
 
 
-def _iter_text(node: Mapping[str, Any]):
+def _iter_text(node: Mapping[str, Any]) -> Iterator[str]:
     if not isinstance(node, dict):
         return
 

tiptap_python_utils/codec/reader.py

@@ -0,0 +1,42 @@
+"""Raw TipTap JSON → typed AST hydration."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from ..contract import key, kind
+from ..exceptions import TiptapValidationError
+from ..model import ContentTuple, Doc, Node, registry
+from .raw import require_object
+
+
+def read_doc(raw: Mapping[str, Any]) -> Doc | None:
+    """Read a raw TipTap document root."""
+    if raw.get(key.TYPE) != kind.DOC:
+        return None
+    parsed = read_node(raw)
+    return parsed if isinstance(parsed, Doc) else None
+
+
+def read_node(raw: Mapping[str, Any]) -> Node:
+    """Read a raw TipTap node by delegating to the registry."""
+    children = read_children(raw.get(key.CONTENT, []))
+    return registry.read(raw, children)
+
+
+def read_children(raw_children: Any) -> ContentTuple:
+    if not isinstance(raw_children, list):
+        return ()
+    return tuple(read_node(child) for child in raw_children if isinstance(child, dict))
+
+
+def read_node_input(node_or_raw: Any, *, label: str) -> Node:
+    """Read either a typed node or a raw node payload."""
+    if isinstance(node_or_raw, Node):
+        return node_or_raw
+
+    parsed = require_object(node_or_raw, label=label)
+    node = read_doc(parsed) if parsed.get(key.TYPE) == kind.DOC else read_node(parsed)
+    if node is None:
+        raise TiptapValidationError(f"{label} must be a valid TipTap node")
+    return node

tiptap_python_utils/codec/writer.py

@@ -0,0 +1,16 @@
+"""Typed AST → raw TipTap JSON serialization."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+from ..model import Node
+
+
+def dump(node: Node) -> Dict[str, Any]:
+    return node.raw()
+
+
+def dumps(node: Node) -> str:
+    return json.dumps(dump(node))

tiptap_python_utils/content.py

@@ -117,6 +117,18 @@ class Content:
             tuple(ref for ref in self.refs() if ref.node.kind == node_kind),
         )
 
+    def append_root(self, node_or_raw: Any) -> "Content":
+        return self.of(kind.DOC).append(node_or_raw)
+
+    def replace_by_id(self, node_id: str, node_or_raw: Any) -> "Content":
+        replacement = codec.read_node_input(node_or_raw, label="Node content")
+        replacement_id = replacement.attrs.get(key.ID, "")
+        if not replacement_id:
+            raise TiptapValidationError("Node content must include attrs.id")
+        if replacement_id != node_id:
+            raise TiptapValidationError("Node content attrs.id must match path node_id")
+        return self.where_id(node_id).replace(replacement)
+
     def dump(self) -> str:
         return json.dumps(self.to_dict())
 

tiptap_python_utils/model/__init__.py

@@ -1,345 +1,49 @@
-"""Typed TipTap AST model."""
+"""Typed TipTap AST model.
 
-from __future__ import annotations
+This package initializer is intentionally re-export-only. Implementation
+lives in:
 
-from copy import deepcopy
-from dataclasses import dataclass, field, replace
-from typing import Any, ClassVar, Dict, Iterator, Mapping, Tuple, TypeVar
+- ``base``      — ``Node``, ``Text``, ``ContentTuple``, ``MarksTuple``, ``NodeT``
+- ``nodes``     — concrete node classes (``Doc``, ``Paragraph``, ``Heading``, …)
+- ``registry``  — ``Registry`` plus the bootstrapped ``registry`` instance
+- ``payload``   — raw-payload extraction helpers used by node readers
+"""
 
-from ..contract import key, kind, policy
-
-ContentTuple = Tuple["Node", ...]
-MarksTuple = Tuple[Any, ...]
-NodeT = TypeVar("NodeT", bound="Node")
-
-
-@dataclass(frozen=True)
-class Node:
-    """Base typed TipTap node."""
-
-    id: str = ""
-    content: ContentTuple = field(default_factory=tuple)
-    attrs: Dict[str, Any] = field(default_factory=dict, compare=False, repr=False)
-    extra: Dict[str, Any] = field(default_factory=dict, compare=False, repr=False)
-    present: frozenset[str] = field(default_factory=frozenset, compare=False, repr=False)
-
-    kind: ClassVar[str]
-
-    def __post_init__(self) -> None:
-        if not self.id:
-            object.__setattr__(self, "id", policy.content_id(self.attrs))
-
-    @classmethod
-    def read(cls: type[NodeT], raw: Mapping[str, Any], children: ContentTuple) -> NodeT:
-        return cls(**_payload(raw, children))
-
-    @property
-    def shared_id(self) -> str | None:
-        return policy.shared_id(self.attrs)
-
-    @property
-    def text(self) -> str:
-        return " ".join(part for part in self.iter_text() if part)
-
-    def iter_text(self) -> Iterator[str]:
-        for child in self.content:
-            yield from child.iter_text()
-
-    def raw(self) -> Dict[str, Any]:
-        raw: Dict[str, Any] = {key.TYPE: self.kind}
-        raw.update(deepcopy(self.extra))
-
-        attrs = self.raw_attrs()
-        if attrs or key.ATTRS in self.present:
-            raw[key.ATTRS] = attrs
-
-        if self.content or key.CONTENT in self.present:
-            raw[key.CONTENT] = [child.raw() for child in self.content]
-        return raw
-
-    def raw_attrs(self) -> Dict[str, Any]:
-        attrs = deepcopy(self.attrs)
-        if self.id and not _has_any_identity(attrs):
-            attrs[key.ID] = self.id
-        return attrs
-
-    def with_text(self, value: str) -> "Node":
-        if not self.content:
-            return self
-        return replace(self, content=(Text(value=value),))
-
-    def with_attr(self, name: str, value: Any) -> "Node":
-        attrs = deepcopy(self.attrs)
-        attrs[name] = deepcopy(value)
-        return replace(self, attrs=attrs, present=self.present | {key.ATTRS})
-
-    def append(self, child: "Node") -> "Node":
-        return replace(self, content=self.content + (child,), present=self.present | {key.CONTENT})
-
-
-@dataclass(frozen=True)
-class Text(Node):
-    value: str = ""
-    marks: MarksTuple = ()
-
-    kind: ClassVar[str] = kind.TEXT
-
-    @classmethod
-    def read(cls, raw: Mapping[str, Any], children: ContentTuple) -> "Text":
-        value = raw.get(key.TEXT, "")
-        marks = raw.get(key.MARKS, [])
-        return cls(
-            value=value if isinstance(value, str) else str(value),
-            marks=tuple(deepcopy(marks)) if isinstance(marks, list) else (),
-            **_payload(raw, children, extra_keys={key.TEXT, key.MARKS}),
-        )
-
-    @property
-    def text(self) -> str:
-        return self.value.strip()
-
-    def iter_text(self) -> Iterator[str]:
-        if self.text:
-            yield self.text
-
-    def raw(self) -> Dict[str, Any]:
-        raw = super().raw()
-        if self.value or key.TEXT in self.present:
-            raw[key.TEXT] = self.value
-        if self.marks or key.MARKS in self.present:
-            raw[key.MARKS] = [deepcopy(mark) for mark in self.marks]
-        return raw
-
-    def with_text(self, value: str) -> "Text":
-        return replace(self, value=value, present=self.present | {key.TEXT})
-
-
-@dataclass(frozen=True)
-class Doc(Node):
-    kind: ClassVar[str] = kind.DOC
-
-
-@dataclass(frozen=True)
-class Paragraph(Node):
-    kind: ClassVar[str] = kind.PARAGRAPH
-
-
-@dataclass(frozen=True)
-class Heading(Node):
-    level: int = 1
-
-    kind: ClassVar[str] = kind.HEADING
-
-    @classmethod
-    def read(cls, raw: Mapping[str, Any], children: ContentTuple) -> "Heading":
-        return cls(level=_heading_level(raw), **_payload(raw, children))
-
-    def raw_attrs(self) -> Dict[str, Any]:
-        attrs = super().raw_attrs()
-        if key.LEVEL in attrs or key.ATTRS not in self.present:
-            attrs.setdefault(key.LEVEL, self.level)
-        return attrs
-
-
-@dataclass(frozen=True)
-class TaskItem(Node):
-    task_item_id: str = ""
-    is_completed: bool = False
-    local_task_item_id: str = ""
-    canonical_task_item_id: str = ""
-    is_linked_copy: bool = False
-
-    kind: ClassVar[str] = kind.TASK_ITEM
-
-    @classmethod
-    def read(cls, raw: Mapping[str, Any], children: ContentTuple) -> "TaskItem":
-        completed = _task_completion(raw)
-        local_id = policy.content_id(raw.get(key.ATTRS, {}))
-        canonical_id = _task_canonical_id(raw, local_id)
-        return cls(
-            task_item_id=canonical_id,
-            is_completed=bool(completed),
-            local_task_item_id=local_id,
-            canonical_task_item_id=canonical_id,
-            is_linked_copy=bool(local_id and canonical_id and local_id != canonical_id),
-            **_payload(raw, children),
-        )
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        if not self.local_task_item_id and self.task_item_id:
-            object.__setattr__(self, "local_task_item_id", self.task_item_id)
-        if not self.canonical_task_item_id and self.task_item_id:
-            object.__setattr__(self, "canonical_task_item_id", self.task_item_id)
-        if (
-            not self.is_linked_copy
-            and self.local_task_item_id
-            and self.canonical_task_item_id
-            and self.local_task_item_id != self.canonical_task_item_id
-        ):
-            object.__setattr__(self, "is_linked_copy", True)
-
-    @property
-    def shared_id(self) -> str | None:
-        return policy.shared_id(self.attrs)
-
-    def raw_attrs(self) -> Dict[str, Any]:
-        attrs = super().raw_attrs()
-        if self.local_task_item_id and not _has_any_identity(attrs):
-            attrs[key.ID] = self.local_task_item_id
-        if self.canonical_task_item_id and (
-            key.TASK_CANONICAL_ID in attrs
-            or self.canonical_task_item_id != self.local_task_item_id
-        ):
-            attrs.setdefault(key.TASK_CANONICAL_ID, self.canonical_task_item_id)
-        if key.CHECKED in attrs or (
-            key.ATTRS not in self.present and key.STATUS not in self.extra
-        ):
-            attrs.setdefault(key.CHECKED, self.is_completed)
-        return attrs
-
-
-@dataclass(frozen=True)
-class ListItem(Node):
-    kind: ClassVar[str] = kind.LIST_ITEM
-
-
-@dataclass(frozen=True)
-class CodeBlock(Node):
-    kind: ClassVar[str] = kind.CODE_BLOCK
-
-
-@dataclass(frozen=True)
-class TaskList(Node):
-    kind: ClassVar[str] = kind.TASK_LIST
-
-
-@dataclass(frozen=True)
-class BulletList(Node):
-    kind: ClassVar[str] = kind.BULLET_LIST
-
-
-@dataclass(frozen=True)
-class OrderedList(Node):
-    kind: ClassVar[str] = kind.ORDERED_LIST
-
-
-@dataclass(frozen=True)
-class Blockquote(Node):
-    kind: ClassVar[str] = kind.BLOCKQUOTE
-
-
-@dataclass(frozen=True)
-class TableCell(Node):
-    kind: ClassVar[str] = kind.TABLE_CELL
-
-
-@dataclass(frozen=True)
-class Unknown(Node):
-    raw_kind: str = ""
-
-    @classmethod
-    def read(cls, raw: Mapping[str, Any], children: ContentTuple) -> "Unknown":
-        return cls(raw_kind=str(raw.get(key.TYPE, "")), **_payload(raw, children))
-
-    @property
-    def kind(self) -> str:
-        return self.raw_kind
-
-
-class Registry:
-    """Map raw TipTap kinds to typed node classes."""
-
-    def __init__(self) -> None:
-        self._classes: dict[str, type[Node]] = {}
-
-    def register(self, node_class: type[Node]) -> type[Node]:
-        self._classes[node_class.kind] = node_class
-        return node_class
-
-    def read(self, raw: Mapping[str, Any], children: ContentTuple) -> Node:
-        node_kind = str(raw.get(key.TYPE, ""))
-        node_class = self._classes.get(node_kind, Unknown)
-        return node_class.read(raw, children)
-
-
-registry = Registry()
-for _node_class in (
+from .base import ContentTuple, MarksTuple, Node, NodeT, Text
+from .nodes import (
+    Blockquote,
+    BulletList,
+    CodeBlock,
     Doc,
-    Text,
-    Paragraph,
     Heading,
-    TaskItem,
     ListItem,
-    CodeBlock,
-    TaskList,
-    BulletList,
     OrderedList,
-    Blockquote,
+    Paragraph,
     TableCell,
-):
-    registry.register(_node_class)
-
-
-def _payload(
-    raw: Mapping[str, Any],
-    children: ContentTuple,
-    *,
-    extra_keys: set[str] | None = None,
-) -> dict[str, Any]:
-    present = frozenset(str(name) for name in raw.keys())
-    known = {key.TYPE, key.ATTRS, key.CONTENT} | (extra_keys or set())
-    attrs = raw.get(key.ATTRS, {})
-    return {
-        "id": policy.content_id(attrs),
-        "content": children,
-        "attrs": deepcopy(attrs) if isinstance(attrs, dict) else {},
-        "extra": {name: deepcopy(value) for name, value in raw.items() if name not in known},
-        "present": present,
-    }
-
-
-def _heading_level(raw: Mapping[str, Any]) -> int:
-    attrs = raw.get(key.ATTRS, {})
-    level = attrs.get(key.LEVEL, 1) if isinstance(attrs, dict) else 1
-    return level if isinstance(level, int) and 1 <= level <= 6 else 1
-
-
-def _task_canonical_id(raw: Mapping[str, Any], fallback: str) -> str:
-    attrs = raw.get(key.ATTRS, {})
-    if not isinstance(attrs, dict):
-        return fallback
-
-    canonical_id = attrs.get(key.TASK_CANONICAL_ID)
-    if isinstance(canonical_id, str):
-        stripped = canonical_id.strip()
-        if stripped:
-            return stripped
-    if canonical_id is not None:
-        return str(canonical_id)
-    return fallback
-
-
-def _task_completion(raw: Mapping[str, Any]) -> bool | None:
-    status = raw.get(key.STATUS)
-    if isinstance(status, str) and status.lower() in {"done", "pending"}:
-        return status.lower() == "done"
-
-    attrs = raw.get(key.ATTRS, {})
-    if not isinstance(attrs, dict):
-        attrs = {}
-
-    status = attrs.get(key.STATUS)
-    if isinstance(status, str) and status.lower() in {"done", "pending"}:
-        return status.lower() == "done"
-
-    checked = attrs.get(key.CHECKED)
-    if isinstance(checked, bool):
-        return checked
-    if isinstance(checked, str) and checked.strip().lower() in {"true", "false"}:
-        return checked.strip().lower() == "true"
-    return None
-
-
-def _has_any_identity(attrs: Dict[str, Any]) -> bool:
-    return key.ID in attrs or key.TIPTAP_ID in attrs
+    TaskItem,
+    TaskList,
+    Unknown,
+)
+from .registry import Registry, registry
+
+__all__ = [
+    "Blockquote",
+    "BulletList",
+    "CodeBlock",
+    "ContentTuple",
+    "Doc",
+    "Heading",
+    "ListItem",
+    "MarksTuple",
+    "Node",
+    "NodeT",
+    "OrderedList",
+    "Paragraph",
+    "Registry",
+    "TableCell",
+    "TaskItem",
+    "TaskList",
+    "Text",
+    "Unknown",
+    "registry",
+]