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

tiptap_python_utils/__init__.py

@@ -0,0 +1,85 @@
+"""Public API for TipTap JSON utilities."""
+
+from .contract import key, kind
+from .content import Content
+from .edit import append_node, replace_node
+from .exceptions import TiptapValidationError
+from .model import (
+    Blockquote,
+    BulletList,
+    CodeBlock,
+    Doc,
+    Heading,
+    ListItem,
+    Node,
+    OrderedList,
+    Paragraph,
+    TableCell,
+    TaskItem,
+    TaskList,
+    Text,
+    Unknown,
+    registry,
+)
+from .contract.policy import content_id, is_parseable, node_id, tiptap_id
+from .select import Selection
+from .shared import (
+    fingerprint_shared,
+    has_shared,
+    new_shared_id,
+    shared_id,
+    shared_families,
+    stamp_shared,
+    sync_shared,
+)
+from .tasks import has_open_tasks, open_tasks, syncable_tasks
+from .text import NodeText, text_slices, visible_text, word_count
+from .walk import Ref, Walker
+
+EMPTY_DOCUMENT_CONTENT = '{"type":"doc","content":[]}'
+
+__all__ = [
+    "Blockquote",
+    "BulletList",
+    "CodeBlock",
+    "Content",
+    "Doc",
+    "EMPTY_DOCUMENT_CONTENT",
+    "Heading",
+    "ListItem",
+    "Node",
+    "NodeText",
+    "OrderedList",
+    "Paragraph",
+    "Ref",
+    "Selection",
+    "TableCell",
+    "TaskItem",
+    "TaskList",
+    "Text",
+    "TiptapValidationError",
+    "Unknown",
+    "Walker",
+    "append_node",
+    "content_id",
+    "fingerprint_shared",
+    "has_open_tasks",
+    "has_shared",
+    "is_parseable",
+    "key",
+    "kind",
+    "new_shared_id",
+    "node_id",
+    "open_tasks",
+    "registry",
+    "replace_node",
+    "shared_families",
+    "shared_id",
+    "stamp_shared",
+    "sync_shared",
+    "syncable_tasks",
+    "text_slices",
+    "tiptap_id",
+    "visible_text",
+    "word_count",
+]

tiptap_python_utils/codec/__init__.py

@@ -0,0 +1,29 @@
+"""Raw JSON codec exports."""
+
+from .json import (
+    dump,
+    dumps,
+    normalize_text,
+    parse_raw,
+    raw_node_id,
+    raw_text,
+    read_children,
+    read_doc,
+    read_node,
+    read_node_input,
+    require_object,
+)
+
+__all__ = [
+    "dump",
+    "dumps",
+    "normalize_text",
+    "parse_raw",
+    "raw_node_id",
+    "raw_text",
+    "read_children",
+    "read_doc",
+    "read_node",
+    "read_node_input",
+    "require_object",
+]

tiptap_python_utils/codec/json.py

