simple-module-news 0.0.2__tar.gz

simple_module_news-0.0.2/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+*.db
+*.sqlite3
+.env
+
+# Built frontend assets — shipped inside the wheel via force-include but
+# NOT source-controlled. Re-run `npm run build` (or `vite build`) before
+# `uv build` to repopulate.
+*/static/dist/

simple_module_news-0.0.2/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: simple_module_news
+Version: 0.0.2
+Summary: News articles backed by page-builder pages
+Project-URL: Repository, https://github.com/antosubash/simple_module_python_modules
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: articles,cms,news,simple-module
+Requires-Python: >=3.12
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: simple-module-core<0.1,>=0.0.25
+Requires-Dist: simple-module-db<0.1,>=0.0.25
+Requires-Dist: simple-module-hosting<0.1,>=0.0.25
+Requires-Dist: simple-module-pagebuilder<0.1,>=0.0.1
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: simple-module-test<0.1,>=0.0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# simple_module_news
+
+News articles for SimpleModule hosts, backed by page-builder pages.
+
+An article **is** a page. Its title, slug, body, approval workflow, revisions
+and public URL all belong to `simple_module_pagebuilder`; this module adds only
+the two things a page has no concept of — the category it belongs to and the
+date it should be listed under — plus the listing API and a feed block.
+
+That is why there is no public route here. An article serves at `/p/{slug}`
+with the existing ETag, cache, CSP, SEO and site-layout handling; a second
+viewer would mean duplicating all of it.
+
+## Installation
+
+```bash
+pip install simple_module_news
+```
+
+The host must also install `simple_module_pagebuilder`. For an in-repo
+checkout, resolve it from the workspace:
+
+```toml
+dependencies = ["simple_module_news"]
+
+[tool.uv.sources.simple_module_news]
+workspace = true
+```
+
+Then run `make migrate` — the module's first revision is labelled `news`, so it
+can be removed on its own with `alembic downgrade news@base`.
+
+## Usage
+
+Go to **News** in the sidebar. "New article" creates a page, attaches the
+article metadata to it, and drops you into the page-builder editor to write the
+body. Category and date are edited inline in the list.
+
+To show articles on a page, add the **News feed** block in the page builder and
+set its category filter and item count.
+
+### API
+
+| Route | Access |
+|---|---|
+| `GET /api/news/articles?limit&offset&category` | anonymous; published only |
+| `GET /api/news/categories` | anonymous; published only |
+| `POST /api/news/articles` | `news.edit` |
+| `PUT /api/news/articles/{id}` | `news.edit` |
+| `DELETE /api/news/articles/{id}` | `news.edit` |
+
+Reads are anonymous because the feed block runs on public pages. Listing is
+ordered newest first with undated articles last, and an editor additionally
+sees articles whose page is still a draft.
+
+`PUT` is a **partial** update: a field you omit is left alone. Sending
+`published_at` as an explicit `null` is different from omitting it — that
+undates the article, which is a real state rather than an error.
+
+`DELETE` detaches the metadata; the page and its body stay.
+
+## Design note: no foreign key
+
+`news_articles.page_id` carries no database foreign key. The framework gives
+every module its own `MetaData`, so a cross-module `ForeignKey` cannot resolve
+its target table, and pagebuilder publishes no page-deleted event to hang a
+cascade on either.
+
+Two things make that safe. Every listing inner-joins the page, so an article
+whose page was deleted stops appearing immediately rather than rendering a card
+that links nowhere. And the orphan is then removed rather than merely hidden —
+by a `PageDeleted` subscription first, and by a sweep at application startup
+when that event is missed.
+
+The sweep is not belt-and-braces. The event bus logs a handler failure instead
+of raising it, and pagebuilder has already committed the page deletion by the
+time the handler runs, so a dropped event leaves the row behind with nothing to
+retry it. An invisible orphan does not stay invisible either: SQLite reuses a
+deleted row's id, so the row would re-attach to whatever page is created next
+and list one article's category and date against another article's page.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## API-version contract
+
+`ModuleMeta.requires_framework` declares which `simple_module_core` versions
+this module supports. Update the spec on each framework major bump after
+verifying compatibility.

simple_module_news-0.0.2/README.md

