tiptap-python-utils 0.1.0__py3-none-any.whl

tiptap_python_utils/text/extract.py

@@ -0,0 +1,113 @@
+"""Visible text extraction for TipTap content."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Iterator, List, Optional, Tuple
+
+from ..content import Content
+from ..contract import kind
+from ..model import CodeBlock, Heading, Node, Paragraph, TaskItem
+
+
+@dataclass(frozen=True)
+class NodeText:
+    node_id: str
+    text: str
+    html_tag: str = "p"
+    context: Optional[str] = None
+    node_type: Optional[str] = None
+
+
+def visible_text(content: Content) -> str:
+    return content.text
+
+
+def word_count(content: Content) -> int:
+    return content.word_count()
+
+
+def text_slices(content: Content, *, context: bool = False) -> List[NodeText]:
+    nodes = _content_nodes(content)
+    if context:
+        return list(_apply_heading_context(nodes))
+    return list(nodes)
+
+
+def _content_nodes(content: Content) -> Iterator[NodeText]:
+    if content.root is None:
+        return
+    for ref in content.refs(parseable=True):
+        node = ref.node
+        node_id = _node_id(node)
+        if not node_id or not isinstance(node, (Paragraph, Heading, TaskItem, CodeBlock)):
+            continue
+        yield NodeText(
+            node_id=node_id,
+            text=node.text,
+            html_tag=_tag(node),
+            node_type=node.kind,
+        )
+
+
+def _node_id(node: Node) -> str:
+    if isinstance(node, TaskItem):
+        return node.task_item_id
+    return node.id
+
+
+def _tag(node: Node) -> str:
+    if isinstance(node, Heading):
+        return f"h{node.level}"
+    if node.kind == kind.TASK_ITEM:
+        return "li"
+    if node.kind == kind.CODE_BLOCK:
+        return "code"
+    return "p"
+
+
+def _apply_heading_context(nodes: Iterable[NodeText]) -> Iterator[NodeText]:
+    context_stack: List[Tuple[int, str]] = []
+
+    for node in nodes:
+        if not node.text.strip():
+            context_stack.clear()
+            yield node
+            continue
+
+        if _is_heading(node.html_tag):
+            level = int(node.html_tag[1])
+            parent_context = _context_string(context_stack)
+            _push_heading(context_stack, level, node.text)
+            yield NodeText(
+                node_id=node.node_id,
+                text=node.text,
+                html_tag=node.html_tag,
+                context=parent_context,
+                node_type=node.node_type,
+            )
+            continue
+
+        yield NodeText(
+            node_id=node.node_id,
+            text=node.text,
+            html_tag=node.html_tag,
+            context=_context_string(context_stack),
+            node_type=node.node_type,
+        )
+
+
+def _is_heading(html_tag: str) -> bool:
+    return len(html_tag) == 2 and html_tag[0] == "h" and html_tag[1].isdigit()
+
+
+def _push_heading(stack: List[Tuple[int, str]], level: int, text: str) -> None:
+    while stack and stack[-1][0] >= level:
+        stack.pop()
+    stack.append((level, text))
+
+
+def _context_string(stack: List[Tuple[int, str]]) -> Optional[str]:
+    if not stack:
+        return None
+    return " > ".join(text for _, text in stack)

tiptap_python_utils/tree/__init__.py

@@ -0,0 +1,5 @@
+"""Tree cursor helpers for typed TipTap nodes."""
+
+from .path import node_at_path, replace_at_path
+
+__all__ = ["node_at_path", "replace_at_path"]

tiptap_python_utils/tree/path.py

@@ -0,0 +1,36 @@
+"""Immutable tree path operations for typed TipTap nodes."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Tuple
+
+from ..exceptions import TiptapValidationError
+
+from ..contract import key
+from ..model import Node
+
+
+def node_at_path(node: Node, path: Tuple[int, ...]) -> Node:
+    current = node
+    for index in path:
+        try:
+            current = current.content[index]
+        except IndexError as exc:
+            raise TiptapValidationError(
+                "TipTap selection path is no longer valid"
+            ) from exc
+    return current
+
+
+def replace_at_path(node: Node, path: Tuple[int, ...], replacement_node: Node) -> Node:
+    if not path:
+        return replacement_node
+
+    index = path[0]
+    content = list(node.content)
+    if index >= len(content):
+        raise TiptapValidationError("TipTap selection path is no longer valid")
+
+    content[index] = replace_at_path(content[index], path[1:], replacement_node)
+    return replace(node, content=tuple(content), present=node.present | {key.CONTENT})

tiptap_python_utils/types.py

