tiptap-python-utils 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

tiptap_python_utils/__init__.py

@@ -1,5 +1,6 @@
 """Public API for TipTap JSON utilities."""
 
+from . import task
 from .contract import key, kind
 from .content import Content
 from .exceptions import TiptapValidationError
@@ -21,6 +22,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,11 +60,13 @@ __all__ = [
     "is_parseable",
     "key",
     "kind",
+    "new_node_id",
     "new_shared_id",
     "node_id",
     "open_tasks",
     "registry",
     "syncable_tasks",
+    "task",
     "text_slices",
     "tiptap_id",
     "visible_text",

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/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/task.py

@@ -0,0 +1,55 @@
+"""Pure, raw-dict helpers for TipTap ``taskList`` / ``taskItem`` shapes.
+
+This module is the raw-dict counterpart to the typed ``tasks`` package:
+``tasks`` works on hydrated ``Content``/``TaskItem`` objects, while ``task``
+deals only with plain TipTap JSON dicts and never imports the model layer.
+
+Read as a namespace: ``task.create_list(...)``, ``task.is_list(...)``,
+``task.is_item(...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+from .contract import key, kind
+
+__all__ = ["create_list", "is_item", "is_list"]
+
+
+def create_list(items: List[Any]) -> dict:
+    """Wrap ``items`` in a ``taskList`` block.
+
+    By design this does **not** copy ``items`` — the same list object is
+    stored on the returned block's ``content`` (by reference). Callers may
+    keep appending to the original list afterwards and see the change
+    reflected here. Do not introduce ``deepcopy``/``list(...)``/``[*items]``
+    here: the shared-reference behaviour is part of the contract and is
+    pinned by ``tests/test_task_namespace.py``.
+    """
+    return {key.TYPE: kind.TASK_LIST, key.CONTENT: items}
+
+
+def is_list(item: Any) -> bool:
+    """True iff ``item`` is a valid ``taskList`` dict.
+
+    Safe on missing keys (uses ``.get()``): all three conditions must hold —
+    ``item`` is a dict, its ``type`` is ``taskList``, and its ``content`` is a
+    list.
+    """
+    if not isinstance(item, dict):
+        return False
+    return item.get(key.TYPE) == kind.TASK_LIST and isinstance(
+        item.get(key.CONTENT), list
+    )
+
+
+def is_item(node: Any) -> bool:
+    """True iff ``node`` is a ``taskItem`` dict.
+
+    Safe on missing keys: ``node`` must be a dict whose ``type`` is
+    ``taskItem``.
+    """
+    if not isinstance(node, dict):
+        return False
+    return node.get(key.TYPE) == kind.TASK_ITEM

{tiptap_python_utils-0.4.0.dist-info → tiptap_python_utils-0.6.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tiptap_python_utils
-Version: 0.4.0
-Summary: Python utilities for parsing, traversing, editing, and serializing TipTap JSON content.
+Version: 0.6.0
+Summary: Pure-Python utilities for processing TipTap JSON on the server side. Parse, traverse, edit, and serialize TipTap documents — no JavaScript bridge required. Zero runtime dependencies, Python 3.9+.
 Author: tiptap_python_utils contributors
 License: MIT License
         
@@ -56,23 +56,10 @@ Dynamic: license-file
 [![CI](https://github.com/tugkanpilka/tiptap-python-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/tugkanpilka/tiptap-python-utils/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Python utilities for [TipTap](https://tiptap.dev) JSON content.
-
-`tiptap_python_utils` parses TipTap documents into typed, immutable Python
-nodes, preserves unknown/custom nodes for lossless round trips, and provides
-small helpers for traversal, immutable edits, visible text extraction, task
-queries, and shared-node synchronization.
-
-- **Zero runtime dependencies.** Standard library only.
-- **Python 3.9+.** Tested on 3.9, 3.10, 3.11, 3.12, 3.13.
-- **Lossless round trip.** Unknown node kinds and any extra fields are preserved.
-- **Immutable AST.** All mutations return new instances via a fluent selection API.
-
-## Install
-
-```bash
-pip install tiptap_python_utils
-```
+TipTap is a JavaScript editor. If your backend is Python and you need to
+process TipTap JSON — extract text, query tasks, sync shared nodes — this
+library does it in pure Python with zero dependencies. No JS bridge, no
+Node.js subprocess.
 
 ## Quick Start
 
@@ -94,8 +81,24 @@ raw = {
 updated = Content.require(raw).where_id("p1").leaf().text("New").dump()
 ```
 
+## Features
+
+- **Zero runtime dependencies.** Standard library only.
+- **Python 3.9+.** Tested on 3.9, 3.10, 3.11, 3.12, 3.13.
+- **Lossless round trip.** Unknown node kinds and any extra fields are preserved.
+- **Immutable AST.** All mutations return new instances via a fluent selection API.
+
+## Install
+
+```bash
+pip install tiptap_python_utils
+```
+
 ## Three Ways to Load a Document
 
+Pick a constructor by how much you trust the input — lenient, strict, or
+auto-wrapping a bare node into a `doc`.
+
 | Constructor | When to use | On invalid input |
 |---|---|---|
 | `Content.parse(raw)` | Lenient — `raw` may be `None`, a string, or a dict | Returns a `Content` with `root=None` |
@@ -104,7 +107,8 @@ updated = Content.require(raw).where_id("p1").leaf().text("New").dump()
 
 ## Lossless Round Trip
 
-Parsing never silently drops fields. Two mechanisms preserve information:
+Parsing never silently drops fields — custom nodes and unknown keys survive a
+parse-then-serialize cycle byte-for-byte. Two mechanisms preserve information:
 
 - `Node.extra` stores top-level keys that aren't part of the known schema
   (e.g. custom node attributes, vendor-specific keys).
@@ -125,7 +129,8 @@ assert Content.require(raw).to_dict() == raw  # byte-for-byte
 
 ## Typed Nodes
 
-Build typed nodes directly and serialize them back to TipTap-compatible JSON:
+Build typed nodes directly in Python and serialize them back to
+TipTap-compatible JSON.
 
 ```python
 from tiptap_python_utils import Content, Paragraph, Text
@@ -136,8 +141,8 @@ doc = Content.wrap(node.raw())
 
 ## Selection and Editing
 
-The fluent selection API is the single home for mutation. Selection methods
-return a new `Content`; the original is never mutated.
+The fluent selection API is the single home for mutation: every method returns
+a new `Content`, so the original is never mutated.
 
 ### Select by id or kind
 
@@ -149,6 +154,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 +196,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",
@@ -185,6 +211,9 @@ content.replace_by_id("p1", {
 
 ## Text Extraction
 
+Pull the visible plain text out of a document — useful for search indexing,
+word counts, or previews.
+
 ```python
 from tiptap_python_utils import Content, text_slices, visible_text, word_count
 
@@ -197,6 +226,9 @@ slices = text_slices(content, context=True)
 
 ## Tasks
 
+Query task lists in a document — find every task item or check whether any are
+still open.
+
 ```python
 from tiptap_python_utils import Content, has_open_tasks, open_tasks
 
@@ -219,6 +251,9 @@ task.shared_id          # sharedId attr, if any
 
 ## Shared-Node Synchronization
 
+Keep copies of the same logical node (linked by `sharedId`) in sync — collect
+canonical bodies, then rewrite every matching node from them.
+
 `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
@@ -257,17 +292,6 @@ Related helpers on `Content`:
 - `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`
-(immutable AST with a registry of node classes; unknown kinds round-trip via
-`Unknown`) → `codec` (raw I/O in `raw.py`, hydration in `reader.py`, dump in
-`writer.py`) → `walk` & `tree` (traversal + path-based replacement on the
-immutable tree) → `select` (fluent `Selection` — the single home for mutation)
-→ `content` (public facade) → `text` / `tasks` / `shared` (user-facing
-workflows built on `Content`). All nodes are `@dataclass(frozen=True)`;
-mutations return new instances.
-
 ## Public API
 
 Common imports are available from the package root:
@@ -281,6 +305,7 @@ from tiptap_python_utils import (
     Text,
     has_open_tasks,
     kind,
+    new_node_id,
     new_shared_id,
     open_tasks,
     text_slices,
@@ -289,35 +314,21 @@ from tiptap_python_utils import (
 )
 ```
 
-## Stability
-
-The project is pre-1.0; minor versions may include breaking changes. See
-[CHANGELOG.md](CHANGELOG.md) for what changed and when.
-
-## Development
-
-```bash
-python -m venv .venv
-. .venv/bin/activate
-python -m pip install -e ".[dev]"
-pytest -q
-```
-
-Build and validate a release artifact:
-
-```bash
-python -m build
-python -m twine check dist/*
-```
-
 ## Contributing
 
 Issues and pull requests are welcome. Please read
-[CONTRIBUTING.md](CONTRIBUTING.md) for the local setup and release checklist,
-and open an issue at
+[CONTRIBUTING.md](CONTRIBUTING.md) for the local setup, architecture overview,
+and release checklist, and open an issue at
 [github.com/tugkanpilka/tiptap-python-utils/issues](https://github.com/tugkanpilka/tiptap-python-utils/issues)
-before larger changes so we can align on the approach.
+before opening a pull request so we can align on the approach.
 
 ## License
 
 MIT — see [LICENSE](LICENSE).
+
+## Stability
+
+The project is pre-1.0; minor versions may include breaking changes. See
+[CHANGELOG.md](CHANGELOG.md) for what changed and when.
+</content>
+</invoke>

{tiptap_python_utils-0.4.0.dist-info → tiptap_python_utils-0.6.0.dist-info}/RECORD

@@ -1,11 +1,13 @@
-tiptap_python_utils/__init__.py,sha256=J78QM5SdfIB3qEeZ0f0ejFJgE1lS8o6VJdCxD5_yCkc,1417
-tiptap_python_utils/content.py,sha256=NfTow1rPtTKcBkYTyPA50y0mjmlq57uXnXwFeKgKH_0,6522
+tiptap_python_utils/__init__.py,sha256=0YJx2Uj-7A2TEvWw-ajC8Jlv1wLCBH0pAy0NP8NWva8,1501
+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/task.py,sha256=x5LttsHEtHZL6oAzYfjLNUXsUWpuLmUU6N-qoV8J-xA,1831
 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=JV-pBYY_zO9uZ3XWQtjzrTcmhgisVFO2O-zscrUHhPA,294
@@ -17,7 +19,7 @@ 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=T89HaILztYmEJU_0rWeJYQuTc1uU0oCS1QuYQF_b-wg,2440
 tiptap_python_utils/shared/fingerprint.py,sha256=X0zrxbjM-ATUukXp5YUYBW9XzkeeYxP7szpHeFBsr_8,582
@@ -30,8 +32,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.4.0.dist-info/licenses/LICENSE,sha256=pIGeAFdiaTJBpJilmEbR8YQ5agrt7DqbGlTTrzqO6Qo,1089
-tiptap_python_utils-0.4.0.dist-info/METADATA,sha256=UOD9KXoyarycfxuiloO13KsRJvR8_hvYFtASYHMvP4I,10854
-tiptap_python_utils-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-tiptap_python_utils-0.4.0.dist-info/top_level.txt,sha256=t7g66MmK6WqTixs5_ZnXe4j-RvH9thuDRKvxk_8F0AQ,20
-tiptap_python_utils-0.4.0.dist-info/RECORD,,
+tiptap_python_utils-0.6.0.dist-info/licenses/LICENSE,sha256=pIGeAFdiaTJBpJilmEbR8YQ5agrt7DqbGlTTrzqO6Qo,1089
+tiptap_python_utils-0.6.0.dist-info/METADATA,sha256=UnRezBToej-6BT4lPGNwqT7OK6-P3l9omAwIdO2uMxc,11468
+tiptap_python_utils-0.6.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tiptap_python_utils-0.6.0.dist-info/top_level.txt,sha256=t7g66MmK6WqTixs5_ZnXe4j-RvH9thuDRKvxk_8F0AQ,20
+tiptap_python_utils-0.6.0.dist-info/RECORD,,