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

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/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/codec/reader.py

@@ -2,14 +2,30 @@
 
 from __future__ import annotations
 
-from typing import Any, Mapping
+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:
@@ -30,6 +46,43 @@ def read_children(raw_children: Any) -> ContentTuple:
     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):

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/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/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/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/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/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.dist-info → tiptap_python_utils-0.5.0.dist-info}/METADATA

@@ -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.dist-info → tiptap_python_utils-0.5.0.dist-info}/RECORD

@@ -1,14 +1,15 @@
-tiptap_python_utils/__init__.py,sha256=J78QM5SdfIB3qEeZ0f0ejFJgE1lS8o6VJdCxD5_yCkc,1417
-tiptap_python_utils/content.py,sha256=NfTow1rPtTKcBkYTyPA50y0mjmlq57uXnXwFeKgKH_0,6522
+tiptap_python_utils/__init__.py,sha256=OBr4gCjfFWNe8MLv_JDb6_-_8EYRebbCiuAWTkEZIEI,1470
+tiptap_python_utils/content.py,sha256=3PtrEfmXyOMPoHVEH8xxHUYozIab5WlG1EXiPj0DAvs,7048
 tiptap_python_utils/exceptions.py,sha256=GIP91_6gaz4Vp-uMbmZBFFpnHHvToKYWyYf78Apt0ns,150
+tiptap_python_utils/identity.py,sha256=cXqAECIqft4My575tp-jUjKhv2oTAEQnQdDSVsva6Ps,151
 tiptap_python_utils/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 tiptap_python_utils/types.py,sha256=f6ocw9oOTyj_khush3bP5cHS2YpybKS0jQgjzSNVx_k,152
-tiptap_python_utils/codec/__init__.py,sha256=by1i-NoxvdH-_sBxYRQrm_P5EaOCRDYss7pkcj-zot4,476
+tiptap_python_utils/codec/__init__.py,sha256=kaqQ9OHJg_S0hwLFGS55_Mdhyr2wt9BRMrdYfhIKdHI,510
 tiptap_python_utils/codec/raw.py,sha256=glQWotPxzOFvPkg3nBBk3GbcM03Cj2yRclG62ckb1k0,2082
-tiptap_python_utils/codec/reader.py,sha256=zBJQZ8NX3MuNNhEZbP2POjj9OnkiO64jnGoKDvbqju0,1376
+tiptap_python_utils/codec/reader.py,sha256=LOcGgx8eFOWH_5LyI2ydBfJP54XwJxqFBjOs8zUUYCE,2963
 tiptap_python_utils/codec/writer.py,sha256=YkOyHkkiufCRFUDtnuGXd6AD4a57mDsDWksn4ZFzyyc,285
 tiptap_python_utils/contract/__init__.py,sha256=gJMHPqIl6vkcXAOKNKtZIbs8aQs1abqykEpc5i3abQY,115
-tiptap_python_utils/contract/key.py,sha256=6T4Y-26hESduXmLaNOOpbZ-zTYkHgABvDCHjL6b2VDM,260
+tiptap_python_utils/contract/key.py,sha256=JV-pBYY_zO9uZ3XWQtjzrTcmhgisVFO2O-zscrUHhPA,294
 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
@@ -17,10 +18,10 @@ tiptap_python_utils/model/nodes.py,sha256=obi8prcwJeJ3MBGZNCdbiGBwiPNJhiKb08b3oW
 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=oTJ5l4o4vr0yKMXcIfhZInzXFqD8X6T9ZhE2WSxpVEY,4999
+tiptap_python_utils/select/selection.py,sha256=j-3x_MgNdp88dlwWKDdDrXkyDoCXleXuvlnVQdWTezM,5432
 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/families.py,sha256=T89HaILztYmEJU_0rWeJYQuTc1uU0oCS1QuYQF_b-wg,2440
+tiptap_python_utils/shared/fingerprint.py,sha256=X0zrxbjM-ATUukXp5YUYBW9XzkeeYxP7szpHeFBsr_8,582
 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
@@ -30,8 +31,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.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-0.5.0.dist-info/licenses/LICENSE,sha256=pIGeAFdiaTJBpJilmEbR8YQ5agrt7DqbGlTTrzqO6Qo,1089
+tiptap_python_utils-0.5.0.dist-info/METADATA,sha256=Nbe0TNUp5hKT2WjMRmsV2fVkmHqSq3k2dJgm8SiGhqg,11649
+tiptap_python_utils-0.5.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tiptap_python_utils-0.5.0.dist-info/top_level.txt,sha256=t7g66MmK6WqTixs5_ZnXe4j-RvH9thuDRKvxk_8F0AQ,20
+tiptap_python_utils-0.5.0.dist-info/RECORD,,