@@ -0,0 +1,116 @@
+"""TipTap raw JSON codec."""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from typing import Any, Dict, Mapping, Optional
+
+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."""
+    if isinstance(raw, str):
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            return None
+    else:
+        parsed = raw
+
+    return deepcopy(parsed) if isinstance(parsed, dict) else None
+
+
+def require_object(
+    content: str | Mapping[str, Any],
+    *,
+    label: str = "content",
+) -> Dict[str, Any]:
+    """Strictly parse a JSON object payload."""
+    if isinstance(content, str):
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError as exc:
+            raise TiptapValidationError(f"{label} is not valid JSON") from exc
+    else:
+        parsed = deepcopy(dict(content))
+
+    if not isinstance(parsed, dict):
+        raise TiptapValidationError(f"{label} must be a JSON 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, {}))
+
+
+def raw_text(node: Mapping[str, Any]) -> str:
+    return " ".join(_iter_text(node))
+
+
+def normalize_text(value: str) -> str:
+    return " ".join(value.split())
+
+
+def _iter_text(node: Mapping[str, Any]):
+    if not isinstance(node, dict):
+        return
+
+    if node.get(key.TYPE) == kind.TEXT:
+        text = str(node.get(key.TEXT, "")).strip()
+        if text:
+            yield text
+        return
+
+    content = node.get(key.CONTENT, [])
+    if not isinstance(content, list):
+        return
+
+    for child in content:
+        if isinstance(child, dict):
+            yield from _iter_text(child)

tiptap_python_utils/content.py

@@ -0,0 +1,174 @@
+"""Public TipTap content facade."""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any, Dict, Iterator, Optional
+
+from .exceptions import TiptapValidationError
+from .types import DocumentContent
+
+from . import codec
+from .contract import key, kind, policy
+from .model import (
+    Blockquote,
+    BulletList,
+    CodeBlock,
+    Doc,
+    Heading,
+    ListItem,
+    Node,
+    OrderedList,
+    Paragraph,
+    TableCell,
+    TaskItem,
+    TaskList,
+    Text,
+)
+from .select import Selection
+from .walk import Ref, Walker
+
+
+@dataclass(frozen=True)
+class Content:
+    """Parsed TipTap content aggregate."""
+
+    _tree: Optional[Dict[str, Any]]
+    _root: Optional[Doc]
+
+    @classmethod
+    def parse(cls, raw: Optional[DocumentContent]) -> "Content":
+        raw_object = codec.parse_raw(raw)
+        if raw_object is None:
+            return cls(None, None)
+
+        root = codec.read_doc(raw_object)
+        return cls(raw_object, root)
+
+    @classmethod
+    def require(cls, raw: DocumentContent) -> "Content":
+        raw_object = codec.require_object(raw, label="Document content")
+        if raw_object.get(key.TYPE) != kind.DOC:
+            raise TiptapValidationError("Document content must be a TipTap doc")
+
+        root = codec.read_doc(raw_object)
+        if root is None:
+            raise TiptapValidationError("Document content must be a TipTap doc")
+        return cls(raw_object, root)
+
+    @classmethod
+    def wrap(cls, raw_node: Optional[DocumentContent]) -> "Content":
+        raw_object = codec.parse_raw(raw_node)
+        if raw_object is None:
+            return cls(None, None)
+        if raw_object.get(key.TYPE) == kind.DOC:
+            return cls.parse(raw_object)
+        return cls.parse({key.TYPE: kind.DOC, key.CONTENT: [raw_object]})
+
+    @property
+    def root(self) -> Optional[Doc]:
+        return self._root
+
+    @property
+    def text(self) -> str:
+        if self.root is None:
+            return ""
+        return codec.normalize_text(self.root.text)
+
+    @property
+    def tasks(self) -> list[TaskItem]:
+        return self.walker().of_type(TaskItem)
+
+    @property
+    def headings(self) -> list[Heading]:
+        return self.walker().of_type(Heading)
+
+    @property
+    def paragraphs(self) -> list[Paragraph]:
+        return self.walker().of_type(Paragraph)
+
+    @property
+    def texts(self) -> list[Text]:
+        return self.walker().of_type(Text)
+
+    def walker(self) -> Walker:
+        return Walker(self._root)
+
+    def refs(self, *, parseable: bool = False) -> Iterator[Ref]:
+        return self.walker().refs(parseable=parseable)
+
+    def where_id(self, node_id: str) -> Selection:
+        matches = [ref for ref in self.refs(parseable=True) if ref.node_id == node_id]
+        if not matches:
+            raise TiptapValidationError(
+                f"Node with ID {node_id} not found in document content"
+            )
+        if len(matches) > 1:
+            raise TiptapValidationError(
+                f"Node with ID {node_id} appears multiple times in document content"
+            )
+        return Selection(self, tuple(matches))
+
+    def of(self, node_kind: str) -> Selection:
+        return Selection(
+            self,
+            tuple(ref for ref in self.refs() if ref.node.kind == node_kind),
+        )
+
+    def dump(self) -> str:
+        return json.dumps(self.to_dict())
+
+    def to_dict(self) -> Dict[str, Any]:
+        if self._root is not None:
+            return self._root.raw()
+        if self._tree is not None:
+            return deepcopy(self._tree)
+        raise TiptapValidationError("Document content is not valid")
+
+    def word_count(self) -> int:
+        return sum(len(node.text.split()) for node in _word_count_nodes(self.root))
+
+    def _require_root(self) -> Doc:
+        if self._root is None:
+            raise TiptapValidationError("Document content is not valid")
+        return self._root
+
+    def _with_root(self, root: Doc) -> "Content":
+        return Content(root.raw(), root)
+
+
+def _word_count_nodes(root: Optional[Doc]) -> Iterator[Node]:
+    if root is None:
+        return
+    for child in root.content:
+        yield from _iter_word_count_nodes(child)
+
+
+def _iter_word_count_nodes(node: Node) -> Iterator[Node]:
+    if _is_countable(node):
+        if _identity(node):
+            yield node
+        return
+
+    if _is_container(node):
+        for child in node.content:
+            yield from _iter_word_count_nodes(child)
+
+
+def _is_countable(node: Node) -> bool:
+    return isinstance(node, (Paragraph, Heading, TaskItem, ListItem, CodeBlock))
+
+
+def _is_container(node: Node) -> bool:
+    return isinstance(
+        node,
+        (Doc, TaskList, BulletList, OrderedList, Blockquote, TableCell),
+    )
+
+
+def _identity(node: Node) -> str:
+    if isinstance(node, TaskItem):
+        return node.task_item_id
+    return node.id or policy.node_id(node.attrs) or ""

tiptap_python_utils/contract/__init__.py

@@ -0,0 +1,5 @@
+"""Raw TipTap contract and domain policy."""
+
+from . import key, kind, policy
+
+__all__ = ["key", "kind", "policy"]

tiptap_python_utils/contract/key.py

@@ -0,0 +1,14 @@
+"""Raw TipTap payload keys."""
+
+TYPE = "type"
+ATTRS = "attrs"
+CONTENT = "content"
+TEXT = "text"
+MARKS = "marks"
+ID = "id"
+TIPTAP_ID = "tiptapId"
+SHARED_ID = "sharedId"
+LEVEL = "level"
+CHECKED = "checked"
+STATUS = "status"
+TASK_CANONICAL_ID = "taskCanonicalId"

tiptap_python_utils/contract/kind.py

@@ -0,0 +1,14 @@
+"""TipTap node kinds."""
+
+DOC = "doc"
+TEXT = "text"
+PARAGRAPH = "paragraph"
+HEADING = "heading"
+TASK_ITEM = "taskItem"
+TASK_LIST = "taskList"
+LIST_ITEM = "listItem"
+BULLET_LIST = "bulletList"
+ORDERED_LIST = "orderedList"
+BLOCKQUOTE = "blockquote"
+CODE_BLOCK = "codeBlock"
+TABLE_CELL = "tableCell"

tiptap_python_utils/contract/policy.py

@@ -0,0 +1,52 @@
+"""TipTap identity and parseability policy."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from . import key, kind
+
+_CONTAINER_KINDS = frozenset(
+    {
+        kind.TASK_ITEM,
+        kind.LIST_ITEM,
+        kind.TABLE_CELL,
+        kind.BLOCKQUOTE,
+    }
+)
+
+
+def is_parseable(node_kind: str, parent_kind: str) -> bool:
+    """Return whether a node is tracked as an addressable document node."""
+    if node_kind == kind.PARAGRAPH and parent_kind in _CONTAINER_KINDS:
+        return False
+    return True
+
+
+def node_id(attrs: Any) -> Optional[str]:
+    return _string_attr(attrs, key.ID)
+
+
+def tiptap_id(attrs: Any) -> Optional[str]:
+    return _string_attr(attrs, key.TIPTAP_ID)
+
+
+def content_id(attrs: Any) -> str:
+    return node_id(attrs) or tiptap_id(attrs) or ""
+
+
+def shared_id(attrs: Any) -> Optional[str]:
+    return _string_attr(attrs, key.SHARED_ID)
+
+
+def _string_attr(attrs: Any, name: str) -> Optional[str]:
+    if not isinstance(attrs, dict):
+        return None
+
+    value = attrs.get(name)
+    if value is None:
+        return None
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or None
+    return str(value)

