tiptap-python-utils 0.5.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
@@ -65,6 +66,7 @@ __all__ = [
     "open_tasks",
     "registry",
     "syncable_tasks",
+    "task",
     "text_slices",
     "tiptap_id",
     "visible_text",

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.5.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.5.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
 
@@ -206,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
 
@@ -218,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
 
@@ -240,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
@@ -278,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:
@@ -311,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.5.0.dist-info → tiptap_python_utils-0.6.0.dist-info}/RECORD

@@ -1,8 +1,9 @@
-tiptap_python_utils/__init__.py,sha256=OBr4gCjfFWNe8MLv_JDb6_-_8EYRebbCiuAWTkEZIEI,1470
+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=kaqQ9OHJg_S0hwLFGS55_Mdhyr2wt9BRMrdYfhIKdHI,510
 tiptap_python_utils/codec/raw.py,sha256=glQWotPxzOFvPkg3nBBk3GbcM03Cj2yRclG62ckb1k0,2082
@@ -31,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.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,,
+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,,