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

tiptap_python_utils/model/__init__.py

@@ -0,0 +1,345 @@
+"""Typed TipTap AST model."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field, replace
+from typing import Any, ClassVar, Dict, Iterator, Mapping, Tuple, TypeVar
+
+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 (
+    Doc,
+    Text,
+    Paragraph,
+    Heading,
+    TaskItem,
+    ListItem,
+    CodeBlock,
+    TaskList,
+    BulletList,
+    OrderedList,
+    Blockquote,
+    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

tiptap_python_utils/py.typed

@@ -0,0 +1 @@
+

tiptap_python_utils/select/__init__.py

@@ -0,0 +1,5 @@
+"""Selection API exports."""
+
+from .selection import Selection
+
+__all__ = ["Selection"]

tiptap_python_utils/select/selection.py

@@ -0,0 +1,72 @@
+"""Fluent TipTap selection API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterator, Tuple
+
+from ..exceptions import TiptapValidationError
+
+from .. import codec
+from ..edit import append_child, set_attr, set_key, set_text
+from ..model import Doc, Node
+from ..tree import node_at_path, replace_at_path
+from ..walk import Ref
+
+if TYPE_CHECKING:
+    from ..content import Content
+
+
+class Selection:
+    """A selected set of TipTap nodes that can be edited immutably."""
+
+    def __init__(self, content: "Content", refs: Tuple[Ref, ...]) -> None:
+        self._content = content
+        self._refs = refs
+
+    def __iter__(self) -> Iterator[Ref]:
+        return iter(self._refs)
+
+    def __len__(self) -> int:
+        return len(self._refs)
+
+    @property
+    def refs(self) -> Tuple[Ref, ...]:
+        return self._refs
+
+    @property
+    def nodes(self) -> Tuple[Node, ...]:
+        return tuple(ref.node for ref in self._refs)
+
+    def text(self, value: str) -> "Content":
+        return self._apply(lambda node: set_text(node, value))
+
+    def set(self, name: str, value: Any) -> "Content":
+        return self._apply(lambda node: set_key(node, name, value))
+
+    def attr(self, name: str, value: Any) -> "Content":
+        return self._apply(lambda node: set_attr(node, name, value))
+
+    def replace(self, node_or_raw: Any) -> "Content":
+        replacement = codec.read_node_input(node_or_raw, label="Node content")
+        return self._apply(lambda _node: replacement)
+
+    def append(self, node_or_raw: Any) -> "Content":
+        child = codec.read_node_input(node_or_raw, label="Node content")
+        if isinstance(child, Doc):
+            raise TiptapValidationError("Child node content must not be a document root")
+        return self._apply(lambda node: append_child(node, child))
+
+    def dump(self) -> str:
+        return self._content.dump()
+
+    def _apply(self, transform: Any) -> "Content":
+        root = self._content._require_root()
+        updated: Node = root
+
+        for ref in sorted(self._refs, key=lambda item: len(item.path), reverse=True):
+            current = node_at_path(updated, ref.path)
+            updated = replace_at_path(updated, ref.path, transform(current))
+
+        if not isinstance(updated, Doc):
+            raise TiptapValidationError("Document root must remain a TipTap doc")
+        return self._content._with_root(updated)

tiptap_python_utils/shared/__init__.py

@@ -0,0 +1,23 @@
+"""Shared-node service exports."""
+
+from .service import (
+    fingerprint_shared,
+    has_shared,
+    new_shared_id,
+    normalize_shared_id,
+    shared_families,
+    shared_id,
+    stamp_shared,
+    sync_shared,
+)
+
+__all__ = [
+    "fingerprint_shared",
+    "has_shared",
+    "new_shared_id",
+    "normalize_shared_id",
+    "shared_families",
+    "shared_id",
+    "stamp_shared",
+    "sync_shared",
+]

tiptap_python_utils/shared/service.py