tiptap_python_utils/edit/__init__.py

@@ -0,0 +1,12 @@
+"""Immutable edit command exports."""
+
+from .commands import append_child, append_node, replace_node, set_attr, set_key, set_text
+
+__all__ = [
+    "append_child",
+    "append_node",
+    "replace_node",
+    "set_attr",
+    "set_key",
+    "set_text",
+]

tiptap_python_utils/edit/commands.py

@@ -0,0 +1,163 @@
+"""Pure immutable TipTap edit commands."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from ..exceptions import TiptapValidationError
+
+from .. import codec
+from ..contract import key
+from ..model import Doc, Node, Text
+
+
+def set_text(node: Node, value: Any) -> Node:
+    text_value = value if isinstance(value, str) else str(value)
+    if isinstance(node, Text):
+        return node.with_text(text_value)
+    if isinstance(node, Doc):
+        raise TiptapValidationError("Document node does not support text updates")
+
+    direct_texts = [child for child in node.content if isinstance(child, Text)]
+    if direct_texts:
+        return node.__class__(
+            **{
+                **_clone_payload(node),
+                "content": (direct_texts[0].with_text(text_value),),
+                "present": node.present | {key.CONTENT},
+            }
+        )
+
+    for index, child in enumerate(node.content):
+        try:
+            updated_child = set_text(child, text_value)
+        except TiptapValidationError:
+            continue
+        content = list(node.content)
+        content[index] = updated_child
+        return node.__class__(
+            **{
+                **_clone_payload(node),
+                "content": tuple(content),
+                "present": node.present | {key.CONTENT},
+            }
+        )
+
+    return node.__class__(
+        **{
+            **_clone_payload(node),
+            "content": (Text(value=text_value),),
+            "present": node.present | {key.CONTENT},
+        }
+    )
+
+
+def set_key(node: Node, name: str, value: Any) -> Node:
+    if name == key.TEXT:
+        return set_text(node, value)
+    if name == key.TYPE:
+        raise TiptapValidationError("TipTap node type cannot be updated")
+    if name == key.ATTRS and not isinstance(value, dict):
+        raise TiptapValidationError("TipTap attrs must be a JSON object")
+    if name == key.CONTENT and not isinstance(value, list):
+        raise TiptapValidationError("TipTap content must be a list")
+    if name == key.MARKS and isinstance(node, Text):
+        if not isinstance(value, list):
+            raise TiptapValidationError("TipTap marks must be a list")
+        return Text(
+            value=node.value,
+            marks=tuple(deepcopy(mark) for mark in value),
+            content=node.content,
+            attrs=node.attrs,
+            extra=node.extra,
+            present=node.present | {key.MARKS},
+        )
+
+    raw = node.raw()
+    raw[name] = deepcopy(value)
+    return codec.read_node(raw)
+
+
+def set_attr(node: Node, name: str, value: Any) -> Node:
+    return node.with_attr(name, value)
+
+
+def append_child(node: Node, child: Node) -> Node:
+    if isinstance(node, Text):
+        raise TiptapValidationError("Text nodes cannot contain child nodes")
+    return node.append(child)
+
+
+def append_node(content: str | dict[str, Any], node: str | dict[str, Any] | Node) -> str:
+    """Append a node to the document root content."""
+    from ..content import Content
+
+    document = codec.require_object(content, label="Document content")
+    root_content = document.get(key.CONTENT, [])
+    if not isinstance(root_content, list):
+        raise TiptapValidationError("Document content must contain a content list")
+    return Content.require(document).of("doc").append(node).dump()
+
+
+def replace_node(
+    content: str | dict[str, Any],
+    node_id: str,
+    node: str | dict[str, Any] | Node,
+) -> str:
+    """Replace one parseable node by local attrs.id."""
+    from ..content import Content
+
+    document = codec.require_object(content, label="Document content")
+    replacement_raw = (
+        node.raw() if isinstance(node, Node) else codec.require_object(node, label="Node content")
+    )
+    replacement_id = codec.raw_node_id(replacement_raw)
+    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")
+
+    root_content = document.get(key.CONTENT, [])
+    if not isinstance(root_content, list):
+        raise TiptapValidationError("Document content must contain a content list")
+
+    tiptap = Content.require(document)
+    matches = [
+        ref
+        for ref in tiptap.refs(parseable=True)
+        if ref.node.attrs.get(key.ID) == node_id
+    ]
+    if not matches:
+        raise TiptapValidationError(
+            f"Node with ID {node_id} not found in document content"
+        )
+    if len(matches) > 1:
+        raise TiptapValidationError(
+            f"Node with ID {node_id} appears multiple times in document content"
+        )
+
+    return tiptap.where_id(node_id).replace(replacement_raw).dump()
+
+
+def _clone_payload(node: Node) -> dict[str, Any]:
+    payload = {
+        "id": node.id,
+        "attrs": deepcopy(node.attrs),
+        "extra": deepcopy(node.extra),
+    }
+    if hasattr(node, "level"):
+        payload["level"] = getattr(node, "level")
+    if hasattr(node, "task_item_id"):
+        payload.update(
+            {
+                "task_item_id": getattr(node, "task_item_id"),
+                "is_completed": getattr(node, "is_completed"),
+                "local_task_item_id": getattr(node, "local_task_item_id"),
+                "canonical_task_item_id": getattr(node, "canonical_task_item_id"),
+                "is_linked_copy": getattr(node, "is_linked_copy"),
+            }
+        )
+    if hasattr(node, "raw_kind"):
+        payload["raw_kind"] = getattr(node, "raw_kind")
+    return payload

tiptap_python_utils/exceptions.py

@@ -0,0 +1,5 @@
+"""Package-specific exceptions."""
+
+
+class TiptapValidationError(ValueError):
+    """Raised when TipTap content cannot be parsed or edited safely."""