@@ -0,0 +1,93 @@
+# simple_module_news
+
+News articles for SimpleModule hosts, backed by page-builder pages.
+
+An article **is** a page. Its title, slug, body, approval workflow, revisions
+and public URL all belong to `simple_module_pagebuilder`; this module adds only
+the two things a page has no concept of — the category it belongs to and the
+date it should be listed under — plus the listing API and a feed block.
+
+That is why there is no public route here. An article serves at `/p/{slug}`
+with the existing ETag, cache, CSP, SEO and site-layout handling; a second
+viewer would mean duplicating all of it.
+
+## Installation
+
+```bash
+pip install simple_module_news
+```
+
+The host must also install `simple_module_pagebuilder`. For an in-repo
+checkout, resolve it from the workspace:
+
+```toml
+dependencies = ["simple_module_news"]
+
+[tool.uv.sources.simple_module_news]
+workspace = true
+```
+
+Then run `make migrate` — the module's first revision is labelled `news`, so it
+can be removed on its own with `alembic downgrade news@base`.
+
+## Usage
+
+Go to **News** in the sidebar. "New article" creates a page, attaches the
+article metadata to it, and drops you into the page-builder editor to write the
+body. Category and date are edited inline in the list.
+
+To show articles on a page, add the **News feed** block in the page builder and
+set its category filter and item count.
+
+### API
+
+| Route | Access |
+|---|---|
+| `GET /api/news/articles?limit&offset&category` | anonymous; published only |
+| `GET /api/news/categories` | anonymous; published only |
+| `POST /api/news/articles` | `news.edit` |
+| `PUT /api/news/articles/{id}` | `news.edit` |
+| `DELETE /api/news/articles/{id}` | `news.edit` |
+
+Reads are anonymous because the feed block runs on public pages. Listing is
+ordered newest first with undated articles last, and an editor additionally
+sees articles whose page is still a draft.
+
+`PUT` is a **partial** update: a field you omit is left alone. Sending
+`published_at` as an explicit `null` is different from omitting it — that
+undates the article, which is a real state rather than an error.
+
+`DELETE` detaches the metadata; the page and its body stay.
+
+## Design note: no foreign key
+
+`news_articles.page_id` carries no database foreign key. The framework gives
+every module its own `MetaData`, so a cross-module `ForeignKey` cannot resolve
+its target table, and pagebuilder publishes no page-deleted event to hang a
+cascade on either.
+
+Two things make that safe. Every listing inner-joins the page, so an article
+whose page was deleted stops appearing immediately rather than rendering a card
+that links nowhere. And the orphan is then removed rather than merely hidden —
+by a `PageDeleted` subscription first, and by a sweep at application startup
+when that event is missed.
+
+The sweep is not belt-and-braces. The event bus logs a handler failure instead
+of raising it, and pagebuilder has already committed the page deletion by the
+time the handler runs, so a dropped event leaves the row behind with nothing to
+retry it. An invisible orphan does not stay invisible either: SQLite reuses a
+deleted row's id, so the row would re-attach to whatever page is created next
+and list one article's category and date against another article's page.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## API-version contract
+
+`ModuleMeta.requires_framework` declares which `simple_module_core` versions
+this module supports. Update the spec on each framework major bump after
+verifying compatibility.

simple_module_news-0.0.2/news/components/ArticleRow.tsx

@@ -0,0 +1,78 @@
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { useState } from 'react';
+
+import type { ArticleRead } from '../utils/api';
+
+/** `2026-02-01T00:00:00` -> `2026-02-01`, which is what <input type=date> wants. */
+function toDateInput(iso: string | null): string {
+  return iso ? iso.slice(0, 10) : '';
+}
+
+export function ArticleRow({
+  article,
+  busy,
+  onSave,
+  onDetach,
+}: {
+  article: ArticleRead;
+  busy: boolean;
+  onSave: (id: number, category: string, publishedAt: string | null) => void;
+  onDetach: (id: number) => void;
+}) {
+  const [category, setCategory] = useState(article.category);
+  const [date, setDate] = useState(toDateInput(article.published_at));
+
+  const dirty = category !== article.category || date !== toDateInput(article.published_at);
+
+  return (
+    <tr className="border-b last:border-b-0">
+      <td className="py-2 pr-4">
+        <a href={`/pagebuilder/${article.page_id}`} className="font-medium hover:underline">
+          {article.title}
+        </a>
+        <div className="text-xs text-muted-foreground">{article.url}</div>
+      </td>
+      <td className="py-2 pr-4">
+        <Input
+          aria-label={`Category for ${article.title}`}
+          value={category}
+          disabled={busy}
+          onChange={(e) => setCategory(e.target.value)}
+          className="w-40"
+        />
+      </td>
+      <td className="py-2 pr-4">
+        <Input
+          type="date"
+          aria-label={`Date for ${article.title}`}
+          value={date}
+          disabled={busy}
+          onChange={(e) => setDate(e.target.value)}
+          className="w-40"
+        />
+      </td>
+      <td className="py-2 text-right whitespace-nowrap">
+        <Button
+          type="button"
+          size="sm"
+          // Enabled only when something changed, so the row never fires a
+          // no-op PUT that bumps updated_at for nothing.
+          disabled={busy || !dirty}
+          onClick={() => onSave(article.id, category, date ? `${date}T00:00:00Z` : null)}
+        >
+          Save
+        </Button>
+        <Button
+          type="button"
+          size="sm"
+          variant="ghost"
+          disabled={busy}
+          onClick={() => onDetach(article.id)}
+        >
+          Detach
+        </Button>
+      </td>
+    </tr>
+  );
+}

