maatlog 0.0.0__py3-none-any.whl

maatlog/__init__.py

@@ -0,0 +1,3 @@
+from .extension import setup
+
+__all__ = ["setup"]

maatlog/_myst_compat.py

@@ -0,0 +1,80 @@
+"""Narrow compatibility adapter for typed MyST 5.1 front matter."""
+
+from collections.abc import Callable, Mapping
+from importlib import import_module
+from typing import Protocol, cast
+
+from myst_parser.config.main import TopmatterReadError, read_topmatter
+
+
+class _Mark(Protocol):
+    line: int
+
+
+class _ScalarNode(Protocol):
+    value: object
+    start_mark: _Mark
+
+
+class _MappingNode(Protocol):
+    value: list[tuple[_ScalarNode, object]]
+
+
+class _YamlModule(Protocol):
+    compose: Callable[[str], object | None]
+
+
+class _MySTRendererModule(Protocol):
+    yaml: _YamlModule
+
+
+def read_typed_frontmatter(source: str) -> dict[str, tuple[object, int]] | None:
+    """Return MyST front matter values and one-based key lines.
+
+    ``read_topmatter`` is MyST's own typed loader. MyST's renderer module owns
+    the YAML implementation used to turn the same payload into marked nodes;
+    keeping that access here prevents MaatLog from importing transitive PyYAML
+    directly and gives diagnostics the parser's key marks.
+    """
+
+    try:
+        topmatter = read_topmatter(source)
+    except TopmatterReadError:
+        return None
+    if topmatter is None:
+        return None
+
+    payload = _frontmatter_payload(source)
+    renderer = cast(_MySTRendererModule, cast(object, import_module("myst_parser.mdit_to_docutils.base")))
+    root = renderer.yaml.compose(payload)
+    key_lines = _mapping_key_lines(root)
+    typed = cast(Mapping[object, object], topmatter)
+    return {
+        key: (value, key_lines.get(key, 1))
+        for key, value in typed.items()
+        if isinstance(key, str) and key.startswith("maatlog-")
+    }
+
+
+def _frontmatter_payload(source: str) -> str:
+    lines = source.splitlines()
+    if not lines or not lines[0].startswith("---"):
+        return ""
+    payload: list[str] = []
+    for line in lines[1:]:
+        if line.startswith(("---", "...")):
+            break
+        payload.append(line)
+    return "\n".join(payload) + ("\n" if payload else "")
+
+
+def _mapping_key_lines(root: object | None) -> dict[str, int]:
+    if root is None or not hasattr(root, "value"):
+        return {}
+    mapping = cast(_MappingNode, root)
+    lines: dict[str, int] = {}
+    for key_node, _ in mapping.value:
+        if isinstance(key_node.value, str):
+            # The payload begins on source line 2, while parser marks are zero-based.
+            lines[key_node.value] = key_node.start_mark.line + 2
+    return lines

maatlog/archives.py

