tiptap-python-utils 0.1.0__tar.gz

tiptap_python_utils-0.1.0/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/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include src/tiptap_python_utils/py.typed
+recursive-include tests *.py

tiptap_python_utils-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,126 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tiptap_python_utils"
+version = "0.1.0"
+description = "Python utilities for parsing, traversing, editing, and serializing TipTap JSON content."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+  { name = "tiptap_python_utils contributors" }
+]
+keywords = ["tiptap", "prosemirror", "json", "ast", "editor"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/tugkanpilka/tiptap-python-utils"
+Repository = "https://github.com/tugkanpilka/tiptap-python-utils"
+Issues = "https://github.com/tugkanpilka/tiptap-python-utils/issues"
+Changelog = "https://github.com/tugkanpilka/tiptap-python-utils/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8",
+  "twine>=5",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tiptap_python_utils = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+  "unit: unit tests",
+]

tiptap_python_utils-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tiptap_python_utils-0.1.0/src/tiptap_python_utils/__init__.py

@@ -0,0 +1,85 @@
+"""Public API for TipTap JSON utilities."""
+
+from .contract import key, kind
+from .content import Content
+from .edit import append_node, replace_node
+from .exceptions import TiptapValidationError
+from .model import (
+    Blockquote,
+    BulletList,
+    CodeBlock,
+    Doc,
+    Heading,
+    ListItem,
+    Node,
+    OrderedList,
+    Paragraph,
+    TableCell,
+    TaskItem,
+    TaskList,
+    Text,
+    Unknown,
+    registry,
+)
+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 .tasks import has_open_tasks, open_tasks, syncable_tasks
+from .text import NodeText, text_slices, visible_text, word_count
+from .walk import Ref, Walker
+
+EMPTY_DOCUMENT_CONTENT = '{"type":"doc","content":[]}'
+
+__all__ = [
+    "Blockquote",
+    "BulletList",
+    "CodeBlock",
+    "Content",
+    "Doc",
+    "EMPTY_DOCUMENT_CONTENT",
+    "Heading",
+    "ListItem",
+    "Node",
+    "NodeText",
+    "OrderedList",
+    "Paragraph",
+    "Ref",
+    "Selection",
+    "TableCell",
+    "TaskItem",
+    "TaskList",
+    "Text",
+    "TiptapValidationError",
+    "Unknown",
+    "Walker",
+    "append_node",
+    "content_id",
+    "fingerprint_shared",
+    "has_open_tasks",
+    "has_shared",
+    "is_parseable",
+    "key",
+    "kind",
+    "new_shared_id",
+    "node_id",
+    "open_tasks",
+    "registry",
+    "replace_node",
+    "shared_families",
+    "shared_id",
+    "stamp_shared",
+    "sync_shared",
+    "syncable_tasks",
+    "text_slices",
+    "tiptap_id",
+    "visible_text",
+    "word_count",
+]

tiptap_python_utils-0.1.0/src/tiptap_python_utils/codec/__init__.py

@@ -0,0 +1,29 @@
+"""Raw JSON codec exports."""
+
+from .json import (
+    dump,
+    dumps,
+    normalize_text,
+    parse_raw,
+    raw_node_id,
+    raw_text,
+    read_children,
+    read_doc,
+    read_node,
+    read_node_input,
+    require_object,
+)
+
+__all__ = [
+    "dump",
+    "dumps",
+    "normalize_text",
+    "parse_raw",
+    "raw_node_id",
+    "raw_text",
+    "read_children",
+    "read_doc",
+    "read_node",
+    "read_node_input",
+    "require_object",
+]

tiptap_python_utils-0.1.0/src/tiptap_python_utils/codec/json.py

@@ -0,0 +1,116 @@
+"""TipTap raw JSON codec."""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from typing import Any, Dict, Mapping, Optional
+
+from ..exceptions import TiptapValidationError
+from ..types import DocumentContent
+
+from ..contract import key, kind, policy
+from ..model import ContentTuple, Doc, Node, registry
+
+
+def parse_raw(raw: Optional[DocumentContent]) -> Optional[Dict[str, Any]]:
+    """Leniently parse a raw document payload."""
+    if isinstance(raw, str):
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            return None
+    else:
+        parsed = raw
+
+    return deepcopy(parsed) if isinstance(parsed, dict) else None
+
+
+def require_object(
+    content: str | Mapping[str, Any],
+    *,
+    label: str = "content",
+) -> Dict[str, Any]:
+    """Strictly parse a JSON object payload."""
+    if isinstance(content, str):
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError as exc:
+            raise TiptapValidationError(f"{label} is not valid JSON") from exc
+    else:
+        parsed = deepcopy(dict(content))
+
+    if not isinstance(parsed, dict):
+        raise TiptapValidationError(f"{label} must be a JSON object")
+    return parsed
+
+
+def read_doc(raw: Mapping[str, Any]) -> Doc | None:
+    """Read a raw TipTap document root."""
+    if raw.get(key.TYPE) != kind.DOC:
+        return None
+    parsed = read_node(raw)
+    return parsed if isinstance(parsed, Doc) else None
+
+
+def read_node(raw: Mapping[str, Any]) -> Node:
+    """Read a raw TipTap node by delegating to the registry."""
+    children = read_children(raw.get(key.CONTENT, []))
+    return registry.read(raw, children)
+
+
+def read_children(raw_children: Any) -> ContentTuple:
+    if not isinstance(raw_children, list):
+        return ()
+    return tuple(read_node(child) for child in raw_children if isinstance(child, dict))
+
+
+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):
+        return node_or_raw
+
+    parsed = require_object(node_or_raw, label=label)
+    node = read_doc(parsed) if parsed.get(key.TYPE) == kind.DOC else read_node(parsed)
+    if node is None:
+        raise TiptapValidationError(f"{label} must be a valid TipTap node")
+    return node
+
+
+def dump(node: Node) -> Dict[str, Any]:
+    return node.raw()
+
+
+def dumps(node: Node) -> str:
+    return json.dumps(dump(node))
+
+
+def raw_node_id(node: Mapping[str, Any]) -> str:
+    return policy.content_id(node.get(key.ATTRS, {}))
+
+
+def raw_text(node: Mapping[str, Any]) -> str:
+    return " ".join(_iter_text(node))
+
+
+def normalize_text(value: str) -> str:
+    return " ".join(value.split())
+
+
+def _iter_text(node: Mapping[str, Any]):
+    if not isinstance(node, dict):
+        return
+
+    if node.get(key.TYPE) == kind.TEXT:
+        text = str(node.get(key.TEXT, "")).strip()
+        if text:
+            yield text
+        return
+
+    content = node.get(key.CONTENT, [])
+    if not isinstance(content, list):
+        return
+
+    for child in content:
+        if isinstance(child, dict):
+            yield from _iter_text(child)