simple_module_news-0.0.2/news/components/NewsFeed.tsx

@@ -0,0 +1,96 @@
+import type { ComponentConfig } from '@puckeditor/core';
+import {
+  type ArticleCardItem,
+  ArticleCardsGrid,
+} from '@simple-module-py/pagebuilder/pagebuilder/components/widgets/article-cards-render';
+import { useEffect, useState } from 'react';
+
+import { type ArticleRead, formatArticleDate, listArticles } from '../utils/api';
+
+export interface NewsFeedProps {
+  title: string;
+  category: string;
+  limit: number;
+  columns: '2' | '3' | '4';
+  viewAllLabel: string;
+  viewAllHref: string;
+}
+
+function toCard(article: ArticleRead): ArticleCardItem {
+  return {
+    imageUrl: article.cover_image_url,
+    imageAlt: '',
+    eyebrow: article.category,
+    date: formatArticleDate(article.published_at),
+    title: article.title,
+    body: article.excerpt,
+    // An article *is* a page, so this is the page's own public URL.
+    href: article.url,
+  };
+}
+
+export function NewsFeedRender({
+  title,
+  category,
+  limit,
+  columns,
+  viewAllLabel,
+  viewAllHref,
+}: NewsFeedProps) {
+  const [items, setItems] = useState<ArticleCardItem[] | null>(null);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    listArticles({ limit, category, signal: controller.signal })
+      .then((response) => setItems(response.items.map(toCard)))
+      // An empty feed and a failed fetch look the same to a visitor on
+      // purpose: a broken API must not put an error box on a public page.
+      .catch(() => setItems([]));
+    return () => controller.abort();
+  }, [limit, category]);
+
+  // Render nothing at all until the first response, and nothing when there
+  // are no articles: a heading with an empty grid under it reads as a broken
+  // section. An empty fragment rather than null because Puck's render must
+  // return an Element.
+  if (items === null || items.length === 0) return <></>;
+
+  return (
+    <ArticleCardsGrid
+      title={title}
+      viewAllLabel={viewAllLabel}
+      viewAllHref={viewAllHref}
+      columns={columns}
+      items={items}
+    />
+  );
+}
+
+export const NewsFeedBlock: ComponentConfig<NewsFeedProps> = {
+  label: 'News feed (live articles)',
+  fields: {
+    title: { type: 'text', label: 'Heading' },
+    category: { type: 'text', label: 'Category filter (blank = all)' },
+    limit: { type: 'number', label: 'How many', min: 1, max: 12 },
+    columns: {
+      type: 'select',
+      label: 'Columns (desktop)',
+      options: [
+        { label: '2', value: '2' },
+        { label: '3', value: '3' },
+        { label: '4', value: '4' },
+      ],
+    },
+    viewAllLabel: { type: 'text', label: 'View-all link label' },
+    viewAllHref: { type: 'text', label: 'View-all link URL' },
+  },
+  defaultProps: {
+    title: 'Latest news',
+    category: '',
+    limit: 4,
+    columns: '4',
+    viewAllLabel: '',
+    viewAllHref: '',
+  },
+  render: NewsFeedRender,
+};

simple_module_news-0.0.2/news/constants.py