@@ -0,0 +1,218 @@
+"""Immutable archive page projection: filter, pagination, and docnames."""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Sequence
+from dataclasses import dataclass
+from math import ceil
+from zoneinfo import ZoneInfo
+
+from .config import TaxonomyAxis
+from .errors import Diagnostic, MaatlogBuildError
+from .model import Post
+from .references import archive_docname
+from .taxonomy import DomainIndex
+
+
+@dataclass(frozen=True, slots=True)
+class PostFilter:
+    """Filter for published posts. Empty axis means no constraint.
+
+    Within one axis, multiple IDs are OR. Across axes and month, constraints AND.
+    """
+
+    tags: tuple[str, ...] = ()
+    categories: tuple[str, ...] = ()
+    authors: tuple[str, ...] = ()
+    month: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveKey:
+    """Identity of an archive listing (all posts, or one taxonomy/month value)."""
+
+    axis: TaxonomyAxis | None
+    value: str | None
+    label: str
+
+
+@dataclass(frozen=True, slots=True)
+class PageSlice:
+    """One page of a filtered post sequence (1-origin page numbers)."""
+
+    number: int
+    total_pages: int
+    posts: tuple[Post, ...]
+
+    @property
+    def docname_suffix(self) -> str:
+        return "" if self.number == 1 else f"/page/{self.number}"
+
+
+@dataclass(frozen=True, slots=True)
+class ArchivePage:
+    """One generated archive page ready for collection / rendering."""
+
+    key: ArchiveKey
+    docname: str
+    number: int
+    total_pages: int
+    posts: tuple[Post, ...]
+    total_posts: int
+
+
+def filter_posts(
+    posts: Sequence[Post],
+    post_filter: PostFilter,
+    *,
+    timezone: ZoneInfo,
+) -> tuple[Post, ...]:
+    """Keep posts matching *post_filter*, preserving input order.
+
+    Same-axis IDs are OR; different axes and month are AND. An empty axis
+    tuple (or ``month is None``) imposes no constraint on that dimension.
+    """
+    return tuple(post for post in posts if _matches(post, post_filter, timezone=timezone))
+
+
+def paginate(posts: Sequence[Post], page_size: int) -> tuple[PageSlice, ...]:
+    """Split *posts* into 1-origin pages of *page_size*.
+
+    Empty input yields a single empty page 1. Page 1 has no ``/page/1`` suffix.
+    """
+    if page_size < 1:
+        msg = f"page_size must be >= 1, got {page_size}"
+        raise ValueError(msg)
+
+    if not posts:
+        return (PageSlice(number=1, total_pages=1, posts=()),)
+
+    total_pages = ceil(len(posts) / page_size)
+    return tuple(
+        PageSlice(
+            number=number,
+            total_pages=total_pages,
+            posts=tuple(posts[(number - 1) * page_size : number * page_size]),
+        )
+        for number in range(1, total_pages + 1)
+    )
+
+
+def project_archives(
+    index: DomainIndex,
+    *,
+    root: str,
+    page_size: int,
+    timezone: ZoneInfo,
+) -> tuple[ArchivePage, ...]:
+    """Project all archive pages from a published domain index.
+
+    The all-posts archive is always produced (even with zero posts). Taxonomy
+    and month archives are produced only when they have at least one post.
+    """
+    pages: list[ArchivePage] = []
+    pages.extend(
+        _pages_for_key(
+            posts=index.published,
+            key=ArchiveKey(axis=None, value=None, label="Posts"),
+            root=root,
+            page_size=page_size,
+        )
+    )
+
+    for axis in (TaxonomyAxis.TAG, TaxonomyAxis.CATEGORY, TaxonomyAxis.AUTHOR, TaxonomyAxis.MONTH):
+        axis_members = index.members.get(axis, {})
+        axis_labels = index.labels.get(axis, {})
+        for value, _slugs in axis_members.items():
+            if axis is TaxonomyAxis.MONTH:
+                post_filter = PostFilter(month=value)
+            elif axis is TaxonomyAxis.TAG:
+                post_filter = PostFilter(tags=(value,))
+            elif axis is TaxonomyAxis.CATEGORY:
+                post_filter = PostFilter(categories=(value,))
+            else:
+                post_filter = PostFilter(authors=(value,))
+
+            filtered = filter_posts(index.published, post_filter, timezone=timezone)
+            if not filtered:
+                continue
+            label = axis_labels.get(value, value)
+            pages.extend(
+                _pages_for_key(
+                    posts=filtered,
+                    key=ArchiveKey(axis=axis, value=value, label=label),
+                    root=root,
+                    page_size=page_size,
+                )
+            )
+
+    return tuple(pages)
+
+
+def _pages_for_key(
+    *,
+    posts: Sequence[Post],
+    key: ArchiveKey,
+    root: str,
+    page_size: int,
+) -> list[ArchivePage]:
+    slices = paginate(posts, page_size)
+    total_posts = len(posts)
+    return [
+        ArchivePage(
+            key=key,
+            docname=archive_docname(root, key.axis, key.value, page=slice_.number),
+            number=slice_.number,
+            total_pages=slice_.total_pages,
+            posts=slice_.posts,
+            total_posts=total_posts,
+        )
+        for slice_ in slices
+    ]
+
+
+def check_generated_docnames(
+    generated: Sequence[str],
+    *,
+    known_docnames: Collection[str],
+) -> None:
+    """Raise when projected archive docnames collide with sources or each other.
+
+    Collisions with Sphinx source / known docnames, or internal duplicates among
+    MaatLog pages, raise :class:`MaatlogBuildError` with
+    ``maatlog.generated-docname.conflict`` before any archive page is yielded or
+    owned outputs are committed.
+    """
+    diagnostics: list[Diagnostic] = []
+    seen: set[str] = set()
+    known = set(known_docnames)
+    for docname in generated:
+        if docname in seen or docname in known:
+            diagnostics.append(
+                Diagnostic(
+                    code="maatlog.generated-docname.conflict",
+                    message=f"Generated archive docname conflicts with an existing document: {docname}",
+                    field="docname",
+                    value=docname,
+                    expected="unused relative docname",
+                )
+            )
+        seen.add(docname)
+    if diagnostics:
+        raise MaatlogBuildError(diagnostics)
+
+
+def _matches(post: Post, post_filter: PostFilter, *, timezone: ZoneInfo) -> bool:
+    if post_filter.tags and not any(tag in post.tags for tag in post_filter.tags):
+        return False
+    if post_filter.categories and not any(cat in post.categories for cat in post_filter.categories):
+        return False
+    if post_filter.authors and not any(author in post.authors for author in post_filter.authors):
+        return False
+    if post_filter.month is not None:
+        if post.published_at is None:
+            return False
+        month = post.published_at.astimezone(timezone).strftime("%Y-%m")
+        if month != post_filter.month:
+            return False
+    return True

