tiptap-python-utils 0.5.0__tar.gz → 0.6.0__tar.gz

{tiptap_python_utils-0.5.0/src/tiptap_python_utils.egg-info → tiptap_python_utils-0.6.0}/PKG-INFO

@@ -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 → tiptap_python_utils-0.6.0}/README.md

@@ -5,23 +5,10 @@
 [![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
 
@@ -43,8 +30,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` |
@@ -53,7 +56,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).
@@ -74,7 +78,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
@@ -85,8 +90,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
 
@@ -155,6 +160,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
 
@@ -167,6 +175,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
 
@@ -189,6 +200,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
@@ -227,17 +241,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:
@@ -260,35 +263,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 → tiptap_python_utils-0.6.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tiptap_python_utils"
-version = "0.5.0"
-description = "Python utilities for parsing, traversing, editing, and serializing TipTap JSON content."
+version = "0.6.0"
+description = "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+."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { file = "LICENSE" }

{tiptap_python_utils-0.5.0 → tiptap_python_utils-0.6.0}/src/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-0.6.0/src/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 → tiptap_python_utils-0.6.0/src/tiptap_python_utils.egg-info}/PKG-INFO

@@ -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 → tiptap_python_utils-0.6.0}/src/tiptap_python_utils.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/tiptap_python_utils/content.py
 src/tiptap_python_utils/exceptions.py
 src/tiptap_python_utils/identity.py
 src/tiptap_python_utils/py.typed
+src/tiptap_python_utils/task.py
 src/tiptap_python_utils/types.py
 src/tiptap_python_utils.egg-info/PKG-INFO
 src/tiptap_python_utils.egg-info/SOURCES.txt
@@ -48,4 +49,5 @@ tests/test_filter.py
 tests/test_generic_helpers.py
 tests/test_mutations.py
 tests/test_public_api.py
+tests/test_task_namespace.py
 tests/test_traverser.py

{tiptap_python_utils-0.5.0 → tiptap_python_utils-0.6.0}/tests/test_compat_imports.py

@@ -66,6 +66,7 @@ SUBPACKAGE_PUBLIC_NAMES: dict[str, frozenset[str]] = {
             "new_shared_id",
         }
     ),
+    "tiptap_python_utils.task": frozenset({"create_list", "is_item", "is_list"}),
     "tiptap_python_utils.tasks": frozenset(
         {"has_open_tasks", "open_tasks", "syncable_tasks"}
     ),

{tiptap_python_utils-0.5.0 → tiptap_python_utils-0.6.0}/tests/test_public_api.py

@@ -50,6 +50,7 @@ EXPECTED_PUBLIC_API = frozenset(
         "open_tasks",
         "registry",
         "syncable_tasks",
+        "task",
         "text_slices",
         "tiptap_id",
         "visible_text",

tiptap_python_utils-0.6.0/tests/test_task_namespace.py

@@ -0,0 +1,90 @@
+"""Unit tests for the pure raw-dict `task` namespace."""
+
+from __future__ import annotations
+
+from tiptap_python_utils import task
+
+
+# --- create_list -----------------------------------------------------------
+
+
+def test_create_list_wraps_items_in_task_list_block():
+    items = [{"type": "taskItem"}]
+    block = task.create_list(items)
+    assert block == {"type": "taskList", "content": items}
+
+
+def test_create_list_accepts_empty_list():
+    assert task.create_list([]) == {"type": "taskList", "content": []}
+
+
+def test_create_list_stores_items_by_reference_not_a_copy():
+    items = [{"type": "taskItem", "n": 1}]
+    block = task.create_list(items)
+    # Same object, not a copy.
+    assert block["content"] is items
+
+
+def test_create_list_reflects_later_mutations_of_original_list():
+    items = [{"type": "taskItem", "n": 1}]
+    block = task.create_list(items)
+    # Caller keeps appending to the original list after wrapping.
+    items.append({"type": "taskItem", "n": 2})
+    # The change is visible inside the block (by-reference contract).
+    assert block["content"] == [
+        {"type": "taskItem", "n": 1},
+        {"type": "taskItem", "n": 2},
+    ]
+    assert len(block["content"]) == 2
+
+
+# --- is_list ---------------------------------------------------------------
+
+
+def test_is_list_true_for_valid_task_list():
+    assert task.is_list({"type": "taskList", "content": []}) is True
+    assert task.is_list({"type": "taskList", "content": [{"type": "taskItem"}]}) is True
+
+
+def test_is_list_false_for_wrong_type():
+    assert task.is_list({"type": "bulletList", "content": []}) is False
+
+
+def test_is_list_false_when_content_not_a_list():
+    assert task.is_list({"type": "taskList", "content": {}}) is False
+    assert task.is_list({"type": "taskList", "content": "x"}) is False
+
+
+def test_is_list_false_on_missing_keys_without_raising():
+    assert task.is_list({}) is False
+    assert task.is_list({"type": "taskList"}) is False  # no content key
+    assert task.is_list({"content": []}) is False  # no type key
+
+
+def test_is_list_false_for_non_dict():
+    assert task.is_list(None) is False
+    assert task.is_list([]) is False
+    assert task.is_list("taskList") is False
+
+
+# --- is_item ---------------------------------------------------------------
+
+
+def test_is_item_true_for_task_item():
+    assert task.is_item({"type": "taskItem"}) is True
+    assert task.is_item({"type": "taskItem", "attrs": {"checked": True}}) is True
+
+
+def test_is_item_false_for_wrong_type():
+    assert task.is_item({"type": "taskList"}) is False
+    assert task.is_item({"type": "listItem"}) is False
+
+
+def test_is_item_false_on_missing_keys_without_raising():
+    assert task.is_item({}) is False
+
+
+def test_is_item_false_for_non_dict():
+    assert task.is_item(None) is False
+    assert task.is_item([]) is False
+    assert task.is_item("taskItem") is False