picata 0.0.11__py3-none-any.whl → 0.0.12__py3-none-any.whl

picata/helpers/__init__.py

@@ -1,4 +1,5 @@
 """Generic helper-functions."""
+
 # NB: Django's meta-class shenanigans over-complicate type hinting when QuerySets get involved.
 # pyright: reportAttributeAccessIssue=false
 

picata/helpers/wagtail.py

@@ -1,24 +1,25 @@
 """Generic helper-functions."""
+
 # NB: Django's meta-class shenanigans over-complicate type hinting when QuerySets get involved.
 # pyright: reportAttributeAccessIssue=false
 
-from typing import cast
+from typing import Any, cast
 
-from django.http import HttpRequest
 from wagtail.models import Page
 from wagtail.query import PageQuerySet
 
 from picata.models import TaggedPage
+from picata.typing import UserOrNot
 
 from . import get_models_of_type
 
 TAGGED_PAGE_TYPES = get_models_of_type(TaggedPage)
 
 
-def visible_pages_qs(request: HttpRequest) -> PageQuerySet:
+def visible_pages_qs(user: UserOrNot = None, page_qs: PageQuerySet | None = None) -> PageQuerySet:
     """Return a QuerySet of all pages derived from `Page` visible to the user."""
-    pages = cast(PageQuerySet, Page.objects.all())
-    if not request.user.is_authenticated:
+    pages = page_qs if page_qs else cast(PageQuerySet, Page.objects.all())
+    if not user or not user.is_authenticated:
         pages = pages.live()
     return pages
 