@@ -0,0 +1,7 @@
+"""Shared type aliases."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Union
+
+DocumentContent = Union[str, Mapping[str, Any]]

tiptap_python_utils/walk/__init__.py

@@ -0,0 +1,5 @@
+"""Traversal exports."""
+
+from .traversal import Ref, Walker, selection_id
+
+__all__ = ["Ref", "Walker", "selection_id"]

tiptap_python_utils/walk/traversal.py

@@ -0,0 +1,88 @@
+"""Depth-first TipTap traversal."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterator, Optional, Tuple, Type, TypeVar
+
+from ..contract import kind, policy
+from ..model import CodeBlock, Heading, ListItem, Node, Paragraph, TaskItem
+
+NodeT = TypeVar("NodeT", bound=Node)
+
+
+@dataclass(frozen=True)
+class Ref:
+    node: Node
+    path: Tuple[int, ...]
+    parent_kind: str
+
+    @property
+    def node_id(self) -> Optional[str]:
+        return selection_id(self.node)
+
+    @property
+    def parseable(self) -> bool:
+        return not self.path or policy.is_parseable(self.node.kind, self.parent_kind)
+
+
+class Walker:
+    """Depth-first traversal for typed TipTap content."""
+
+    def __init__(self, root_or_content: Any) -> None:
+        self._root = getattr(root_or_content, "root", root_or_content)
+
+    def walk(self) -> Iterator[Node]:
+        if self._root is None:
+            return
+        yield from _walk(self._root)
+
+    def of_type(self, node_class: Type[NodeT]) -> list[NodeT]:
+        return [node for node in self.walk() if isinstance(node, node_class)]
+
+    def refs(self, *, parseable: bool = False) -> Iterator[Ref]:
+        if self._root is None:
+            return
+        yield from _refs(
+            self._root,
+            path=(),
+            parent_kind=kind.DOC,
+            parseable=parseable,
+        )
+
+
+def selection_id(node: Node) -> Optional[str]:
+    attrs_id = policy.node_id(getattr(node, "attrs", {}))
+    if attrs_id:
+        return attrs_id
+    if isinstance(node, TaskItem):
+        return node.local_task_item_id or node.task_item_id or None
+    if isinstance(node, (Paragraph, Heading, ListItem, CodeBlock)):
+        return node.id or None
+    return None
+
+
+def _walk(node: Node) -> Iterator[Node]:
+    yield node
+    for child in node.content:
+        yield from _walk(child)
+
+
+def _refs(
+    node: Node,
+    *,
+    path: tuple[int, ...],
+    parent_kind: str,
+    parseable: bool,
+) -> Iterator[Ref]:
+    ref = Ref(node=node, path=path, parent_kind=parent_kind)
+    if not parseable or ref.parseable:
+        yield ref
+
+    for index, child in enumerate(node.content):
+        yield from _refs(
+            child,
+            path=path + (index,),
+            parent_kind=node.kind,
+            parseable=parseable,
+        )

