wagtail-write-api 0.2.2__tar.gz → 0.3.0__tar.gz

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wagtail-write-api
-Version: 0.2.2
+Version: 0.3.0
 Summary: A read/write REST API for Wagtail CMS
 Project-URL: Homepage, https://tomdyson.github.io/wagtail-write-api/
 Project-URL: Repository, https://github.com/tomdyson/wagtail-write-api

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/docs/api/pages.md

@@ -34,8 +34,8 @@ GET /pages/
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `type` | string | Filter by page type, e.g. `blog.BlogPage` |
-| `parent` | int | Direct children of this page ID |
-| `descendant_of` | int | All descendants of this page ID |
+| `parent` | int or string | Direct children of this page ID or URL path (e.g. `5` or `/blog/`) |
+| `descendant_of` | int or string | All descendants of this page ID or URL path |
 | `status` | string | `draft`, `live`, or `live+draft` |
 | `slug` | string | Exact slug match (may return multiple if slug exists under different parents) |
 | `path` | string | Exact URL path match, e.g. `/blog/my-post/` (always 0 or 1 result) |

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/docs/guides/rich-text.md

@@ -92,6 +92,12 @@ WAGTAIL_WRITE_API = {
 !!! tip "For CMS editors"
     If your client needs to read content, edit it, and write it back, use `"wagtail"` format. This preserves the internal link references (page IDs) through the round trip. With `"html"` format, internal links are expanded to URL paths, which can't be losslessly converted back.
 
+## StreamField blocks sent to a RichTextField
+
+If a client accidentally sends StreamField-style blocks (a list of `{"type": ..., "value": ...}` dicts) to a `RichTextField`, the API extracts the HTML content from the blocks rather than storing a stringified list. Paragraph and text block values are concatenated, and heading blocks are converted to HTML heading tags.
+
+This is a convenience fallback — for best results, send one of the documented input formats above.
+
 ## Rich text in StreamField
 
 `RichTextBlock` values in StreamField accept the same input format:

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/example/testapp/management/commands/seed_demo.py

@@ -1,10 +1,13 @@
+import io
 import json
 import uuid
 
 from django.contrib.auth.models import Group, Permission, User
+from django.core.files.images import ImageFile
 from django.core.management.base import BaseCommand
-from wagtail_write_api.models import ApiToken
+from wagtail.images.models import Image
 from wagtail.models import GroupPagePermission, Page, Site
+from wagtail_write_api.models import ApiToken
 
 from testapp.models import (
     BlogIndexPage,
@@ -124,6 +127,19 @@ class Command(BaseCommand):
             )
         moderator.groups.add(mods_group)
 
+        # Images
+        Image.objects.all().delete()
+        image_titles = ["Hero background", "Blog header", "Team photo"]
+        for i, title in enumerate(image_titles, 1):
+            img = self._create_placeholder_image(100 * i, 80 * i)
+            Image.objects.create(
+                title=title,
+                file=ImageFile(img, name=f"demo-{i}.png"),
+                uploaded_by_user=admin,
+            )
+
+        self.stdout.write(f"Created {len(image_titles)} images")
+
         # Print tokens
         self.stdout.write("\n--- API Tokens ---")
         for user in [admin, editor, moderator, reviewer]:
@@ -133,6 +149,17 @@ class Command(BaseCommand):
         self.stdout.write(f"\nCreated {Page.objects.count()} pages")
         self.stdout.write(self.style.SUCCESS("Done!"))
 
+    @staticmethod
+    def _create_placeholder_image(width, height):
+        """Create a minimal solid-colour PNG in memory."""
+        from PIL import Image as PILImage
+
+        img = PILImage.new("RGB", (width, height), color=(200, 200, 200))
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        buf.seek(0)
+        return buf
+
     def _create_user(self, username, is_superuser=False):
         user, created = User.objects.get_or_create(
             username=username,

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wagtail-write-api"
-version = "0.2.2"
+version = "0.3.0"
 description = "A read/write REST API for Wagtail CMS"
 readme = "README.md"
 license = "BSD-3-Clause"

wagtail_write_api-0.3.0/src/wagtail_write_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/src/wagtail_write_api/converters/rich_text.py

@@ -14,6 +14,9 @@ def convert_rich_text_input(value) -> str:
     if isinstance(value, str):
         return value
 
+    if isinstance(value, list):
+        return _blocks_to_html(value)
+
     if not isinstance(value, dict):
         return str(value)
 
@@ -54,3 +57,24 @@ def markdown_to_wagtail(md_text: str) -> str:
     # The wagtail links are already in the output as <a linktype="..." id="...">
     # because we replaced them before markdown processing
     return html
+
+
+def _blocks_to_html(blocks: list) -> str:
+    """Extract HTML from a list of StreamField-style blocks.
+
+    Handles the case where a client sends block data to a RichTextField —
+    we pull out the text content rather than storing a stringified list.
+    """
+    parts = []
+    for block in blocks:
+        if not isinstance(block, dict):
+            continue
+        value = block.get("value", "")
+        block_type = block.get("type", "")
+        if block_type == "heading" and isinstance(value, dict):
+            size = value.get("size", "h2")
+            text = value.get("text", "")
+            parts.append(f"<{size}>{text}</{size}>")
+        elif isinstance(value, str):
+            parts.append(value)
+    return "".join(parts)

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/src/wagtail_write_api/endpoints/pages.py

@@ -103,6 +103,7 @@ def list_pages(
                     "live": page.live,
                     "has_unpublished_changes": page.has_unpublished_changes,
                     "parent_id": page.get_parent().id if page.get_parent() else None,
+                    "url_path": _get_url_path(page),
                 },
             }
         )
