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

tiptap_python_utils/__init__.py

@@ -22,15 +22,7 @@ from .model import (
 )
 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 .shared import SharedFamilies, fingerprint, new_shared_id
 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
@@ -52,6 +44,7 @@ __all__ = [
     "Paragraph",
     "Ref",
     "Selection",
+    "SharedFamilies",
     "TableCell",
     "TaskItem",
     "TaskList",
@@ -60,9 +53,8 @@ __all__ = [
     "Unknown",
     "Walker",
     "content_id",
-    "fingerprint_shared",
+    "fingerprint",
     "has_open_tasks",
-    "has_shared",
     "is_parseable",
     "key",
     "kind",
@@ -70,10 +62,6 @@ __all__ = [
     "node_id",
     "open_tasks",
     "registry",
-    "shared_families",
-    "shared_id",
-    "stamp_shared",
-    "sync_shared",
     "syncable_tasks",
     "text_slices",
     "tiptap_id",

tiptap_python_utils/content.py

@@ -28,6 +28,7 @@ from .model import (
     Text,
 )
 from .select import Selection
+from .shared import SharedFamilies
 from .walk import Ref, Walker
 
 
@@ -117,6 +118,36 @@ class Content:
             tuple(ref for ref in self.refs() if ref.node.kind == node_kind),
         )
 
+    def where_shared_id(self, shared_id: str) -> Selection:
+        return Selection(
+            self,
+            tuple(
+                ref
+                for ref in self.refs(parseable=True)
+                if ref.node.shared_id == shared_id
+            ),
+        )
+
+    def has_shared(self, shared_id: str) -> bool:
+        return any(
+            ref.node.shared_id == shared_id for ref in self.refs(parseable=True)
+        )
+
+    def shared_families(self) -> SharedFamilies:
+        return SharedFamilies.from_content(self)
+
+    def sync_shared(self, families: SharedFamilies) -> "Content":
+        if self._root is None:
+            return self
+        refs = tuple(
+            ref
+            for ref in self.refs(parseable=True)
+            if ref.node.shared_id and ref.node.shared_id in families
+        )
+        if not refs:
+            return self
+        return Selection(self, refs).transform(families.merge)
+
     def append_root(self, node_or_raw: Any) -> "Content":
         return self.of(kind.DOC).append(node_or_raw)
 

tiptap_python_utils/model/base.py

@@ -79,6 +79,9 @@ class Node:
         attrs[name] = deepcopy(value)
         return replace(self, attrs=attrs, present=self.present | {key.ATTRS})
 
+    def with_shared_id(self, value: str) -> "Node":
+        return self.with_attr(key.SHARED_ID, value)
+
     def with_content(self, content: ContentTuple) -> "Node":
         return replace(self, content=content, present=self.present | {key.CONTENT})
 

tiptap_python_utils/model/nodes.py

@@ -66,10 +66,6 @@ class TaskItem(Node):
     def is_completed(self) -> bool:
         return bool(task_completion(self.attrs, self.extra))
 
-    @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 key.CHECKED in attrs or (

tiptap_python_utils/select/selection.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from copy import deepcopy
 from dataclasses import replace
-from typing import TYPE_CHECKING, Any, Iterator, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Tuple
 
 from .. import codec
 from ..contract import key
@@ -69,6 +69,9 @@ class Selection:
             raise TiptapValidationError("Child node content must not be a document root")
         return self._apply(lambda node: node.append(child))
 
+    def transform(self, fn: Callable[[Node], Node]) -> "Content":
+        return self._apply(fn)
+
     def dump(self) -> str:
         return self._content.dump()
 

tiptap_python_utils/shared/__init__.py

@@ -1,17 +1,11 @@
 """Shared-node service exports."""
 
-from .families import has_shared, shared_families
-from .fingerprint import fingerprint_shared
-from .identity import new_shared_id, normalize_shared_id, shared_id, stamp_shared
-from .sync import sync_shared
+from .families import SharedFamilies
+from .fingerprint import fingerprint
+from .identity import new_shared_id
 
 __all__ = [
-    "fingerprint_shared",
-    "has_shared",
+    "SharedFamilies",
+    "fingerprint",
     "new_shared_id",
-    "normalize_shared_id",
-    "shared_families",
-    "shared_id",
-    "stamp_shared",
-    "sync_shared",
 ]

tiptap_python_utils/shared/families.py

@@ -1,47 +1,64 @@
-"""Group canonical bodies by sharedId and answer presence queries."""
+"""SharedFamilies: canonical bodies grouped by sharedId."""
 
 from __future__ import annotations
 
-from copy import deepcopy
-from typing import Any, Dict
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Iterator, Mapping
 
-from ..content import Content
+from .. import codec
 from ..contract import key
 from ..exceptions import TiptapValidationError
-from .fingerprint import fingerprint_shared
-from .identity import normalize_shared_id
-
-
-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 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
+from ..model import Node
+from .fingerprint import fingerprint
+
+if TYPE_CHECKING:
+    from ..content import Content
+
+
+@dataclass(frozen=True)
+class SharedFamilies:
+    """Canonical node bodies indexed by sharedId."""
+
+    _bodies: Mapping[str, Node] = field(default_factory=lambda: MappingProxyType({}))
+
+    @classmethod
+    def from_content(cls, content: "Content") -> "SharedFamilies":
+        bodies: dict[str, Node] = {}
+        prints: dict[str, str] = {}
+        for ref in content.refs(parseable=True):
+            sid = ref.node.shared_id
+            if not sid:
+                continue
+            fp = fingerprint(ref.node)
+            if sid in prints and prints[sid] != fp:
+                raise TiptapValidationError(
+                    f"Conflicting node bodies detected for sharedId '{sid}'"
+                )
+            bodies.setdefault(sid, ref.node)
+            prints.setdefault(sid, fp)
+        return cls(MappingProxyType(bodies))
+
+    def __contains__(self, shared_id: str) -> bool:
+        return shared_id in self._bodies
+
+    def __getitem__(self, shared_id: str) -> Node:
+        return self._bodies[shared_id]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._bodies)
+
+    def __len__(self) -> int:
+        return len(self._bodies)
+
+    def merge(self, target: Node) -> Node:
+        """Return target rewritten from the canonical body, preserving local id and sharedId."""
+        canonical = self[target.shared_id]
+        raw = canonical.raw()
+        attrs = dict(raw.get(key.ATTRS, {}))
+        if target.id:
+            attrs[key.ID] = target.id
+        if target.shared_id:
+            attrs[key.SHARED_ID] = target.shared_id
+        raw[key.ATTRS] = attrs
+        return codec.read_node(raw)

tiptap_python_utils/shared/fingerprint.py

@@ -1,21 +1,20 @@
-"""Identity-stripped fingerprint of a raw node, used to detect divergent bodies."""
+"""Identity-stripped fingerprint of a node, used to detect divergent bodies."""
 
 from __future__ import annotations
 
 import json
-from copy import deepcopy
-from typing import Any
 
 from ..contract import key
+from ..model import Node
 
 
-def fingerprint_shared(node: dict[str, Any]) -> str:
-    normalized = deepcopy(node)
-    attrs = dict(normalized.get(key.ATTRS, {}))
+def fingerprint(node: Node) -> str:
+    raw = node.raw()
+    attrs = dict(raw.get(key.ATTRS, {}))
     attrs.pop(key.ID, None)
     attrs.pop(key.SHARED_ID, None)
     if attrs:
-        normalized[key.ATTRS] = attrs
+        raw[key.ATTRS] = attrs
     else:
-        normalized.pop(key.ATTRS, None)
-    return json.dumps(normalized, sort_keys=True)
+        raw.pop(key.ATTRS, None)
+    return json.dumps(raw, sort_keys=True)

tiptap_python_utils/shared/identity.py

@@ -1,48 +1,9 @@
-"""Shared-node identity primitives.
-
-Pure value-level helpers: normalize a sharedId, mint a new one, read a node's
-sharedId, and stamp identity onto a raw node payload. No document traversal,
-no families, no sync — those live in their sibling modules.
-"""
+"""Shared-node identity primitives."""
 
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
 from uuid import uuid4
 
-from .. import codec
-from ..contract import key
-
-
-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 new_shared_id() -> str:
     return f"shared-{uuid4().hex}"
-
-
-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 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

{tiptap_python_utils-0.2.0.dist-info → tiptap_python_utils-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiptap_python_utils
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python utilities for parsing, traversing, editing, and serializing TipTap JSON content.
 Author: tiptap_python_utils contributors
 License: MIT License
@@ -219,36 +219,44 @@ task.shared_id          # sharedId attr, if any
 
 ## Shared-Node Synchronization
 
-`shared_families` collects canonical bodies grouped by `sharedId`;
-`sync_shared` rewrites every matching node in a document using those canonical
-bodies while preserving per-instance identity (`id`, `sharedId`).
+`Content.shared_families()` collects canonical bodies grouped by `sharedId` into
+a `SharedFamilies` value object. `Content.sync_shared(families)` rewrites every
+matching node in the document from those canonical bodies, preserving
+per-instance identity (`id`, `sharedId`). Both return immutable values — the
+original `Content` is never mutated.
 
 ```python
-from tiptap_python_utils import shared_families, sync_shared
+from tiptap_python_utils import Content
 
 # Canonical doc: the source of truth for every shared body.
-canonical = {"type": "doc", "content": [
+canonical = Content.require({"type": "doc", "content": [
     {
         "type": "paragraph",
         "attrs": {"id": "p1", "sharedId": "intro"},
         "content": [{"type": "text", "text": "Authoritative intro"}],
     }
-]}
+]})
 
 # Doc that mirrors the same sharedId but with a stale body.
-target = {"type": "doc", "content": [
+target = Content.require({"type": "doc", "content": [
     {
         "type": "paragraph",
         "attrs": {"id": "p1-copy", "sharedId": "intro"},
         "content": [{"type": "text", "text": "Stale copy"}],
     }
-]}
+]})
 
-families = shared_families(canonical)
-synced_json, changed = sync_shared(target, families)
-assert changed is True
+synced = target.sync_shared(canonical.shared_families())
+assert synced.has_shared("intro")
 ```
 
+Related helpers on `Content`:
+
+- `content.where_shared_id(sid)` — `Selection` over every node with that sharedId.
+- `content.has_shared(sid)` — quick presence check.
+- `node.with_shared_id(sid)` — stamp a sharedId onto a node (returns a new node).
+- `new_shared_id()` — mint a fresh `shared-…` identifier.
+
 ## Architecture (one paragraph)
 
 The package is layered: `contract` (key/kind/policy primitives) → `model`
@@ -268,13 +276,13 @@ Common imports are available from the package root:
 from tiptap_python_utils import (
     Content,
     Paragraph,
+    SharedFamilies,
     TaskItem,
     Text,
     has_open_tasks,
     kind,
+    new_shared_id,
     open_tasks,
-    shared_families,
-    sync_shared,
     text_slices,
     visible_text,
     word_count,

{tiptap_python_utils-0.2.0.dist-info → tiptap_python_utils-0.3.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-tiptap_python_utils/__init__.py,sha256=okNcgTgISvshG4f7LCfGv4Q1GN2thdlPlIg7SAHWFTw,1590
-tiptap_python_utils/content.py,sha256=_-iwFt-4nDH4xxWkEFrzRVMPlufq43tRaKYJxNBBY1I,5557
+tiptap_python_utils/__init__.py,sha256=J78QM5SdfIB3qEeZ0f0ejFJgE1lS8o6VJdCxD5_yCkc,1417
+tiptap_python_utils/content.py,sha256=NfTow1rPtTKcBkYTyPA50y0mjmlq57uXnXwFeKgKH_0,6522
 tiptap_python_utils/exceptions.py,sha256=GIP91_6gaz4Vp-uMbmZBFFpnHHvToKYWyYf78Apt0ns,150
 tiptap_python_utils/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 tiptap_python_utils/types.py,sha256=f6ocw9oOTyj_khush3bP5cHS2YpybKS0jQgjzSNVx_k,152
@@ -12,17 +12,16 @@ tiptap_python_utils/contract/key.py,sha256=6T4Y-26hESduXmLaNOOpbZ-zTYkHgABvDCHjL
 tiptap_python_utils/contract/kind.py,sha256=I-vkJ9mskw07qjbIR5uC1s3z0AvtwA2y3qovkzTsY2Q,297
 tiptap_python_utils/contract/policy.py,sha256=AeJfLv07JWqhuJMakUgz1Y-bMpac28h426bj17hKvwk,1193
 tiptap_python_utils/model/__init__.py,sha256=Xv2GP0fCM72H2_Jxo5vvJfStA6ztDavzjYcaV0U0p9g,1049
-tiptap_python_utils/model/base.py,sha256=Lq5mFvzQRV_bi368szFGjee8mM_AJNIjtHe9sECUr4M,4558
-tiptap_python_utils/model/nodes.py,sha256=FKUgRAZWINNhUgiImkhkY5NcB7EzuRdb6Da40JUNI68,2989
+tiptap_python_utils/model/base.py,sha256=STQczhXwe49x48TrCXkIzU4F4vcz1FS65ipXS663Az4,4663
+tiptap_python_utils/model/nodes.py,sha256=obi8prcwJeJ3MBGZNCdbiGBwiPNJhiKb08b3oW5tTm4,2891
 tiptap_python_utils/model/payload.py,sha256=UAWAaXgh50tglwFGBjkWj5ngMHQE35XQR1oHNysHdTw,2417
 tiptap_python_utils/model/registry.py,sha256=2TbiEvUkVh85W0I0YKjpeVivcvKFCvcO1GtYEzMNu6Q,1168
 tiptap_python_utils/select/__init__.py,sha256=lFavos0E3w2D_keUPDa5xkWhIjkQiee7yNK7X-G-U6o,88
-tiptap_python_utils/select/selection.py,sha256=NAcnYfB-HGu4SlAlWPwyRpRkgRzIBjYJR4CCtSRAzSU,4891
-tiptap_python_utils/shared/__init__.py,sha256=IC6p4jp-f8Fe1QVQC2UvqnmBnyo2AlaAEDghqREyKZg,428
-tiptap_python_utils/shared/families.py,sha256=v8XUDKighu7q1EXGTDiEZMFGVs9qGFe57usiuq1LHbc,1596
-tiptap_python_utils/shared/fingerprint.py,sha256=_5l2ZKpUuZAcIjkoodKqoBHgKAMjL_wFKyqprNsRV_M,560
-tiptap_python_utils/shared/identity.py,sha256=IqNjSfgDtFS3GR0DP_nExECXV0WgNC2NDBs3Nc4KJPA,1347
-tiptap_python_utils/shared/sync.py,sha256=k2523VJJsiIRNrvJyt9W11Z7JIoniKSxTnrwtv43O1A,2127
+tiptap_python_utils/select/selection.py,sha256=oTJ5l4o4vr0yKMXcIfhZInzXFqD8X6T9ZhE2WSxpVEY,4999
+tiptap_python_utils/shared/__init__.py,sha256=XoRaVFjOlCWbnTeTFKw5DdoLqGA6sGdRr0eGpSkFQS8,223
+tiptap_python_utils/shared/families.py,sha256=7B39bXpEePfearOl2tzLDuJelo1yG67-anzVlmnidVs,2069
+tiptap_python_utils/shared/fingerprint.py,sha256=YUKhUgPXIEFQ_ujUxnh1jPfxT1eilrFP_-hmqXmlkCM,476
+tiptap_python_utils/shared/identity.py,sha256=cwUy6CMvlGV15Z8FyY3idDl2tPs9eiIWbwJRsNQgwY0,164
 tiptap_python_utils/tasks/__init__.py,sha256=EXNu9YfJHBjyUZGf5HJIvaW7Ub_aN6fw_CZBNjBW0Og,154
 tiptap_python_utils/tasks/query.py,sha256=59hb0fubBHlfOQekv_KY3DbTEBPFdYh_1Tc9LuFsL9w,464
 tiptap_python_utils/text/__init__.py,sha256=F8PVtbGQlshGAtNLGNhGt8eyOwyE3Z5GC2lZLovxWg4,170
@@ -31,8 +30,8 @@ tiptap_python_utils/tree/__init__.py,sha256=YzlXRkQrlRGYmkWbpZ8mutZOmK4BzmiZaBqU
 tiptap_python_utils/tree/path.py,sha256=bHmBFIZ3BV4FVlB79HhSgjeP6qHdNXClB9DFovSe8fs,1067
 tiptap_python_utils/walk/__init__.py,sha256=hKU7DhRY6HVlxCxyWmnZtoobWNx5MCIT0OoErGe4Bp4,120
 tiptap_python_utils/walk/traversal.py,sha256=6GDFmPAuo_t4FeOeV6hqrqvwcTZ8G93ep21-hrFt7S0,2320
-tiptap_python_utils-0.2.0.dist-info/licenses/LICENSE,sha256=pIGeAFdiaTJBpJilmEbR8YQ5agrt7DqbGlTTrzqO6Qo,1089
-tiptap_python_utils-0.2.0.dist-info/METADATA,sha256=CXKgXRn7hKpmQre_D9YMroy27b-k83RgFoGyLweOwpU,10411
-tiptap_python_utils-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-tiptap_python_utils-0.2.0.dist-info/top_level.txt,sha256=t7g66MmK6WqTixs5_ZnXe4j-RvH9thuDRKvxk_8F0AQ,20
-tiptap_python_utils-0.2.0.dist-info/RECORD,,
+tiptap_python_utils-0.3.0.dist-info/licenses/LICENSE,sha256=pIGeAFdiaTJBpJilmEbR8YQ5agrt7DqbGlTTrzqO6Qo,1089
+tiptap_python_utils-0.3.0.dist-info/METADATA,sha256=wuFsehiOaIjsPpYh9FegYN6OeXddbnlnDbIufDlAyPA,10854
+tiptap_python_utils-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tiptap_python_utils-0.3.0.dist-info/top_level.txt,sha256=t7g66MmK6WqTixs5_ZnXe4j-RvH9thuDRKvxk_8F0AQ,20
+tiptap_python_utils-0.3.0.dist-info/RECORD,,

tiptap_python_utils/shared/sync.py

@@ -1,63 +0,0 @@
-"""Rewrite shared nodes from canonical bodies while preserving local identity."""
-
-from __future__ import annotations
-
-from copy import deepcopy
-from typing import Any, Dict
-
-from .. import codec
-from ..content import Content
-from ..contract import key
-from ..tree import node_at_path, replace_at_path
-from .identity import normalize_shared_id
-
-
-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 _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