@@ -53,9 +54,9 @@ def filter_pages_by_type(pages: list[Page], page_type_slugs: set[str]) -> list[P
     return filtered_pages
 
 
-def page_preview_data(page: Page, request: HttpRequest | None) -> dict[str, str]:
+def page_preview_data(page: Page, user: UserOrNot) -> dict[str, Any]:
     """Return a dictionary of available publication and preview data for a page."""
-    page_data = getattr(page, "preview_data", {}).copy()
+    page_data = page.get_preview_fields(user) if hasattr(page, "get_preview_fields") else {}
     if hasattr(page, "get_publication_data"):
-        page_data.update(page.get_publication_data(request))
+        page_data.update(page.get_publication_data())
     return page_data

picata/migrations/0002_postseries.py

@@ -0,0 +1,27 @@
+# Generated by Django 5.1.5 on 2025-02-05 01:16
+
+import django.db.models.deletion
+import wagtail.fields
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('picata', '0001_initial'),
+        ('wagtailcore', '0094_alter_page_locale'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='PostSeries',
+            fields=[
+                ('page_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='wagtailcore.page')),
+                ('introduction', wagtail.fields.StreamField([('rich_text', 0), ('image', 1)], blank=True, block_lookup={0: ('wagtail.blocks.RichTextBlock', (), {}), 1: ('picata.blocks.WrappedImageChooserBlock', (), {})})),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('wagtailcore.page',),
+        ),
+    ]

picata/migrations/0003_postseries_summary_alter_postseries_introduction.py

@@ -0,0 +1,24 @@
+# Generated by Django 5.1.5 on 2025-02-11 02:39
+
+import wagtail.fields
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('picata', '0002_postseries'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='postseries',
+            name='summary',
+            field=wagtail.fields.RichTextField(blank=True, help_text='A summary to be displayed in previews.'),
+        ),
+        migrations.AlterField(
+            model_name='postseries',
+            name='introduction',
+            field=wagtail.fields.StreamField([('rich_text', 0), ('code', 3), ('image', 4)], blank=True, block_lookup={0: ('wagtail.blocks.RichTextBlock', (), {}), 1: ('wagtail.blocks.TextBlock', (), {'help_text': None, 'required': True}), 2: ('wagtail.blocks.ChoiceBlock', [], {'choices': [('plaintext', 'Plain Text'), ('bash', 'Bash'), ('css', 'CSS'), ('javascript', 'JavaScript'), ('html', 'HTML'), ('python', 'Python'), ('toml', 'TOML'), ('yaml', 'YAML')], 'required': False}), 3: ('wagtail.blocks.StructBlock', [[('code', 1), ('language', 2)]], {}), 4: ('picata.blocks.WrappedImageChooserBlock', (), {})}, help_text='Content to introduce the series of articles.'),
+        ),
+    ]

picata/models.py

@@ -4,10 +4,11 @@
 # pyright: reportAttributeAccessIssue=false
 
 from collections import OrderedDict
-from datetime import timedelta
-from typing import Any, ClassVar, cast
+from datetime import datetime, timedelta
+from typing import Any, ClassVar, TypedDict, cast
 
-from django.contrib.auth.models import AnonymousUser, User
+from django.apps import apps
+from django.contrib.auth.models import AbstractUser
 from django.db.models import (
     CASCADE,
     SET_NULL,
@@ -17,15 +18,15 @@ from django.db.models import (
     SlugField,
     TextField,
 )
-from django.db.models.functions import Coalesce, ExtractYear
+from django.db.models.functions import Coalesce
 from django.http import HttpRequest
 from django.urls import reverse
+from django.utils.timezone import now
 from modelcluster.contrib.taggit import ClusterTaggableManager
 from modelcluster.fields import ParentalKey
 from taggit.models import TagBase, TaggedItemBase
 from wagtail.admin.panels import FieldPanel, Panel
 from wagtail.blocks import RichTextBlock
-from wagtail.contrib.routable_page.models import RoutablePageMixin
 from wagtail.contrib.settings.models import BaseSiteSetting, register_setting
 from wagtail.fields import RichTextField, StreamField
 from wagtail.images.blocks import ImageChooserBlock
@@ -35,7 +36,7 @@ from wagtail.query import PageQuerySet
 from wagtail.search import index
 from wagtail_modeladmin.options import ModelAdmin
 
-from picata.typing import Args, Kwargs
+from picata.typing import Args, Kwargs, UserOrNot
 from picata.typing.wagtail import PageContext
 
 from .blocks import (
@@ -45,6 +46,53 @@ from .blocks import (
 )
 
 
+class ChronoPageQuerySet(PageQuerySet):
+    """QuerySet for pages that can be ordered based on dates."""
+
+    def with_effective_date(self) -> "ChronoPageQuerySet":
+        """Annotate pages with 'effective_date' to allow date-based ordering."""
+        return self.annotate(
+            effective_date=Coalesce("last_published_at", "latest_revision_created_at", now())
+        )
+
+    def by_date(self) -> "ChronoPageQuerySet":
+        """Return all pages ordered by descending 'effective_date'."""
+        return self.with_effective_date().order_by("-effective_date")
+
+    def live_for_user(self, user: UserOrNot = None) -> "ChronoPageQuerySet":
+        """Filter out non-live pages for non-authenticated users."""
+        return self if user and user.is_authenticated else self.live()
+
+    def descendants_of_page(self, page: Page) -> "ChronoPageQuerySet":
+        """Return all Article and PostSeries pages under a given page."""
+        from picata.models import Article, PostSeries  # Avoid circular imports
+
+        qs = Page.objects.descendant_of(page).type(Article, PostSeries)  # ✅ Correct approach!
+        return qs.specific()  # Ensures the QuerySet remains correctly typed.
+
+
+class ChronoPageManager(PageManager.from_queryset(ChronoPageQuerySet)):  # type: ignore[misc]
+    """Custom manager to ensure QuerySet methods are always available."""
+
+
+class CorePublicationData(TypedDict):
+    """Guaranteed keys for publication data on a page derived from `BasePage`."""
+
+    live: bool
+    url: str | None
+    published: str | None
+    updated: str | None
+    year: int
+    list_date: datetime
+
+
+class BasePublicationData(CorePublicationData, total=False):
+    """Publication data that may be included on pages derived from `BasePage`."""
+
+    latest_draft: str
+    draft_url: str
+
+
 class BasePageContext(PageContext, total=False):
     """Return-type for an `Article`'s context dictionary."""
 
@@ -57,10 +105,11 @@ class BasePageContext(PageContext, total=False):
 
 
 class BasePage(Page):
-    """Mixin for `Page`-types offering previews of themselves on other `Page`s."""
+    """Base for all Picata pages, offering publication and preview data methods."""
 
-    @property
-    def preview_data(self) -> dict[str, Any]:
+    objects = ChronoPageManager()
+
+    def get_preview_fields(self, user: UserOrNot = None) -> dict[str, Any]:
         """Return a dictionary of data used in previewing this page type."""
         return {
             "title": self.seo_title or self.title,
@@ -73,14 +122,12 @@ class BasePage(Page):
         last_edited = (
             self.latest_revision.created_at if self.latest_revision else self.last_published_at
         )
+        published, updated = self.first_published_at, self.last_published_at
         year = (
             self.first_published_at.year
             if self.first_published_at
-            else last_edited.year
-            if last_edited
-            else None
+            else (last_edited.year if last_edited else now().year)
         )
-        published, updated = self.first_published_at, self.last_published_at
 
         # Convert datetime objects to strings like "3 Jan, '25", or False, and
         # give a grace-period of one week for edits before marking the post as "updated"
@@ -97,6 +144,7 @@ class BasePage(Page):
             "published": published_str,
             "updated": updated_str,
             "year": year,
+            "list_date": published if published else last_edited if last_edited else now(),
         }
 
         # Add last draft date & preview URL if there's an unpublished draft, for logged-in users
@@ -120,7 +168,7 @@ class BasePage(Page):
         from picata.helpers.wagtail import page_preview_data
 
         context = super().get_context(request, *args, **kwargs)
-        context.update(page_preview_data(self, request))
+        context.update(page_preview_data(self, request.user))
         return cast(BasePageContext, {**context})
 
     class Meta:
@@ -162,9 +210,9 @@ class TaggedPage(BasePage):
         help_text="Tags for the article.",
     )
 
-    content_panels: ClassVar[list[Panel]] = [
-        *BasePage.content_panels,
+    promote_panels: ClassVar[list[Panel]] = [
         FieldPanel("tags"),
+        *BasePage.promote_panels,
     ]
 
     class Meta:
@@ -273,35 +321,37 @@ class ArticleTypeAdmin(ModelAdmin):
     search_fields = ("name", "slug")  # Fields to include in the search bar
 
 
-class ArticleContext(BasePageContext):
-    """Return-type for an `Article`'s context dictionary."""
+class SeriesPostMixinContext(TypedDict, total=False):
+    """Potential context data for page including `SeriesPostMixin`."""
 
-    content: str
+    series: dict[str, Any]
 
 
-class ArticleQuerySet(PageQuerySet):
-    """Default `QuerySet` for all `Article`-type pages."""
+class SeriesPostMixin:
+    """Mixin for articles that belong to a PostSeries."""
 
-    def with_effective_date(self) -> PageQuerySet:
-        """Annotate with 'effective_date' to allow date-ordering to consider recent drafts."""
-        return self.annotate(
-            effective_date=Coalesce("first_published_at", "latest_revision_created_at")
-        )
+    def get_context(
+        self, request: HttpRequest, *args: Args, **kwargs: Kwargs
+    ) -> SeriesPostMixinContext:
+        """Return context about the series this page belongs to (if any)."""
+        context = cast(Page, super()).get_context(request, *args, **kwargs)
+        parent = context["page"].get_parent()
+        PostSeries = apps.get_model("picata", "PostSeries")
+        if isinstance(parent, PostSeries):
+            context["series"] = parent.get_preview_fields(request.user, relative_to=self)
+        return cast(SeriesPostMixinContext, context)
 
-    def by_date(self) -> PageQuerySet:
-        """Return all `Article` pages, ordered by decending "effective" date."""
-        return self.with_effective_date().order_by("-effective_date")
 
-    def live_for_user(self, user: AnonymousUser | User) -> PageQuerySet:
-        """Filter out non-live pages for non-authenticated users."""
-        return self if user.is_authenticated else self.live()
+class ArticleContext(SeriesPostMixinContext, BasePageContext):
+    """Return-type for an `Article`'s context dictionary."""
+
+    content: str
 
 
-class Article(TaggedPage):
+class Article(SeriesPostMixin, TaggedPage):
     """Class for article-like pages."""
 
     template = "picata/article.html"
-    objects = PageManager.from_queryset(ArticleQuerySet)()
 
     tagline: CharField = CharField(
         blank=True, help_text="A short tagline for the article.", max_length=255
@@ -327,12 +377,16 @@ class Article(TaggedPage):
         help_text="Select the type of article.",
     )
 
+    promote_panels: ClassVar[list[Panel]] = [
+        FieldPanel("summary"),
+        FieldPanel("page_type"),
+        *TaggedPage.promote_panels,
+    ]
+
     content_panels: ClassVar[list[Panel]] = [
         *TaggedPage.content_panels,
         FieldPanel("tagline"),
-        FieldPanel("summary"),
         FieldPanel("content"),
-        FieldPanel("page_type"),
     ]
 
     search_fields: ClassVar[list[index.SearchField]] = [
@@ -344,11 +398,10 @@ class Article(TaggedPage):
         index.SearchField("page_type"),
     ]
 
-    @property
-    def preview_data(self) -> dict[str, Any]:
+    def get_preview_fields(self, user: UserOrNot = None) -> dict[str, Any]:
         """Return data required to render a preview of this article."""
         return {
-            **super().preview_data,
+            **super().get_preview_fields(user),
             "tagline": self.tagline,
             "summary": self.summary,
             "page_type": self.page_type,
@@ -362,17 +415,17 @@ class Article(TaggedPage):
         return cast(ArticleContext, context)
 
 
-class PostGroupePageContext(PageContext):
+class PostGroupPageContext(BasePageContext):
     """Return-type for a `PostGroupPage`'s context dictionary."""
 
-    posts: OrderedDict[int, list[dict[str, str]]]
+    posts_by_year: OrderedDict[int, list[dict[str, str]]]
 
 
-class PostGroupPage(RoutablePageMixin, Page):
+class PostGroupPage(BasePage):
     """A top-level page for grouping various types of posts or articles."""
 
     template = "picata/post_listing.html"
-    subpage_types: ClassVar[list[str]] = ["picata.Article"]
+    subpage_types: ClassVar[list[str]] = ["picata.Article", "picata.PostSeries"]
 
     intro = RichTextField(blank=True, help_text="An optional introduction to this group.")
 
@@ -380,30 +433,30 @@ class PostGroupPage(RoutablePageMixin, Page):
 
     def get_context(
         self, request: HttpRequest, *args: Args, **kwargs: Kwargs
-    ) -> PostGroupePageContext:
+    ) -> PostGroupPageContext:
         """Add a dictionary of posts grouped by year to the context dict."""
-        children = self.get_children()
-        if not request.user.is_authenticated:
-            children = children.live()
-        children = children.specific()
-        children = children.annotate(
-            effective_date=Coalesce("first_published_at", "latest_revision_created_at"),
-            year_published=ExtractYear("first_published_at"),
+        from picata.helpers.wagtail import page_preview_data, visible_pages_qs
+
+        children = visible_pages_qs(
+            cast(AbstractUser, request.user), cast(PageQuerySet, self.get_children())
+        ).specific()
+
+        child_data = sorted(
+            [page_preview_data(child, request.user) for child in children],
+            key=lambda p: p["list_date"],
+            reverse=True,
         )
 
         # Create an OrderedDict grouping posts by year in reverse chronological order
         posts_by_year: OrderedDict = OrderedDict()
-        for child in children.order_by("-effective_date"):
-            post_data = getattr(child, "preview_data", {}).copy()
-            post_data.update(**child.get_publication_data(request))
-
+        for child in child_data:
             # Group posts by year, defaulting to last-draft year if unpublished
-            if post_data["year"] not in posts_by_year:
-                posts_by_year[post_data["year"]] = []
-            posts_by_year[post_data["year"]].append(post_data)
+            if child["year"] not in posts_by_year:
+                posts_by_year[child["year"]] = []
+            posts_by_year[child["year"]].append(child)
 
         return cast(
-            PostGroupePageContext,
+            PostGroupPageContext,
             {**super().get_context(request, *args, **kwargs), "posts_by_year": posts_by_year},
         )
 
@@ -484,7 +537,7 @@ class HomePage(BasePage):
         from picata.helpers.wagtail import page_preview_data
 
         recent_posts = Article.objects.live_for_user(request.user).by_date()
-        recent_posts = [page_preview_data(post, request) for post in recent_posts]
+        recent_posts = [page_preview_data(post, request.user) for post in recent_posts]
 
         return cast(
             HomePageContext,
@@ -500,3 +553,86 @@ class HomePage(BasePage):
         """Declare explicit human-readable names for the page type."""
 
         verbose_name = "home page"
+
+
+class PostSeriesContext(BasePageContext):
+    """Return-type for a `PostSeries`'s context dictionary."""
+
+    introduction: str
+
+
+class PostSeries(BasePage):
+    """A container for a series of related articles."""
+
+    summary = RichTextField(blank=True, help_text="A summary to be displayed in previews.")
+    introduction = StreamField(
+        [
+            ("rich_text", RichTextBlock()),
+            ("code", CodeBlock()),
+            ("image", WrappedImageChooserBlock()),
+        ],
+        blank=True,
+        use_json_field=True,
+        help_text="Content to introduce the series of articles.",
+    )
+
+    promote_panels: ClassVar[list[Panel]] = [
+        FieldPanel("summary"),
+        *BasePage.promote_panels,
+    ]
+
+    content_panels: ClassVar[list[FieldPanel]] = [
+        *BasePage.content_panels,
+        FieldPanel("introduction"),
+    ]
+
+    parent_page_types: ClassVar[list[str]] = ["PostGroupPage"]
+    subpage_types: ClassVar[list[str]] = ["Article"]
+
+    def get_publication_data(self, request: HttpRequest | None = None) -> dict[str, Any]:
+        """Return publication data, using the most recent child article's data for sorting."""
+        data = super().get_publication_data(request)
+        children = (
+            Article.objects.child_of(self)
+            .by_date()
+            .live_for_user(request.user if request else None)
+        )
+        child_publication_data = [child.get_publication_data(request) for child in children]
+
+        if child_publication_data:
+            latest_child = max(child_publication_data, key=lambda p: p["list_date"])
+            data["published"] = latest_child["published"]
+            data["updated"] = latest_child["updated"]
+            data["list_date"] = latest_child["list_date"]
+
+        return data
+
+    def get_preview_fields(
+        self, user: UserOrNot = None, relative_to: Page | None = None
+    ) -> dict[str, Any]:
+        """Return preview data, including a sorted list of child articles as 'parts'."""
+        from picata.helpers.wagtail import page_preview_data
+
+        site = self.get_site()
+        data = {
+            **super().get_preview_fields(user),
+            "summary": self.summary,
+        }
+        children = list(Article.objects.child_of(self).by_date().live_for_user(user))
+        part_previews = [page_preview_data(child, user) for child in children]
+        data["url"] = self.relative_url(site)
+        data["parts"] = part_previews
+        if relative_to and relative_to in children:
+            data["this_part"] = children.index(relative_to) + 1
+        return data
+
+    def get_context(self, request: HttpRequest, *args: Args, **kwargs: Kwargs) -> PostSeriesContext:
+        """Add content streams and a recent posts list to the context."""
+        return cast(
+            PostSeriesContext,
+            {
+                **super().get_context(request, *args, **kwargs),
+                **self.get_preview_fields(request.user),
+                "introduction": self.introduction,
+            },
+        )

picata/transformers.py

@@ -13,7 +13,8 @@ def add_heading_ids(tree: etree._Element) -> None:
         return
 
     for heading in main[0].xpath(".//h1|//h2|//h3|//h4|//h5|//h6"):
-        if heading.get("id"):
+        # Exclude headings in <nav> tags and those already having an id.
+        if heading.xpath("ancestor::nav") or heading.get("id"):
             continue
         heading_text = get_full_text(heading)
         slug = heading_text.lower().replace(" ", "-")

picata/typing/__init__.py

@@ -2,6 +2,7 @@
 
 from typing import Any, TypedDict
 
+from django.contrib.auth.models import AbstractBaseUser, AnonymousUser
 from django.http import HttpRequest
 
 # Generic arguments and keyword arguments
@@ -9,6 +10,9 @@ Args = tuple[Any, ...]
 Kwargs = dict[str, Any]
 
 
+UserOrNot = AbstractBaseUser | AnonymousUser | None
+
+
 class Context(TypedDict):
     """Base class for context dicts passed all around the system."""
 

picata/views.py

@@ -88,7 +88,7 @@ def search(request: HttpRequest) -> HttpResponse:
     results: dict[str, str | list[str] | set[str]] = {}
 
     # Base QuerySet for all pages
-    pages: PageQuerySet = visible_pages_qs(request)
+    pages: PageQuerySet = visible_pages_qs(request.user)
 
     # Perform search by query
     query_string = request.GET.get("query")
@@ -119,6 +119,6 @@ def search(request: HttpRequest) -> HttpResponse:
         specific_pages = []
 
     # Enhance pages with preview and publication data
-    page_previews = [page_preview_data(page, request) for page in specific_pages]
+    page_previews = [page_preview_data(page, request.user) for page in specific_pages]
 
     return render(request, "picata/search_results.html", {**results, "pages": page_previews})

{picata-0.0.11.dist-info → picata-0.0.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: picata
-Version: 0.0.11
+Version: 0.0.12
 Summary: Ada's Wagtail-based CMS & blog
 Project-URL: Documentation, https://github.com/hipikat/picata#readme
 Project-URL: Issues, https://github.com/hipikat/picata/issues