tiptap_python_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: tiptap_python_utils
+Version: 0.1.0
+Summary: Python utilities for parsing, traversing, editing, and serializing TipTap JSON content.
+Author: tiptap_python_utils contributors
+License: MIT License
+        
+        Copyright (c) 2026 tiptap_python_utils contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/tugkanpilka/tiptap-python-utils
+Project-URL: Repository, https://github.com/tugkanpilka/tiptap-python-utils
+Project-URL: Issues, https://github.com/tugkanpilka/tiptap-python-utils/issues
+Project-URL: Changelog, https://github.com/tugkanpilka/tiptap-python-utils/blob/main/CHANGELOG.md
+Keywords: tiptap,prosemirror,json,ast,editor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# tiptap_python_utils
+
+Python utilities for TipTap JSON content.
+
+`tiptap_python_utils` parses TipTap documents into typed 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.
+
+The package has no runtime dependencies.
+
+## Install
+
+```bash
+pip install tiptap_python_utils
+```
+
+## Quick Start
+
+```python
+from tiptap_python_utils import Content, Paragraph, Text, kind
+
+raw = {
+    "type": "doc",
+    "content": [
+        {
+            "type": "paragraph",
+            "attrs": {"id": "p1"},
+            "content": [{"type": "text", "text": "Old"}],
+        }
+    ],
+}
+
+updated = Content.require(raw).where_id("p1").text("New").dump()
+```
+
+## Typed Nodes
+
+Build typed nodes directly and serialize them back to TipTap-compatible JSON:
+
+```python
+node = Paragraph(id="p1", content=(Text(value="Hello"),))
+doc = Content.wrap(node.raw())
+```
+
+Unknown/custom node types are preserved as `Unknown` nodes and round-trip without
+dropping extra fields.
+
+## Selection And Editing
+
+Select nodes by id or TipTap kind:
+
+```python
+updated = Content.require(raw).of(kind.PARAGRAPH).attr("color", "blue").dump()
+```
+
+Selection methods return updated immutable content:
+
+```python
+updated = (
+    Content.require(raw)
+    .where_id("p1")
+    .text("Updated")
+    .attr("data-state", "reviewed")
+    .dump()
+)
+```
+
+## Text Extraction
+
+Extract visible text or contextual slices:
+
+```python
+from tiptap_python_utils import Content, text_slices, visible_text, word_count
+
+content = Content.require(raw)
+
+plain_text = visible_text(content)
+count = word_count(content)
+slices = text_slices(content, context=True)
+```
+
+## Tasks
+
+```python
+from tiptap_python_utils import Content, has_open_tasks, open_tasks
+
+content = Content.require(raw)
+
+pending = has_open_tasks(content)
+items = open_tasks(content)
+```
+
+## Public API
+
+Common imports are available from the package root:
+
+```python
+from tiptap_python_utils import (
+    Content,
+    Paragraph,
+    TaskItem,
+    Text,
+    append_node,
+    has_open_tasks,
+    kind,
+    replace_node,
+    shared_families,
+    sync_shared,
+    text_slices,
+)
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+Build and check a release artifact:
+
+```bash
+python -m build
+python -m twine check dist/*
+```

tiptap_python_utils-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+tiptap_python_utils/__init__.py,sha256=3Zz8DTxEaQxeLqhLVpwXhOaVV1SAKq_2JgwSXbBKySA,1673
+tiptap_python_utils/content.py,sha256=KP-M4lDt7lBsQJTI137pnPmb2fthi2YBD2BgmHfvq1k,4937
+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
+tiptap_python_utils/codec/__init__.py,sha256=Ip9rhIR2-1R_See3kU3xpATiEgSpz5eZfbQK3OrJjrM,442
+tiptap_python_utils/codec/json.py,sha256=RIxKbG88vGYS57IylJqwNjpNjOLrb8mmkEKcNTA69IY,3176
+tiptap_python_utils/contract/__init__.py,sha256=gJMHPqIl6vkcXAOKNKtZIbs8aQs1abqykEpc5i3abQY,115
+tiptap_python_utils/contract/key.py,sha256=6T4Y-26hESduXmLaNOOpbZ-zTYkHgABvDCHjL6b2VDM,260
+tiptap_python_utils/contract/kind.py,sha256=I-vkJ9mskw07qjbIR5uC1s3z0AvtwA2y3qovkzTsY2Q,297
+tiptap_python_utils/contract/policy.py,sha256=AeJfLv07JWqhuJMakUgz1Y-bMpac28h426bj17hKvwk,1193
+tiptap_python_utils/edit/__init__.py,sha256=8d8K5_v2ka8TnvNghwuyTwBb99OJTIHNyx_i8uHg3cw,251
+tiptap_python_utils/edit/commands.py,sha256=rifp_43vB_ICyI4McYeBmpY3xoY5sB_RFxNOzFbwQAA,5545
+tiptap_python_utils/model/__init__.py,sha256=3m5vTlc2cZTU0atV6xWFvU38bxVjI-xYOR3bQtqEyTM,10320
+tiptap_python_utils/select/__init__.py,sha256=lFavos0E3w2D_keUPDa5xkWhIjkQiee7yNK7X-G-U6o,88
+tiptap_python_utils/select/selection.py,sha256=DWfdGLhMF8HDrBJ1Jiv8XVnPXuexzce7JhzAflynTdw,2409
+tiptap_python_utils/shared/__init__.py,sha256=DL09HcsabBxFXBcvnd7hH3FLT3sR9EZkjurPPQM8U5Q,402
+tiptap_python_utils/shared/service.py,sha256=sWIL32sOGZo8ydzzTGghRTh56-EQGlrZgmEPaxPcIFk,4679
+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
+tiptap_python_utils/text/extract.py,sha256=aluDO3Hp0M7cyLoTtpZAeWHECF5Gh8ApZFdgs_se1aA,3046
+tiptap_python_utils/tree/__init__.py,sha256=YzlXRkQrlRGYmkWbpZ8mutZOmK4BzmiZaBqUtFv8c8c,146
+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.1.0.dist-info/licenses/LICENSE,sha256=pIGeAFdiaTJBpJilmEbR8YQ5agrt7DqbGlTTrzqO6Qo,1089
+tiptap_python_utils-0.1.0.dist-info/METADATA,sha256=JNf4QQALy1Cw400CNm65_NiXfhEFcqyqgUHAIMd1I9k,4895
+tiptap_python_utils-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tiptap_python_utils-0.1.0.dist-info/top_level.txt,sha256=t7g66MmK6WqTixs5_ZnXe4j-RvH9thuDRKvxk_8F0AQ,20
+tiptap_python_utils-0.1.0.dist-info/RECORD,,

tiptap_python_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tiptap_python_utils-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tiptap_python_utils contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiptap_python_utils-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tiptap_python_utils