@@ -459,6 +460,21 @@ def _resolve_page_by_path(path: str):
         return None
 
 
+def _get_url_path(page):
+    """Return the site-relative URL path for a page (e.g. '/blog/my-post/')."""
+    from wagtail.models import Site
+
+    site = Site.objects.filter(is_default_site=True).first()
+    if not site or not page.url_path:
+        return None
+
+    root_path = site.root_page.url_path.rstrip("/")
+    url_path = page.url_path
+    if url_path.startswith(root_path):
+        url_path = url_path[len(root_path):]
+    return url_path or "/"
+
+
 def _apply_fields(page, body, model_class):
     """Apply request body fields to a page instance."""
     from modelcluster.fields import ParentalKey
@@ -541,6 +557,7 @@ def _serialize_page(source, page, type_str, user):
         "last_published_at": (
             page.last_published_at.isoformat() if page.last_published_at else None
         ),
+        "url_path": _get_url_path(page),
         "parent_id": parent.id if parent else None,
         "parent_type": (
             f"{parent_specific._meta.app_label}.{parent_specific.__class__.__name__}"

{wagtail_write_api-0.2.2 → wagtail_write_api-0.3.0}/src/wagtail_write_api/endpoints/schema_discovery.py

@@ -50,6 +50,7 @@ def get_page_type_schema(request, type_str: str):
 
     model_class = _resolve_model(type_str)
     streamfield_meta = _get_streamfield_meta(model_class) if model_class else {}
+    richtext_fields = _get_richtext_fields(model_class) if model_class else []
 
     return {
         "type": type_str,
@@ -57,6 +58,7 @@ def get_page_type_schema(request, type_str: str):
         "patch_schema": patch_schema.model_json_schema(),
         "read_schema": read_schema.model_json_schema(),
         "streamfield_blocks": streamfield_meta,
+        "richtext_fields": richtext_fields,
     }
 
 
@@ -70,6 +72,17 @@ def _resolve_model(type_str):
         return None
 
 
+def _get_richtext_fields(model_class):
+    """Return a list of field names that are RichTextFields."""
+    from wagtail.fields import RichTextField
+
+    return [
+        field.name
+        for field in model_class._meta.get_fields()
+        if isinstance(field, RichTextField)
+    ]
+
+
 def _get_streamfield_meta(model_class):
     """Introspect StreamField definitions and return block type schemas."""
     from wagtail.fields import StreamField

wagtail_write_api-0.3.0/tests/test_pages_read.py

@@ -0,0 +1,247 @@
+import pytest
+from django.test import Client, TestCase
+
+from testapp.models import BlogIndexPage, BlogPage, SimplePage
+from wagtail.models import Page, Site
+from django.contrib.auth.models import User
+from wagtail_write_api.models import ApiToken
+
+
+class _PageTreeMixin:
+    """Shared setUpTestData for read-only page tests.
+
+    Django's setUpTestData creates data once per class and wraps each test
+    in a savepoint, so the page tree is built once (~0.5 s) rather than
+    once per test method.
+    """
+
+    @classmethod
+    def setUpTestData(cls):
+        cls.admin = User.objects.create_superuser("admin", "admin@test.com", "pw")
+        token, _ = ApiToken.objects.get_or_create(user=cls.admin)
+        cls.auth = {"HTTP_AUTHORIZATION": f"Bearer {token.key}"}
+
+        root = Page.objects.filter(depth=1).first()
+        cls.home = root.add_child(title="Home", slug="home-test")
+        Site.objects.update_or_create(
+            is_default_site=True,
+            defaults={"hostname": "localhost", "root_page": cls.home},
+        )
+
+        cls.simple = cls.home.add_child(
+            instance=SimplePage(title="Simple", slug="simple", body="Hello")
+        )
+        cls.simple.save_revision()
+
+        cls.blog_index = cls.home.add_child(
+            instance=BlogIndexPage(title="Blog", slug="blog", intro="Blog intro")
+        )
+        cls.blog_index.save_revision()
+
+        cls.blog1 = cls.blog_index.add_child(
+            instance=BlogPage(title="First Post", slug="first-post", published_date="2026-01-01")
+        )
+        cls.blog1.save_revision()
+        cls.blog1.get_latest_revision().publish()
+
+        cls.blog2 = cls.blog_index.add_child(
+            instance=BlogPage(title="Draft Post", slug="draft-post", published_date="2026-02-01")
+        )
+        cls.blog2.save_revision()
+
+
+class TestListPages(_PageTreeMixin, TestCase):
+    def test_list_returns_items(self):
+        response = self.client.get("/api/write/v1/pages/", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert "items" in data
+        assert "meta" in data
+        assert data["meta"]["total_count"] > 0
+
+    def test_list_requires_auth(self):
+        response = self.client.get("/api/write/v1/pages/")
+        assert response.status_code == 401
+
+    def test_filter_by_type(self):
+        response = self.client.get("/api/write/v1/pages/?type=testapp.BlogPage", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        for item in data["items"]:
+            assert item["meta"]["type"] == "testapp.BlogPage"
+
+    def test_filter_by_parent(self):
+        parent_id = self.blog_index.id
+        response = self.client.get(f"/api/write/v1/pages/?parent={parent_id}", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 2
+
+    def test_filter_by_parent_path(self):
+        response = self.client.get("/api/write/v1/pages/?parent=/blog/", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 2
+
+    def test_filter_by_parent_invalid_returns_empty(self):
+        response = self.client.get("/api/write/v1/pages/?parent=/nonexistent/", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 0
+
+    def test_filter_by_status_live(self):
+        response = self.client.get("/api/write/v1/pages/?status=live", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        for item in data["items"]:
+            assert item["meta"]["live"] is True
+
+    def test_filter_by_status_draft(self):
+        response = self.client.get("/api/write/v1/pages/?status=draft", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        for item in data["items"]:
+            assert item["meta"]["live"] is False
+
+    def test_pagination(self):
+        response = self.client.get("/api/write/v1/pages/?offset=0&limit=1", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 1
+        assert data["meta"]["total_count"] > 1
+
+
+class TestDetailPage(_PageTreeMixin, TestCase):
+    def test_detail_returns_page(self):
+        page_id = self.blog1.id
+        response = self.client.get(f"/api/write/v1/pages/{page_id}/", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert data["id"] == page_id
+        assert data["title"] == "First Post"
+
+    def test_detail_includes_meta(self):
+        page_id = self.blog1.id
+        response = self.client.get(f"/api/write/v1/pages/{page_id}/", **self.auth)
+        data = response.json()
+        meta = data["meta"]
+        assert "type" in meta
+        assert "live" in meta
+        assert "has_unpublished_changes" in meta
+        assert "parent_id" in meta
+        assert "user_permissions" in meta
+
+    def test_detail_404_for_nonexistent(self):
+        response = self.client.get("/api/write/v1/pages/99999/", **self.auth)
+        assert response.status_code == 404
+
+    def test_detail_includes_type_specific_fields(self):
+        page_id = self.blog1.id
+        response = self.client.get(f"/api/write/v1/pages/{page_id}/", **self.auth)
+        data = response.json()
+        assert "published_date" in data
+
+
+class TestDetailPageDrafts(_PageTreeMixin, TestCase):
+    """Draft-aware reads — these mutate the page tree so they get their own class."""
+
+    def test_detail_returns_draft_content_by_default(self):
+        """When a page has unpublished changes, detail returns the draft."""
+        self.blog1.title = "Updated Title (draft)"
+        self.blog1.save_revision()
+
+        response = self.client.get(f"/api/write/v1/pages/{self.blog1.id}/", **self.auth)
+        data = response.json()
+        assert data["title"] == "Updated Title (draft)"
+
+    def test_detail_with_version_live(self):
+        """?version=live returns the published content, not the draft DB row."""
+        self.blog1.refresh_from_db()
+        self.blog1.title = "Updated Title (draft)"
+        self.blog1.save()
+        self.blog1.save_revision()
+
+        response = self.client.get(
+            f"/api/write/v1/pages/{self.blog1.id}/?version=live", **self.auth
+        )
+        data = response.json()
+        assert data["title"] == "First Post"
+
+
+class TestUrlPath(_PageTreeMixin, TestCase):
+    def test_list_includes_url_path(self):
+        response = self.client.get("/api/write/v1/pages/?slug=first-post", **self.auth)
+        data = response.json()
+        item = data["items"][0]
+        assert item["meta"]["url_path"] == "/blog/first-post/"
+
+    def test_list_root_page_url_path(self):
+        """The site root page should have url_path '/'."""
+        home_id = self.home.id
+        response = self.client.get(f"/api/write/v1/pages/{home_id}/", **self.auth)
+        data = response.json()
+        assert data["meta"]["url_path"] == "/"
+
+    def test_detail_includes_url_path(self):
+        page_id = self.blog1.id
+        response = self.client.get(f"/api/write/v1/pages/{page_id}/", **self.auth)
+        data = response.json()
+        assert data["meta"]["url_path"] == "/blog/first-post/"
+
+    def test_detail_simple_page_url_path(self):
+        page_id = self.simple.id
+        response = self.client.get(f"/api/write/v1/pages/{page_id}/", **self.auth)
+        data = response.json()
+        assert data["meta"]["url_path"] == "/simple/"
+
+
+class TestFilterBySlug(_PageTreeMixin, TestCase):
+    def test_filter_by_slug(self):
+        response = self.client.get("/api/write/v1/pages/?slug=first-post", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 1
+        assert data["items"][0]["slug"] == "first-post"
+
+    def test_filter_by_slug_no_match(self):
+        response = self.client.get("/api/write/v1/pages/?slug=nonexistent-slug", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 0
+
+    def test_filter_by_slug_combined_with_type(self):
+        response = self.client.get(
+            "/api/write/v1/pages/?slug=first-post&type=testapp.BlogPage", **self.auth
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 1
+        assert data["items"][0]["meta"]["type"] == "testapp.BlogPage"
+
+
+class TestFilterByPath(_PageTreeMixin, TestCase):
+    def test_filter_by_path(self):
+        response = self.client.get("/api/write/v1/pages/?path=/blog/first-post/", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 1
+        assert data["items"][0]["slug"] == "first-post"
+
+    def test_filter_by_path_no_trailing_slash(self):
+        response = self.client.get("/api/write/v1/pages/?path=/blog/first-post", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 1
+
+    def test_filter_by_path_no_match(self):
+        response = self.client.get("/api/write/v1/pages/?path=/nonexistent/path/", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 0
+
+    def test_filter_by_path_root_level(self):
+        response = self.client.get("/api/write/v1/pages/?path=/simple/", **self.auth)
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 1
+        assert data["items"][0]["slug"] == "simple"