maatlog/builders.py

@@ -0,0 +1,72 @@
+"""Builder capability classification for MaatLog feature gates."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from sphinx.application import Sphinx
+from sphinx.builders import Builder
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+PARTIAL_SUPPORT_CODE = "maatlog.builder.partial-support"
+_PARTIAL_WARNED_ATTR = "_maatlog_partial_support_warned"
+
+
+class BuilderCapability(StrEnum):
+    """Supported feature surface for a Sphinx builder.
+
+    ``FULL_HTML`` (``html`` / ``dirhtml``): archives, Theme API validation, Atom
+    feeds, and HTML metadata are active.
+
+    ``DOCUMENT_ONLY`` (non-HTML formats such as ``text`` / ``latex``): post body
+    and post roles resolve; taxonomy roles render as inline labels; HTML-only
+    features are skipped without hard failures.
+
+    ``PARTIAL_HTML`` (other HTML builders such as ``singlehtml``): same document
+    surface as ``DOCUMENT_ONLY``, with a one-time partial-support warning.
+    Archives, Theme API validation, feeds, and HTML metadata stay disabled.
+    """
+
+    FULL_HTML = "full-html"
+    DOCUMENT_ONLY = "document-only"
+    PARTIAL_HTML = "partial-html"
+
+
+def builder_capability(builder: Builder) -> BuilderCapability:
+    """Classify *builder* into a MaatLog capability tier."""
+    name = getattr(builder, "name", None)
+    if name in {"html", "dirhtml"}:
+        return BuilderCapability.FULL_HTML
+    if getattr(builder, "format", None) != "html":
+        return BuilderCapability.DOCUMENT_ONLY
+    return BuilderCapability.PARTIAL_HTML
+
+
+def is_full_html_builder(builder: Any) -> bool:
+    """Return True when MaatLog's full HTML feature surface is enabled."""
+    return builder_capability(builder) is BuilderCapability.FULL_HTML
+
+
+def warn_partial_support_once(app: Sphinx) -> None:
+    """Emit ``maatlog.builder.partial-support`` at most once per application.
+
+    No-op for full HTML and document-only builders. Uses an application
+    attribute flag so parallel or repeated handler calls stay silent.
+    """
+    if app.__dict__.get(_PARTIAL_WARNED_ATTR):
+        return
+    if builder_capability(app.builder) is not BuilderCapability.PARTIAL_HTML:
+        return
+    app.__dict__[_PARTIAL_WARNED_ATTR] = True
+    # Sphinx appends ``[type.subtype]`` → ``[maatlog.builder.partial-support]``.
+    logger.warning(
+        "MaatLog provides limited support for builder %r: archives, Theme API "
+        "validation, Atom feeds, and HTML metadata are disabled; use html or "
+        "dirhtml for full support",
+        app.builder.name,
+        type="maatlog",
+        subtype="builder.partial-support",
+    )

maatlog/clock.py