@@ -0,0 +1,40 @@
+"""News module constants.
+
+Kept out of the call sites so no module name, route or permission appears as a
+bare literal — see scripts/check_hardcoded_strings.py.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+PACKAGE: Final = "news"
+
+ROUTE_PREFIX_API: Final = "/api/news"
+VIEW_PREFIX: Final = "/news"
+# Trailing slash: the list route is registered at "/" under VIEW_PREFIX, so
+# linking to the bare prefix costs a 307 round trip on every navigation.
+MENU_URL: Final = f"{VIEW_PREFIX}/"
+MENU_GROUP: Final = "Content"
+MENU_ICON: Final = "newspaper"
+
+# Modules this one depends on.
+_MODULE_PAGEBUILDER: Final = "PageBuilder"
+
+# Inertia page identifier, rendered as a literal at the view so the SM003/SM004
+# static-AST diagnostics can pair it with pages/NewsList.tsx.
+_PAGE_LIST: Final = "News/NewsList"
+
+PERM_VIEW: Final = "news.view"
+PERM_EDIT: Final = "news.edit"
+
+# Anonymous reads: the feed block runs on public pages, so listing has to work
+# without a session. Writes stay behind news.edit.
+PUBLIC_READ_PREFIXES: Final = (
+    f"{ROUTE_PREFIX_API}/articles",
+    f"{ROUTE_PREFIX_API}/categories",
+)
+
+MAX_CATEGORY_LEN: Final = 80
+DEFAULT_LIMIT: Final = 20
+MAX_LIMIT: Final = 100

simple_module_news-0.0.2/news/contracts/schemas.py

@@ -0,0 +1,56 @@
+"""DTOs for the News module — the public surface."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from news.constants import MAX_CATEGORY_LEN
+
+
+class ArticleRead(BaseModel):
+    """An article, flattened from its sidecar row plus the page it belongs to."""
+
+    id: int
+    page_id: int
+    slug: str
+    title: str
+    excerpt: str = ""
+    cover_image_url: str = ""
+    category: str = ""
+    published_at: datetime | None = None
+    url: str
+    """Where the article actually serves.
+
+    An article *is* a page, so this is the page's own public URL rather than a
+    route this module owns — duplicating the public viewer would mean
+    duplicating its ETag, cache, CSP, SEO and site-layout handling.
+    """
+
+
+class ArticleListResponse(BaseModel):
+    items: list[ArticleRead]
+    total: int
+
+
+class CategoryCount(BaseModel):
+    category: str
+    count: int
+
+
+class CategoryListResponse(BaseModel):
+    items: list[CategoryCount]
+
+
+class ArticleCreate(BaseModel):
+    """Attach article metadata to an existing page."""
+
+    page_id: int
+    category: str = Field(default="", max_length=MAX_CATEGORY_LEN)
+    published_at: datetime | None = None
+
+
+class ArticleUpdate(BaseModel):
+    category: str | None = Field(default=None, max_length=MAX_CATEGORY_LEN)
+    published_at: datetime | None = None

simple_module_news-0.0.2/news/endpoints/api.py