@@ -0,0 +1,147 @@
+"""Shared-node behavior for TipTap documents."""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+from ..exceptions import TiptapValidationError
+
+from .. import codec
+from ..content import Content
+from ..contract import key
+from ..tree import node_at_path, replace_at_path
+
+
+def shared_families(content: str | Dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Return canonical node bodies grouped by sharedId."""
+    tiptap = Content.require(content)
+    families: dict[str, dict[str, Any]] = {}
+    fingerprints: dict[str, str] = {}
+
+    for ref in tiptap.refs(parseable=True):
+        node = ref.node.raw()
+        node_shared_id = normalize_shared_id(node.get(key.ATTRS, {}).get(key.SHARED_ID))
+        if not node_shared_id:
+            continue
+
+        fingerprint = fingerprint_shared(node)
+        if (
+            node_shared_id in fingerprints
+            and fingerprints[node_shared_id] != fingerprint
+        ):
+            raise TiptapValidationError(
+                f"Conflicting node bodies detected for sharedId '{node_shared_id}'"
+            )
+        if node_shared_id not in families:
+            families[node_shared_id] = deepcopy(node)
+            fingerprints[node_shared_id] = fingerprint
+
+    return families
+
+
+def stamp_shared(
+    node: str | Dict[str, Any],
+    shared_id: str,
+    local_id: Optional[str] = None,
+) -> dict[str, Any]:
+    """Return a deep-copied node with sharedId and optional local id stamped."""
+    parsed = codec.read_node_input(node, label="Node content").raw()
+    attrs = dict(parsed.get(key.ATTRS, {}))
+
+    if local_id is not None:
+        attrs[key.ID] = local_id
+    attrs[key.SHARED_ID] = shared_id
+    parsed[key.ATTRS] = attrs
+    return parsed
+
+
+def has_shared(content: str | Dict[str, Any], shared_id: str) -> bool:
+    tiptap = Content.require(content)
+    for ref in tiptap.refs(parseable=True):
+        if normalize_shared_id(ref.node.attrs.get(key.SHARED_ID)) == shared_id:
+            return True
+    return False
+
+
+def shared_id(node: str | Dict[str, Any]) -> Optional[str]:
+    parsed = codec.read_node_input(node, label="Node content")
+    return normalize_shared_id(parsed.attrs.get(key.SHARED_ID))
+
+
+def new_shared_id() -> str:
+    return f"shared-{uuid4().hex}"
+
+
+def fingerprint_shared(node: dict[str, Any]) -> str:
+    normalized = deepcopy(node)
+    attrs = dict(normalized.get(key.ATTRS, {}))
+    attrs.pop(key.ID, None)
+    attrs.pop(key.SHARED_ID, None)
+    if attrs:
+        normalized[key.ATTRS] = attrs
+    else:
+        normalized.pop(key.ATTRS, None)
+    return json.dumps(normalized, sort_keys=True)
+
+
+def sync_shared(
+    content: str | Dict[str, Any],
+    families: dict[str, dict[str, Any]],
+) -> tuple[str, bool]:
+    """Rewrite matching shared nodes using canonical bodies."""
+    tiptap = Content.require(content)
+    updated_root = tiptap._require_root()
+    changed = False
+
+    refs = tuple(tiptap.refs(parseable=True))
+    for ref in sorted(refs, key=lambda item: len(item.path), reverse=True):
+        current = node_at_path(updated_root, ref.path)
+        current_raw = current.raw()
+        current_shared_id = normalize_shared_id(
+            current_raw.get(key.ATTRS, {}).get(key.SHARED_ID)
+        )
+        if not current_shared_id or current_shared_id not in families:
+            continue
+
+        replacement_raw = _merge_preserving_identity(
+            current_raw,
+            families[current_shared_id],
+        )
+        if replacement_raw == current_raw:
+            continue
+
+        replacement = codec.read_node_input(replacement_raw, label="Node content")
+        updated_root = replace_at_path(updated_root, ref.path, replacement)
+        changed = True
+
+    return tiptap._with_root(updated_root).dump(), changed
+
+
+def normalize_shared_id(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or None
+    return str(value)
+
+
+def _merge_preserving_identity(
+    target_node: dict[str, Any],
+    canonical_node: dict[str, Any],
+) -> dict[str, Any]:
+    replacement = deepcopy(canonical_node)
+    target_attrs = target_node.get(key.ATTRS, {})
+    replacement_attrs = dict(replacement.get(key.ATTRS, {}))
+
+    if isinstance(target_attrs, dict) and target_attrs.get(key.ID):
+        replacement_attrs[key.ID] = target_attrs[key.ID]
+    target_shared_id = normalize_shared_id(target_attrs.get(key.SHARED_ID))
+    if target_shared_id:
+        replacement_attrs[key.SHARED_ID] = target_shared_id
+
+    replacement[key.ATTRS] = replacement_attrs
+    return replacement

tiptap_python_utils/tasks/__init__.py

@@ -0,0 +1,5 @@
+"""Task behavior exports."""
+
+from .query import has_open_tasks, open_tasks, syncable_tasks
+
+__all__ = ["has_open_tasks", "open_tasks", "syncable_tasks"]

tiptap_python_utils/tasks/query.py

@@ -0,0 +1,18 @@
+"""Task-specific TipTap behavior."""
+
+from __future__ import annotations
+
+from ..content import Content
+from ..model import TaskItem
+
+
+def syncable_tasks(items: list[TaskItem]) -> list[TaskItem]:
+    return [item for item in items if item.task_item_id]
+
+
+def open_tasks(items: list[TaskItem]) -> list[TaskItem]:
+    return [item for item in items if not item.is_completed]
+
+
+def has_open_tasks(content: Content) -> bool:
+    return bool(open_tasks(content.tasks))

tiptap_python_utils/text/__init__.py

@@ -0,0 +1,5 @@
+"""Text extraction exports."""
+
+from .extract import NodeText, text_slices, visible_text, word_count
+
+__all__ = ["NodeText", "text_slices", "visible_text", "word_count"]