@@ -0,0 +1,25 @@
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+
+from .errors import Diagnostic, MaatlogBuildError
+
+
+def resolve_build_time(environ: Mapping[str, str], clock: Callable[[], datetime]) -> datetime:
+    source_date_epoch = environ.get("SOURCE_DATE_EPOCH")
+    if source_date_epoch is None:
+        return clock()
+
+    try:
+        return datetime.fromtimestamp(int(source_date_epoch), UTC)
+    except OverflowError, OSError, ValueError:
+        raise MaatlogBuildError(
+            [
+                Diagnostic(
+                    code="maatlog.source-date-epoch.invalid",
+                    message="Invalid SOURCE_DATE_EPOCH",
+                    field="SOURCE_DATE_EPOCH",
+                    value=repr(source_date_epoch),
+                    expected="Unix seconds",
+                )
+            ]
+        ) from None

maatlog/config.py

@@ -0,0 +1,199 @@
+from collections.abc import Mapping, Sequence
+from enum import StrEnum
+from re import compile as re_compile
+from types import MappingProxyType
+from typing import Any, cast
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from pydantic import BaseModel, ConfigDict, field_validator
+from sphinx.config import Config
+
+from .errors import Diagnostic, MaatlogBuildError
+
+
+class TaxonomyAxis(StrEnum):
+    TAG = "tag"
+    CATEGORY = "category"
+    AUTHOR = "author"
+    MONTH = "month"
+
+
+CONFIG_VALUES = {
+    "maatlog_timezone": ("UTC", "env"),
+    "maatlog_tags": (None, "env"),
+    "maatlog_categories": (None, "env"),
+    "maatlog_authors": (None, "env"),
+    "maatlog_archive_docname": ("blog", "env"),
+    "maatlog_page_size": (10, "env"),
+    "maatlog_generate_feeds": (True, "html"),
+    "maatlog_feed_taxonomies": (("tag", "category", "author", "month"), "html"),
+    "maatlog_feed_limit": (20, "html"),
+}
+
+TAXONOMY_KEY_PATTERN = re_compile(r"[a-z0-9][a-z0-9._-]*\Z")
+
+
+class MaatlogConfig(BaseModel):
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        arbitrary_types_allowed=True,
+    )
+
+    timezone: ZoneInfo
+    tags: Mapping[str, str] | None
+    categories: Mapping[str, str] | None
+    authors: Mapping[str, str] | None
+    archive_docname: str
+    page_size: int
+    generate_feeds: bool
+    feed_taxonomies: tuple[TaxonomyAxis, ...]
+    feed_limit: int
+
+    @field_validator("tags", "categories", "authors")
+    @classmethod
+    def _freeze_taxonomy_mapping(cls, value: Mapping[str, str] | None) -> Mapping[str, str] | None:
+        if value is None:
+            return None
+        return MappingProxyType(dict(value))
+
+    @classmethod
+    def from_sphinx(cls, config: Config) -> "MaatlogConfig":
+        return cls.from_values({name: getattr(config, name) for name in CONFIG_VALUES})
+
+    @classmethod
+    def from_values(cls, values: Mapping[str, Any]) -> "MaatlogConfig":
+        resolved = {name: values.get(name, default) for name, (default, _) in CONFIG_VALUES.items()}
+        diagnostics: list[Diagnostic] = []
+
+        timezone = _validate_timezone(resolved["maatlog_timezone"], diagnostics)
+        tags = _validate_taxonomy_mapping("maatlog_tags", resolved["maatlog_tags"], diagnostics)
+        categories = _validate_taxonomy_mapping("maatlog_categories", resolved["maatlog_categories"], diagnostics)
+        authors = _validate_taxonomy_mapping("maatlog_authors", resolved["maatlog_authors"], diagnostics)
+        archive_docname = _validate_docname(resolved["maatlog_archive_docname"], diagnostics)
+        page_size = _validate_positive_int("maatlog_page_size", resolved["maatlog_page_size"], diagnostics)
+        generate_feeds = _validate_bool("maatlog_generate_feeds", resolved["maatlog_generate_feeds"], diagnostics)
+        feed_taxonomies = _validate_feed_taxonomies(resolved["maatlog_feed_taxonomies"], diagnostics)
+        feed_limit = _validate_positive_int("maatlog_feed_limit", resolved["maatlog_feed_limit"], diagnostics)
+
+        if diagnostics:
+            raise MaatlogBuildError(diagnostics)
+
+        assert timezone is not None
+        assert archive_docname is not None
+        assert page_size is not None
+        assert generate_feeds is not None
+        assert feed_taxonomies is not None
+        assert feed_limit is not None
+        return cls(
+            timezone=timezone,
+            tags=tags,
+            categories=categories,
+            authors=authors,
+            archive_docname=archive_docname,
+            page_size=page_size,
+            generate_feeds=generate_feeds,
+            feed_taxonomies=feed_taxonomies,
+            feed_limit=feed_limit,
+        )
+
+
+def _invalid(diagnostics: list[Diagnostic], field: str, value: Any, expected: str) -> None:
+    diagnostics.append(
+        Diagnostic(
+            code="maatlog.config.invalid",
+            message=f"Invalid {field}",
+            field=field,
+            value=repr(value),
+            expected=expected,
+        )
+    )
+
+
+def _validate_timezone(value: Any, diagnostics: list[Diagnostic]) -> ZoneInfo | None:
+    if not isinstance(value, str):
+        _invalid(diagnostics, "maatlog_timezone", value, "an IANA timezone name")
+        return None
+    try:
+        return ZoneInfo(value)
+    except ZoneInfoNotFoundError:
+        _invalid(diagnostics, "maatlog_timezone", value, "an IANA timezone name")
+        return None
+
+
+def _validate_taxonomy_mapping(field: str, value: Any, diagnostics: list[Diagnostic]) -> Mapping[str, str] | None:
+    if value is None:
+        return None
+    if not isinstance(value, Mapping):
+        _invalid(diagnostics, field, value, "a mapping of strings to strings")
+        return None
+    is_valid = True
+    validated: dict[str, str] = {}
+    mapping = cast(Mapping[object, object], value)
+    for key, item in mapping.items():
+        key_is_valid = isinstance(key, str) and TAXONOMY_KEY_PATTERN.fullmatch(key) is not None
+        item_is_valid = isinstance(item, str) and bool(item.strip())
+        if not key_is_valid:
+            _invalid(diagnostics, field, key, "a lowercase taxonomy key")
+            is_valid = False
+        if not item_is_valid:
+            _invalid(diagnostics, field, item, "a non-empty display name")
+            is_valid = False
+        if key_is_valid and item_is_valid:
+            validated[cast(str, key)] = cast(str, item)
+    if not is_valid:
+        return None
+    return MappingProxyType(validated)
+
+
+def _validate_docname(value: Any, diagnostics: list[Diagnostic]) -> str | None:
+    if not isinstance(value, str) or not value:
+        _invalid(diagnostics, "maatlog_archive_docname", value, "a relative Sphinx document name")
+        return None
+    segments = value.split("/")
+    if value.startswith("/") or value.endswith("/") or any(segment in {"", ".", ".."} for segment in segments):
+        _invalid(diagnostics, "maatlog_archive_docname", value, "a relative Sphinx document name")
+        return None
+    return value
+
+
+def _validate_positive_int(field: str, value: Any, diagnostics: list[Diagnostic]) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        _invalid(diagnostics, field, value, "a positive integer")
+        return None
+    return value
+
+
+def _validate_bool(field: str, value: Any, diagnostics: list[Diagnostic]) -> bool | None:
+    if not isinstance(value, bool):
+        _invalid(diagnostics, field, value, "a boolean")
+        return None
+    return value
+
+
+def _validate_feed_taxonomies(value: Any, diagnostics: list[Diagnostic]) -> tuple[TaxonomyAxis, ...] | None:
+    if not isinstance(value, (list, tuple)):
+        _invalid(diagnostics, "maatlog_feed_taxonomies", value, "a sequence of taxonomy axes")
+        return None
+    axes: list[TaxonomyAxis] = []
+    for axis in cast(Sequence[object], value):
+        if not isinstance(axis, str):
+            _invalid(diagnostics, "maatlog_feed_taxonomies", value, "tag, category, author, or month")
+            return None
+        try:
+            axes.append(TaxonomyAxis(axis))
+        except ValueError:
+            _invalid(diagnostics, "maatlog_feed_taxonomies", value, "tag, category, author, or month")
+            return None
+    return tuple(dict.fromkeys(axes))
+
+
+def validate_config(app: Any, config: Config) -> None:
+    del app
+    MaatlogConfig.from_sphinx(config)
+
+
+def register_config(app: Any) -> None:
+    for name, (default, rebuild) in CONFIG_VALUES.items():
+        app.add_config_value(name, default, rebuild)
+    app.connect("config-inited", validate_config)