tiptap-python-utils 0.2.0__tar.gz → 0.4.0__tar.gz

{tiptap_python_utils-0.2.0/src/tiptap_python_utils.egg-info → tiptap_python_utils-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiptap_python_utils
-Version: 0.2.0
+Version: 0.4.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 → tiptap_python_utils-0.4.0}/README.md

@@ -168,36 +168,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`
@@ -217,13 +225,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 → tiptap_python_utils-0.4.0}/pyproject.toml

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

{tiptap_python_utils-0.2.0 → tiptap_python_utils-0.4.0}/src/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-0.2.0 → tiptap_python_utils-0.4.0}/src/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-0.2.0 → tiptap_python_utils-0.4.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.2.0 → tiptap_python_utils-0.4.0}/src/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-0.2.0 → tiptap_python_utils-0.4.0}/src/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-0.2.0 → tiptap_python_utils-0.4.0}/src/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-0.4.0/src/tiptap_python_utils/shared/__init__.py

@@ -0,0 +1,11 @@
+"""Shared-node service exports."""
+
+from .families import SharedFamilies
+from .fingerprint import fingerprint
+from .identity import new_shared_id
+
+__all__ = [
+    "SharedFamilies",
+    "fingerprint",
+    "new_shared_id",
+]

tiptap_python_utils-0.4.0/src/tiptap_python_utils/shared/families.py

@@ -0,0 +1,73 @@
+"""SharedFamilies: canonical bodies grouped by sharedId."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Iterator, Mapping
+
+from .. import codec
+from ..contract import key
+from ..exceptions import TiptapValidationError
+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.
+
+        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.4.0/src/tiptap_python_utils/shared/fingerprint.py

@@ -0,0 +1,23 @@
+"""Identity-stripped fingerprint of a node, used to detect divergent bodies."""
+
+from __future__ import annotations
+
+import json
+
+from ..contract import key
+from ..model import Node
+
+
+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)
+    attrs.pop(key.SHARED, None)
+    attrs.pop(key.PLACE, None)
+    attrs.pop(key.TASK_CANONICAL_ID, None)
+    if attrs:
+        raw[key.ATTRS] = attrs
+    else:
+        raw.pop(key.ATTRS, None)
+    return json.dumps(raw, sort_keys=True)

tiptap_python_utils-0.4.0/src/tiptap_python_utils/shared/identity.py

@@ -0,0 +1,9 @@
+"""Shared-node identity primitives."""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+
+def new_shared_id() -> str:
+    return f"shared-{uuid4().hex}"

{tiptap_python_utils-0.2.0 → tiptap_python_utils-0.4.0/src/tiptap_python_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiptap_python_utils
-Version: 0.2.0
+Version: 0.4.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 → tiptap_python_utils-0.4.0}/src/tiptap_python_utils.egg-info/SOURCES.txt

@@ -31,7 +31,6 @@ src/tiptap_python_utils/shared/__init__.py
 src/tiptap_python_utils/shared/families.py
 src/tiptap_python_utils/shared/fingerprint.py
 src/tiptap_python_utils/shared/identity.py
-src/tiptap_python_utils/shared/sync.py
 src/tiptap_python_utils/tasks/__init__.py
 src/tiptap_python_utils/tasks/query.py
 src/tiptap_python_utils/text/__init__.py

{tiptap_python_utils-0.2.0 → tiptap_python_utils-0.4.0}/tests/test_compat_imports.py

@@ -60,14 +60,9 @@ SUBPACKAGE_PUBLIC_NAMES: dict[str, frozenset[str]] = {
     "tiptap_python_utils.select": frozenset({"Selection"}),
     "tiptap_python_utils.shared": frozenset(
         {
-            "fingerprint_shared",
-            "has_shared",
+            "SharedFamilies",
+            "fingerprint",
             "new_shared_id",
-            "normalize_shared_id",
-            "shared_families",
-            "shared_id",
-            "stamp_shared",
-            "sync_shared",
         }
     ),
     "tiptap_python_utils.tasks": frozenset(