tiptap-python-utils 0.3.0__tar.gz → 0.5.0__tar.gz

{tiptap_python_utils-0.3.0/src/tiptap_python_utils.egg-info → tiptap_python_utils-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiptap_python_utils
-Version: 0.3.0
+Version: 0.5.0
 Summary: Python utilities for parsing, traversing, editing, and serializing TipTap JSON content.
 Author: tiptap_python_utils contributors
 License: MIT License
@@ -149,6 +149,22 @@ content.where_id("p1")
 
 # By TipTap kind.
 content.of(kind.PARAGRAPH)
+
+# By an arbitrary predicate over every node (and its descendants).
+content.where(lambda node: getattr(node, "level", None) == 1)
+```
+
+### Generic queries
+
+`Selection` carries two predicate primitives that work for any kind, so you
+don't need a bespoke `has_heading_text`-style helper per node type:
+
+```python
+# Narrow a selection further.
+content.of(kind.HEADING).filter(lambda n: n.level == 2)
+
+# Existence check (short-circuits).
+content.of(kind.HEADING).any(lambda n: n.text.strip() == "Introduction")
 ```
 
 ### Atomic mutations
@@ -175,6 +191,11 @@ content.where_id("ul1").append({"type": "listItem", "attrs": {"id": "li-new"}, "
 # Append a node to the document root.
 content.append_root({"type": "paragraph", "attrs": {"id": "p2"}, "content": []})
 
+# Build-and-append in one call — works for any kind, stamps a fresh id when
+# none is given. Typed fields (e.g. Heading.level) hydrate correctly.
+content.append(kind.HEADING, "New section", attrs={"level": 2})
+content.append(kind.PARAGRAPH, "Body text", node_id="p3")
+
 # Replace a node by id (the replacement's attrs.id must match).
 content.replace_by_id("p1", {
     "type": "paragraph",
@@ -281,6 +302,7 @@ from tiptap_python_utils import (
     Text,
     has_open_tasks,
     kind,
+    new_node_id,
     new_shared_id,
     open_tasks,
     text_slices,

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/README.md

@@ -98,6 +98,22 @@ content.where_id("p1")
 
 # By TipTap kind.
 content.of(kind.PARAGRAPH)
+
+# By an arbitrary predicate over every node (and its descendants).
+content.where(lambda node: getattr(node, "level", None) == 1)
+```
+
+### Generic queries
+
+`Selection` carries two predicate primitives that work for any kind, so you
+don't need a bespoke `has_heading_text`-style helper per node type:
+
+```python
+# Narrow a selection further.
+content.of(kind.HEADING).filter(lambda n: n.level == 2)
+
+# Existence check (short-circuits).
+content.of(kind.HEADING).any(lambda n: n.text.strip() == "Introduction")
 ```
 
 ### Atomic mutations
@@ -124,6 +140,11 @@ content.where_id("ul1").append({"type": "listItem", "attrs": {"id": "li-new"}, "
 # Append a node to the document root.
 content.append_root({"type": "paragraph", "attrs": {"id": "p2"}, "content": []})
 
+# Build-and-append in one call — works for any kind, stamps a fresh id when
+# none is given. Typed fields (e.g. Heading.level) hydrate correctly.
+content.append(kind.HEADING, "New section", attrs={"level": 2})
+content.append(kind.PARAGRAPH, "Body text", node_id="p3")
+
 # Replace a node by id (the replacement's attrs.id must match).
 content.replace_by_id("p1", {
     "type": "paragraph",
@@ -230,6 +251,7 @@ from tiptap_python_utils import (
     Text,
     has_open_tasks,
     kind,
+    new_node_id,
     new_shared_id,
     open_tasks,
     text_slices,

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tiptap_python_utils"
-version = "0.3.0"
+version = "0.5.0"
 description = "Python utilities for parsing, traversing, editing, and serializing TipTap JSON content."
 readme = "README.md"
 requires-python = ">=3.9"

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils/__init__.py

@@ -21,6 +21,7 @@ from .model import (
     registry,
 )
 from .contract.policy import content_id, is_parseable, node_id, tiptap_id
+from .identity import new_node_id
 from .select import Selection
 from .shared import SharedFamilies, fingerprint, new_shared_id
 from .tasks import has_open_tasks, open_tasks, syncable_tasks
@@ -58,6 +59,7 @@ __all__ = [
     "is_parseable",
     "key",
     "kind",
+    "new_node_id",
     "new_shared_id",
     "node_id",
     "open_tasks",

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils/codec/__init__.py

@@ -8,6 +8,7 @@ from .raw import (
     require_object,
 )
 from .reader import (
+    build_node,
     read_children,
     read_doc,
     read_node,
@@ -16,6 +17,7 @@ from .reader import (
 from .writer import dump, dumps
 
 __all__ = [
+    "build_node",
     "dump",
     "dumps",
     "normalize_text",

tiptap_python_utils-0.5.0/src/tiptap_python_utils/codec/reader.py

@@ -0,0 +1,95 @@
+"""Raw TipTap JSON → typed AST hydration."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from ..contract import key, kind
+from ..exceptions import TiptapValidationError
+from ..model import ContentTuple, Doc, Node, registry
+from ..model.payload import has_any_identity
+from .raw import require_object
+
+
+# Kinds that hold block/container children, never inline text directly.
+_TEXT_REJECTING_KINDS = frozenset(
+    {
+        kind.DOC,
+        kind.BULLET_LIST,
+        kind.ORDERED_LIST,
+        kind.TASK_LIST,
+        kind.LIST_ITEM,
+        kind.TASK_ITEM,
+        kind.BLOCKQUOTE,
+        kind.TABLE_CELL,
+    }
+)
+
+
+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 build_node(
+    node_kind: str,
+    text: str = "",
+    *,
+    attrs: Optional[Dict[str, Any]] = None,
+    node_id: Optional[str] = None,
+) -> Node:
+    """Build any typed node from (kind, text, attrs) via the registry.
+
+    Constructs a minimal raw payload and hydrates it through ``read_node`` so
+    subclass-typed fields (e.g. ``Heading.level``) and ``present`` semantics
+    are derived the same way as when parsing real JSON. Pure: ``node_id`` is
+    only stamped when ``attrs`` carries no identity of its own.
+    """
+    merged = dict(attrs or {})
+    if node_id is not None and not has_any_identity(merged):
+        merged[key.ID] = node_id
+
+    raw: Dict[str, Any] = {key.TYPE: node_kind}
+    if merged:
+        raw[key.ATTRS] = merged
+    if text:
+        _attach_text(raw, node_kind, text)
+    return read_node(raw)
+
+
+def _attach_text(raw: Dict[str, Any], node_kind: str, text: str) -> None:
+    if node_kind == kind.TEXT:
+        raw[key.TEXT] = text
+    elif node_kind in _TEXT_REJECTING_KINDS:
+        raise TiptapValidationError(
+            f"Node kind '{node_kind}' cannot hold inline text content"
+        )
+    else:
+        raw[key.CONTENT] = [{key.TYPE: kind.TEXT, key.TEXT: text}]
+
+
+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-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils/content.py

@@ -5,13 +5,14 @@ from __future__ import annotations
 import json
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import Any, Dict, Iterator, Optional
+from typing import Any, Callable, Dict, Iterator, Optional
 
 from .exceptions import TiptapValidationError
 from .types import DocumentContent
 
 from . import codec
 from .contract import key, kind, policy
+from .identity import new_node_id
 from .model import (
     Blockquote,
     BulletList,
@@ -118,6 +119,9 @@ class Content:
             tuple(ref for ref in self.refs() if ref.node.kind == node_kind),
         )
 
+    def where(self, pred: Callable[[Node], bool]) -> Selection:
+        return Selection(self, tuple(self.refs())).filter(pred)
+
     def where_shared_id(self, shared_id: str) -> Selection:
         return Selection(
             self,
@@ -148,6 +152,19 @@ class Content:
             return self
         return Selection(self, refs).transform(families.merge)
 
+    def append(
+        self,
+        node_kind: str,
+        text: str = "",
+        *,
+        attrs: Optional[Dict[str, Any]] = None,
+        node_id: Optional[str] = None,
+    ) -> "Content":
+        node = codec.build_node(
+            node_kind, text, attrs=attrs, node_id=node_id or new_node_id()
+        )
+        return self.append_root(node)
+
     def append_root(self, node_or_raw: Any) -> "Content":
         return self.of(kind.DOC).append(node_or_raw)
 

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils/contract/key.py

@@ -8,6 +8,8 @@ MARKS = "marks"
 ID = "id"
 TIPTAP_ID = "tiptapId"
 SHARED_ID = "sharedId"
+SHARED = "shared"
+PLACE = "place"
 LEVEL = "level"
 CHECKED = "checked"
 STATUS = "status"

tiptap_python_utils-0.5.0/src/tiptap_python_utils/identity.py

@@ -0,0 +1,9 @@
+"""Generic node identity primitives."""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+
+def new_node_id() -> str:
+    return uuid4().hex

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils/select/selection.py

@@ -43,6 +43,14 @@ class Selection:
         leaves = tuple(leaf for ref in self._refs for leaf in _first_text_descendant(ref))
         return Selection(self._content, leaves)
 
+    def filter(self, pred: Callable[[Node], bool]) -> "Selection":
+        """Narrow the selection to refs whose node matches ``pred``."""
+        return Selection(self._content, tuple(r for r in self._refs if pred(r.node)))
+
+    def any(self, pred: Callable[[Node], bool] = lambda _node: True) -> bool:
+        """True if any selected node matches ``pred`` (short-circuits)."""
+        return any(pred(r.node) for r in self._refs)
+
     def text(self, value: str) -> "Content":
         self._require_text_only("text")
         return self._apply(lambda node: node.with_text(value))

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils/shared/families.py

@@ -52,13 +52,22 @@ class SharedFamilies:
         return len(self._bodies)
 
     def merge(self, target: Node) -> Node:
-        """Return target rewritten from the canonical body, preserving local id and sharedId."""
+        """Return target rewritten from the canonical body.
+
+        Preserves the target's per-copy identity (local id, sharedId) and its
+        per-copy ``place`` discriminator. The family-identical ``shared`` core
+        rides along from the canonical body unchanged.
+        """
         canonical = self[target.shared_id]
         raw = canonical.raw()
         attrs = dict(raw.get(key.ATTRS, {}))
+        attrs.pop(key.PLACE, None)
         if target.id:
             attrs[key.ID] = target.id
         if target.shared_id:
             attrs[key.SHARED_ID] = target.shared_id
+        target_attrs = target.raw().get(key.ATTRS, {})
+        if key.PLACE in target_attrs:
+            attrs[key.PLACE] = target_attrs[key.PLACE]
         raw[key.ATTRS] = attrs
         return codec.read_node(raw)

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils/shared/fingerprint.py

@@ -13,6 +13,9 @@ def fingerprint(node: Node) -> str:
     attrs = dict(raw.get(key.ATTRS, {}))
     attrs.pop(key.ID, None)
     attrs.pop(key.SHARED_ID, None)
+    attrs.pop(key.SHARED, None)
+    attrs.pop(key.PLACE, None)
+    attrs.pop(key.TASK_CANONICAL_ID, None)
     if attrs:
         raw[key.ATTRS] = attrs
     else:

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0/src/tiptap_python_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiptap_python_utils
-Version: 0.3.0
+Version: 0.5.0
 Summary: Python utilities for parsing, traversing, editing, and serializing TipTap JSON content.
 Author: tiptap_python_utils contributors
 License: MIT License
@@ -149,6 +149,22 @@ content.where_id("p1")
 
 # By TipTap kind.
 content.of(kind.PARAGRAPH)
+
+# By an arbitrary predicate over every node (and its descendants).
+content.where(lambda node: getattr(node, "level", None) == 1)
+```
+
+### Generic queries
+
+`Selection` carries two predicate primitives that work for any kind, so you
+don't need a bespoke `has_heading_text`-style helper per node type:
+
+```python
+# Narrow a selection further.
+content.of(kind.HEADING).filter(lambda n: n.level == 2)
+
+# Existence check (short-circuits).
+content.of(kind.HEADING).any(lambda n: n.text.strip() == "Introduction")
 ```
 
 ### Atomic mutations
@@ -175,6 +191,11 @@ content.where_id("ul1").append({"type": "listItem", "attrs": {"id": "li-new"}, "
 # Append a node to the document root.
 content.append_root({"type": "paragraph", "attrs": {"id": "p2"}, "content": []})
 
+# Build-and-append in one call — works for any kind, stamps a fresh id when
+# none is given. Typed fields (e.g. Heading.level) hydrate correctly.
+content.append(kind.HEADING, "New section", attrs={"level": 2})
+content.append(kind.PARAGRAPH, "Body text", node_id="p3")
+
 # Replace a node by id (the replacement's attrs.id must match).
 content.replace_by_id("p1", {
     "type": "paragraph",
@@ -281,6 +302,7 @@ from tiptap_python_utils import (
     Text,
     has_open_tasks,
     kind,
+    new_node_id,
     new_shared_id,
     open_tasks,
     text_slices,

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/src/tiptap_python_utils.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 src/tiptap_python_utils/__init__.py
 src/tiptap_python_utils/content.py
 src/tiptap_python_utils/exceptions.py
+src/tiptap_python_utils/identity.py
 src/tiptap_python_utils/py.typed
 src/tiptap_python_utils/types.py
 src/tiptap_python_utils.egg-info/PKG-INFO
@@ -44,6 +45,7 @@ tests/test_compat_imports.py
 tests/test_content.py
 tests/test_extract.py
 tests/test_filter.py
+tests/test_generic_helpers.py
 tests/test_mutations.py
 tests/test_public_api.py
 tests/test_traverser.py

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/tests/test_compat_imports.py

@@ -20,6 +20,7 @@ import pytest
 SUBPACKAGE_PUBLIC_NAMES: dict[str, frozenset[str]] = {
     "tiptap_python_utils.codec": frozenset(
         {
+            "build_node",
             "dump",
             "dumps",
             "normalize_text",

tiptap_python_utils-0.5.0/tests/test_generic_helpers.py

@@ -0,0 +1,192 @@
+"""Unit tests for the generic node helpers.
+
+Covers the cross-cutting construction/query layer:
+``codec.build_node``, ``Content.append``, ``Content.where``,
+``Selection.filter`` / ``Selection.any``, and ``new_node_id``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tiptap_python_utils import (
+    Content,
+    Heading,
+    TaskItem,
+    Text,
+    TiptapValidationError,
+    key,
+    kind,
+    new_node_id,
+)
+from tiptap_python_utils.codec import build_node
+
+pytestmark = [pytest.mark.unit]
+
+
+# ---------------------------------------------------------------------------
+# new_node_id
+# ---------------------------------------------------------------------------
+
+
+def test_new_node_id_is_unique_and_unprefixed() -> None:
+    a, b = new_node_id(), new_node_id()
+    assert a != b
+    assert not a.startswith("shared-")  # distinct from new_shared_id()
+
+
+# ---------------------------------------------------------------------------
+# build_node — typed-field hydration
+# ---------------------------------------------------------------------------
+
+
+def test_build_node_hydrates_heading_level_from_attrs() -> None:
+    node = build_node(kind.HEADING, "Title", attrs={key.LEVEL: 3})
+    assert isinstance(node, Heading)
+    assert node.level == 3
+    assert node.text == "Title"
+
+
+def test_build_node_default_has_no_content_when_text_empty() -> None:
+    node = build_node(kind.PARAGRAPH)
+    assert node.content == ()
+    assert key.CONTENT not in node.present
+
+
+def test_build_node_with_text_creates_single_text_child() -> None:
+    node = build_node(kind.PARAGRAPH, "hello")
+    assert len(node.content) == 1
+    child = node.content[0]
+    assert isinstance(child, Text)
+    assert child.text == "hello"
+
+
+def test_build_node_text_kind_sets_value_not_child() -> None:
+    node = build_node(kind.TEXT, "raw")
+    assert isinstance(node, Text)
+    assert node.text == "raw"
+    assert node.content == ()
+
+
+def test_build_node_task_item_derives_identity_from_attrs() -> None:
+    node = build_node(kind.TASK_ITEM, attrs={key.ID: "t1"})
+    assert isinstance(node, TaskItem)
+    assert node.local_task_item_id == "t1"
+
+
+# ---------------------------------------------------------------------------
+# build_node — identity stamping
+# ---------------------------------------------------------------------------
+
+
+def test_build_node_stamps_node_id_when_attrs_have_no_identity() -> None:
+    node = build_node(kind.PARAGRAPH, node_id="p1")
+    assert node.attrs.get(key.ID) == "p1"
+
+
+def test_build_node_keeps_existing_identity_over_node_id() -> None:
+    node = build_node(kind.PARAGRAPH, attrs={key.ID: "kept"}, node_id="ignored")
+    assert node.attrs.get(key.ID) == "kept"
+
+
+def test_build_node_pure_when_no_node_id_given() -> None:
+    node = build_node(kind.PARAGRAPH, attrs={key.LEVEL: 1})
+    assert key.ID not in node.attrs
+
+
+# ---------------------------------------------------------------------------
+# build_node — container rejects inline text
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "container", [kind.BULLET_LIST, kind.ORDERED_LIST, kind.TASK_LIST, kind.DOC]
+)
+def test_build_node_rejects_text_on_containers(container: str) -> None:
+    with pytest.raises(TiptapValidationError):
+        build_node(container, "nope")
+
+
+def test_build_node_round_trips_extra_fields() -> None:
+    node = build_node(kind.PARAGRAPH, "x")
+    raw = node.raw()
+    assert raw[key.TYPE] == kind.PARAGRAPH
+    assert raw[key.CONTENT][0][key.TEXT] == "x"
+
+
+# ---------------------------------------------------------------------------
+# Content.append
+# ---------------------------------------------------------------------------
+
+
+def _empty() -> Content:
+    return Content.require({"type": "doc", "content": []})
+
+
+def test_append_stamps_fresh_id_when_omitted() -> None:
+    content = _empty().append(kind.HEADING, "H", attrs={key.LEVEL: 2})
+    [heading] = content.headings
+    assert heading.attrs.get(key.ID)  # non-empty
+    assert heading.level == 2
+
+
+def test_append_keeps_given_node_id() -> None:
+    content = _empty().append(kind.PARAGRAPH, "p", node_id="given")
+    [para] = content.paragraphs
+    assert para.attrs.get(key.ID) == "given"
+
+
+def test_append_adds_node_to_root() -> None:
+    content = _empty().append(kind.HEADING, "Visible")
+    assert any(h.text == "Visible" for h in content.headings)
+
+
+# ---------------------------------------------------------------------------
+# Content.where / Selection.filter / Selection.any
+# ---------------------------------------------------------------------------
+
+
+def _two_headings() -> Content:
+    return (
+        _empty()
+        .append(kind.HEADING, "Intro", attrs={key.LEVEL: 1})
+        .append(kind.HEADING, "Body", attrs={key.LEVEL: 2})
+    )
+
+
+def test_where_filters_by_predicate() -> None:
+    content = _two_headings()
+    selected = content.where(
+        lambda n: n.kind == kind.HEADING and getattr(n, "text", "") == "Body"
+    )
+    assert len(selected) == 1
+    assert selected.nodes[0].text == "Body"
+
+
+def test_where_visits_all_refs_including_descendants() -> None:
+    content = _two_headings()
+    # Generic where() is not kind-scoped: a Heading and its Text child both
+    # expose .text == "Body".
+    selected = content.where(lambda n: getattr(n, "text", "") == "Body")
+    assert len(selected) == 2
+
+
+def test_selection_any_short_circuits_true() -> None:
+    content = _two_headings()
+    assert content.of(kind.HEADING).any(lambda n: n.text == "Intro") is True
+
+
+def test_selection_any_false_on_no_match() -> None:
+    content = _two_headings()
+    assert content.of(kind.HEADING).any(lambda n: n.text == "Missing") is False
+
+
+def test_selection_any_false_on_empty_selection() -> None:
+    content = _empty()
+    assert content.of(kind.HEADING).any() is False
+
+
+def test_has_heading_text_via_generic_query() -> None:
+    content = _two_headings()
+    # The replacement for the old heading-specific has_heading_text:
+    assert content.of(kind.HEADING).any(lambda n: n.text.strip() == "Body")

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/tests/test_mutations.py

@@ -140,6 +140,136 @@ def test_sync_shared_no_op_when_no_matching_shared_id():
     assert rewritten.dump() == target.dump()
 
 
+# ---------------------------------------------------------------------------
+# Self-describing shared core: `shared` (family-identical) + `place` (per-copy)
+# ---------------------------------------------------------------------------
+
+
+def test_shared_families_ignores_shared_and_place_when_fingerprinting():
+    # Two members of one family, identical body text, but differing per-copy
+    # `place` and differing `shared` core. These keys are provenance, not body,
+    # so the fingerprint must ignore them and NOT flag a conflict.
+    content = Content.require(
+        json.dumps(
+            {
+                "type": "doc",
+                "content": [
+                    {
+                        "type": "paragraph",
+                        "attrs": {
+                            "id": "n1",
+                            "sharedId": "shared-1",
+                            "shared": {"id": "shared-1", "topics": ["a"]},
+                            "place": {"context": "dated_note", "topicId": None},
+                        },
+                        "content": [{"type": "text", "text": "same body"}],
+                    },
+                    {
+                        "type": "paragraph",
+                        "attrs": {
+                            "id": "n2",
+                            "sharedId": "shared-1",
+                            "shared": {"id": "shared-1", "topics": ["b"]},
+                            "place": {"context": "undated_note", "topicId": "t-1"},
+                        },
+                        "content": [{"type": "text", "text": "same body"}],
+                    },
+                ],
+            }
+        )
+    )
+
+    families = content.shared_families()
+
+    assert "shared-1" in families
+
+
+def test_shared_families_still_rejects_real_body_divergence_despite_place():
+    # Differing `place` must not mask a genuine body difference: the text still
+    # differs, so this remains a conflict (guards against over-stripping).
+    content = Content.require(
+        json.dumps(
+            {
+                "type": "doc",
+                "content": [
+                    {
+                        "type": "paragraph",
+                        "attrs": {
+                            "id": "n1",
+                            "sharedId": "shared-1",
+                            "place": {"context": "dated_note", "topicId": None},
+                        },
+                        "content": [{"type": "text", "text": "one"}],
+                    },
+                    {
+                        "type": "paragraph",
+                        "attrs": {
+                            "id": "n2",
+                            "sharedId": "shared-1",
+                            "place": {"context": "undated_note", "topicId": "t-1"},
+                        },
+                        "content": [{"type": "text", "text": "two"}],
+                    },
+                ],
+            }
+        )
+    )
+
+    with pytest.raises(TiptapValidationError, match="Conflicting node bodies detected"):
+        content.shared_families()
+
+
+def test_sync_shared_preserves_per_copy_place_and_carries_shared_core():
+    source = Content.require(
+        json.dumps(
+            {
+                "type": "doc",
+                "content": [
+                    {
+                        "type": "paragraph",
+                        "attrs": {
+                            "id": "source-id",
+                            "sharedId": "shared-1",
+                            "shared": {"id": "shared-1", "primaryTopic": "t-react"},
+                            "place": {"context": "dated_note", "topicId": None},
+                        },
+                        "content": [{"type": "text", "text": "new"}],
+                    }
+                ],
+            }
+        )
+    )
+    target = Content.require(
+        json.dumps(
+            {
+                "type": "doc",
+                "content": [
+                    {
+                        "type": "paragraph",
+                        "attrs": {
+                            "id": "target-id",
+                            "sharedId": "shared-1",
+                            "shared": {"id": "shared-1", "primaryTopic": "STALE"},
+                            "place": {"context": "undated_note", "topicId": "t-react"},
+                        },
+                        "content": [{"type": "text", "text": "old"}],
+                    }
+                ],
+            }
+        )
+    )
+
+    rewritten = target.sync_shared(source.shared_families())
+    node = json.loads(rewritten.dump())["content"][0]
+
+    # Body + family-identical `shared` core come from the canonical (source).
+    assert node["content"][0]["text"] == "new"
+    assert node["attrs"]["shared"]["primaryTopic"] == "t-react"
+    # Per-copy identity and `place` stay the target's own.
+    assert node["attrs"]["id"] == "target-id"
+    assert node["attrs"]["place"] == {"context": "undated_note", "topicId": "t-react"}
+
+
 # ---------------------------------------------------------------------------
 # Node.with_shared_id
 # ---------------------------------------------------------------------------

{tiptap_python_utils-0.3.0 → tiptap_python_utils-0.5.0}/tests/test_public_api.py

@@ -44,6 +44,7 @@ EXPECTED_PUBLIC_API = frozenset(
         "is_parseable",
         "key",
         "kind",
+        "new_node_id",
         "new_shared_id",
         "node_id",
         "open_tasks",

tiptap_python_utils-0.3.0/src/tiptap_python_utils/codec/reader.py

@@ -1,42 +0,0 @@
-"""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