@@ -0,0 +1,158 @@
+"""REST API for News.
+
+Reads are anonymous: the feed block runs on public pages, so a visitor with no
+session has to be able to list articles. Writes require ``news.edit``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from simple_module_db import get_db
+from simple_module_hosting.permissions import (
+    WILDCARD,
+    RequiresPermission,
+    resolve_permissions,
+)
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from news import service
+from news.constants import DEFAULT_LIMIT, MAX_LIMIT, PERM_EDIT
+from news.contracts.schemas import (
+    ArticleCreate,
+    ArticleListResponse,
+    ArticleRead,
+    ArticleUpdate,
+    CategoryListResponse,
+)
+
+router = APIRouter()
+
+require_edit = Depends(RequiresPermission(PERM_EDIT))
+
+
+def _may_see_drafts(request: Request) -> bool:
+    """Only an editor sees articles whose page is still a draft.
+
+    Everyone else gets the published site, which is what the public feed block
+    must show.
+
+    Reads ``request.state.resolved_permissions`` — where the hosting middleware
+    and ``RequiresPermission`` both put the resolved set — rather than a
+    ``permissions`` attribute on the user. ``UserContext`` has no such
+    attribute, so testing it always yielded an empty list and no editor ever
+    saw a draft.
+
+    The fallback mirrors ``RequiresPermission.__call__``: these listings are
+    registered as public routes, so on an anonymous-readable GET nothing has
+    populated ``resolved_permissions`` by the time we are asked. ``WILDCARD`` is
+    checked because an administrator resolves to it rather than to a literal
+    ``news.edit``.
+    """
+    resolved = getattr(request.state, "resolved_permissions", None)
+    if resolved is None:
+        user = getattr(request.state, "user", None)
+        if user is None:
+            return False
+        sm = getattr(getattr(request.app, "state", None), "sm", None)
+        registry = getattr(sm, "permissions", None) if sm is not None else None
+        resolved = resolve_permissions(
+            getattr(user, "roles", None) or [],
+            role_map=registry.role_map if registry is not None else None,
+        )
+    return WILDCARD in resolved or PERM_EDIT in resolved
+
+
+async def _read_one_by_page(db: AsyncSession, page_id: int) -> ArticleRead:
+    """Re-read through the listing join so every response has one shape.
+
+    Drafts are included: an editor has just written this row and must see it
+    back whatever state its page is in.
+    """
+    article = await service.get_read_by_page(db, page_id, include_drafts=True)
+    if article is None:
+        # The page is the only source of slug and title, so without it there is
+        # nothing to return.
+        raise HTTPException(status_code=404, detail="Article's page not found.")
+    return article
+
+
+@router.get("/articles", response_model=ArticleListResponse)
+async def list_articles(
+    request: Request,
+    limit: int = Query(DEFAULT_LIMIT, ge=1, le=MAX_LIMIT),
+    offset: int = Query(0, ge=0),
+    category: str | None = Query(None),
+    db: AsyncSession = Depends(get_db),
+) -> ArticleListResponse:
+    items, total = await service.list_articles(
+        db,
+        limit=limit,
+        offset=offset,
+        category=category,
+        include_drafts=_may_see_drafts(request),
+    )
+    return ArticleListResponse(items=items, total=total)
+
+
+@router.get("/categories", response_model=CategoryListResponse)
+async def list_categories(
+    request: Request, db: AsyncSession = Depends(get_db)
+) -> CategoryListResponse:
+    items = await service.list_categories(db, include_drafts=_may_see_drafts(request))
+    return CategoryListResponse(items=items)
+
+
+@router.post(
+    "/articles",
+    response_model=ArticleRead,
+    status_code=201,
+    dependencies=[require_edit],
+)
+async def attach_article(
+    body: ArticleCreate, db: AsyncSession = Depends(get_db)
+) -> ArticleRead:
+    """Make an existing page an article."""
+    if not await service.page_exists(db, body.page_id):
+        raise HTTPException(status_code=404, detail=f"Page {body.page_id} does not exist.")
+    if await service.get_by_page(db, body.page_id) is not None:
+        raise HTTPException(
+            status_code=409, detail=f"Page {body.page_id} is already an article."
+        )
+    await service.create(
+        db, page_id=body.page_id, category=body.category, published_at=body.published_at
+    )
+    return await _read_one_by_page(db, body.page_id)
+
+
+@router.put(
+    "/articles/{article_id}", response_model=ArticleRead, dependencies=[require_edit]
+)
+async def update_article(
+    article_id: int, body: ArticleUpdate, db: AsyncSession = Depends(get_db)
+) -> ArticleRead:
+    article = await service.get(db, article_id)
+    if article is None:
+        raise HTTPException(status_code=404, detail="Article not found.")
+    # A partial update: an omitted `published_at` leaves the date alone, while
+    # an explicit null undates the article. Only `model_fields_set` can tell
+    # those apart, and the distinction is the endpoint's to make.
+    await service.update(
+        db,
+        article,
+        category=body.category,
+        published_at=(
+            body.published_at
+            if "published_at" in body.model_fields_set
+            else service.UNSET
+        ),
+    )
+    return await _read_one_by_page(db, article.page_id)
+
+
+@router.delete("/articles/{article_id}", status_code=204, dependencies=[require_edit])
+async def detach_article(article_id: int, db: AsyncSession = Depends(get_db)) -> None:
+    """Detach the metadata. The page, and its body, stays."""
+    article = await service.get(db, article_id)
+    if article is None:
+        raise HTTPException(status_code=404, detail="Article not found.")
+    await service.delete(db, article)

simple_module_news-0.0.2/news/endpoints/views.py

@@ -0,0 +1,28 @@
+"""Inertia view endpoints for News."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from news import constants
+
+router = APIRouter()
+
+
+@router.get(
+    "/",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(constants.PERM_VIEW))],
+)
+async def article_list(inertia: InertiaDep) -> InertiaResponse:
+    # The list is fetched client-side from /api/news/articles so an inline edit
+    # can refresh one row without a full Inertia round trip.
+    #
+    # The page name comes from the constant, matching pagebuilder and this
+    # repo's check_hardcoded_strings. The framework's own modules inline the
+    # literal instead, for the SM003/SM004 static-AST pairing — the two
+    # conventions disagree, and an in-repo module follows the in-repo linter.
+    return await inertia.render(constants._PAGE_LIST)