wenmode 0.1.0__py3-none-any.whl

wenmode/__init__.py

@@ -0,0 +1,17 @@
+from .parser import Parser, StreamingUnsupportedError
+from .renderers import HTMLRenderer, MarkdownRenderer, RSTRenderer
+from .wenmode import Wenmode
+
+__version__ = '0.1.0'
+__homepage__ = 'https://wenmode.lepture.com/'
+__author__ = 'Hsiaoming Yang <me@lepture.com>'
+__license__ = 'BSD-3-Clause'
+
+__all__ = [
+    'HTMLRenderer',
+    'MarkdownRenderer',
+    'RSTRenderer',
+    'Parser',
+    'StreamingUnsupportedError',
+    'Wenmode',
+]

wenmode/directives/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .abbr import Abbreviation
+from .admonition import Admonition
+from .details import Details
+from .figure import Figure
+from .toc import TableOfContents
+
+__all__ = ['Abbreviation', 'Admonition', 'Details', 'Figure', 'TableOfContents']

wenmode/directives/abbr.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from wenmode.nodes import TextDirective
+
+if TYPE_CHECKING:
+    from wenmode.renderers.html import HTMLRenderContext, HTMLRenderer
+
+
+class Abbreviation:
+    """Render text directives as HTML ``abbr`` elements.
+
+    :param names: Directive names handled by this renderer.
+    """
+
+    node_type = 'textDirective'
+
+    def __init__(self, names: Iterable[str] = ('abbr',)) -> None:
+        self.names = frozenset(names)
+
+    def render(self, renderer: HTMLRenderer, node: TextDirective, context: HTMLRenderContext) -> str:
+        attributes = dict(node.attributes or {})
+        if 'title' not in attributes:
+            return renderer.render_children(node.children, context)
+        return f'<abbr{renderer.render_attrs(attributes)}>{renderer.render_children(node.children, context)}</abbr>'

wenmode/directives/admonition.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from wenmode.nodes import ContainerDirective
+
+from .util import append_class, split_directive_label
+
+if TYPE_CHECKING:
+    from wenmode.renderers.html import HTMLRenderContext, HTMLRenderer
+
+
+class Admonition:
+    """Render container directives as admonition ``aside`` elements.
+
+    :param names: Directive names handled by this renderer.
+    """
+
+    node_type = 'containerDirective'
+
+    def __init__(self, names: Iterable[str] = ('note', 'tip', 'caution', 'danger')) -> None:
+        self.names = frozenset(names)
+
+    def render(self, renderer: HTMLRenderer, node: ContainerDirective, context: HTMLRenderContext) -> str:
+        label, children = split_directive_label(node)
+        class_name = f'admonition admonition-{node.name}'
+        attrs = dict(node.attributes or {})
+        attrs['class'] = append_class(attrs.get('class'), class_name)
+
+        parts = [f'<aside{renderer.render_attrs(attrs)}>\n']
+        if label is not None:
+            parts.append(f'<p class="admonition-title">{renderer.render_children(label.children, context)}</p>\n')
+        parts.append(renderer.render_children(children, context))
+        parts.append('</aside>\n')
+        return ''.join(parts)

wenmode/directives/details.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from wenmode.nodes import ContainerDirective
+
+from .util import split_directive_label
+
+if TYPE_CHECKING:
+    from wenmode.renderers.html import HTMLRenderContext, HTMLRenderer
+
+
+class Details:
+    """Render ``details`` container directives as HTML ``details`` elements.
+
+    :param names: Directive names handled by this renderer.
+    """
+
+    node_type = 'containerDirective'
+
+    def __init__(self, names: Iterable[str] = ('details',)) -> None:
+        self.names = frozenset(names)
+
+    def render(self, renderer: HTMLRenderer, node: ContainerDirective, context: HTMLRenderContext) -> str:
+        label, children = split_directive_label(node)
+        parts = [f'<details{renderer.render_attrs(node.attributes or {})}>\n']
+        if label is not None:
+            parts.append(f'<summary>{renderer.render_children(label.children, context)}</summary>\n')
+        parts.append(renderer.render_children(children, context))
+        parts.append('</details>\n')
+        return ''.join(parts)

wenmode/directives/figure.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from wenmode.nodes import ContainerDirective
+
+from .util import split_directive_label
+
+if TYPE_CHECKING:
+    from wenmode.renderers.html import HTMLRenderContext, HTMLRenderer
+
+
+class Figure:
+    """Render ``figure`` container directives as HTML ``figure`` elements.
+
+    :param names: Directive names handled by this renderer.
+    """
+
+    node_type = 'containerDirective'
+
+    def __init__(self, names: Iterable[str] = ('figure',)) -> None:
+        self.names = frozenset(names)
+
+    def render(self, renderer: HTMLRenderer, node: ContainerDirective, context: HTMLRenderContext) -> str:
+        label, children = split_directive_label(node)
+        parts = [
+            f'<figure{renderer.render_attrs(node.attributes or {})}>\n',
+            renderer.render_children(children, context),
+        ]
+        if label is not None:
+            parts.append(f'<figcaption>{renderer.render_children(label.children, context)}</figcaption>\n')
+        parts.append('</figure>\n')
+        return ''.join(parts)

wenmode/directives/toc.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from wenmode.headings import plain_text
+from wenmode.nodes import LeafDirective
+from wenmode.toc import collect_toc, render_toc_list
+
+from .util import append_class
+
+if TYPE_CHECKING:
+    from wenmode.renderers.html import HTMLRenderContext, HTMLRenderer
+
+
+class TableOfContents:
+    """Render ``toc`` leaf directives as HTML tables of contents.
+
+    :param names: Directive names handled by this renderer.
+    """
+
+    node_type = 'leafDirective'
+
+    def __init__(self, names: Iterable[str] = ('toc',)) -> None:
+        self.names = frozenset(names)
+
+    def render(self, renderer: HTMLRenderer, node: LeafDirective, context: HTMLRenderContext) -> str:
+        if context.root is None:
+            return ''
+
+        attributes = dict(node.attributes or {})
+        min_depth = parse_depth(attributes, ('min', 'min-depth', 'min_depth'), 1)
+        max_depth = parse_depth(attributes, ('max', 'max-depth', 'max_depth'), 6)
+        label_attribute = attributes.pop('label') if 'label' in attributes else None
+        label = plain_text(node.children) or label_attribute or 'Table of contents'
+        items = collect_toc(context.root, min_depth=min_depth, max_depth=max_depth)
+        if not items:
+            return ''
+
+        attributes.pop('min', None)
+        attributes.pop('min-depth', None)
+        attributes.pop('min_depth', None)
+        attributes.pop('max', None)
+        attributes.pop('max-depth', None)
+        attributes.pop('max_depth', None)
+        attributes['aria-label'] = label
+        attributes['class'] = append_class(attributes.get('class'), 'toc')
+        return f'<nav{renderer.render_attrs(attributes)}>\n{render_toc_list(items)}</nav>\n'
+
+
+def parse_depth(attributes: dict[str, str], keys: tuple[str, ...], default: int) -> int:
+    for key in keys:
+        value = attributes.get(key)
+        if value is None:
+            continue
+        try:
+            return max(1, min(6, int(value)))
+        except ValueError:
+            return default
+    return default

wenmode/directives/util.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from wenmode.nodes import ContainerDirective, Node, Paragraph
+
+
+def split_directive_label(node: ContainerDirective) -> tuple[Paragraph | None, list[Node]]:
+    """Split a container directive into its label paragraph and body nodes."""
+    if node.children and isinstance(node.children[0], Paragraph) and node.children[0].data == {'directiveLabel': True}:
+        return node.children[0], node.children[1:]
+    return None, node.children
+
+
+def append_class(current: str | None, value: str) -> str:
+    """Append one CSS class value to an existing class attribute."""
+    return f'{current} {value}' if current else value

wenmode/headings.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import re
+import string
+
+from .nodes import Heading, Image, Literal, Node, Parent
+
+SLUG_PUNCTUATION = ''.join(char for char in string.punctuation if char not in '-_')
+SLUG_PUNCTUATION_RE = re.compile('[' + re.escape(SLUG_PUNCTUATION) + ']')
+SLUG_SPACE_RE = re.compile(r'\s+')
+
+
+class Slugger:
+    """Generate unique slug IDs for headings."""
+
+    name = 'default'
+
+    def __init__(self) -> None:
+        self.seen: dict[str, int] = {}
+
+    def slug(self, value: str) -> str:
+        """Return a unique slug for a heading title."""
+        base = slugify(value)
+        index = self.seen.get(base, 0)
+        self.seen[base] = index + 1
+        if index == 0:
+            return base
+        return f'{base}-{index}'
+
+    def use(self, value: str) -> None:
+        """Mark an existing slug as already used."""
+        self.seen[value] = self.seen.get(value, 0) + 1
+
+
+def add_heading_ids(
+    node: Node,
+    *,
+    slugger: Slugger,
+    min_depth: int = 1,
+    max_depth: int = 6,
+    overwrite: bool = False,
+) -> None:
+    """Add generated IDs to heading nodes in a tree.
+
+    Existing heading IDs are preserved unless ``overwrite`` is ``True``.
+
+    :param node: Root or subtree to update.
+    :param slugger: Slug generator used to create unique IDs.
+    :param min_depth: Minimum heading depth to update.
+    :param max_depth: Maximum heading depth to update.
+    :param overwrite: Whether to replace existing heading IDs.
+    """
+    for heading in iter_headings(node):
+        if not (min_depth <= heading.depth <= max_depth):
+            continue
+        current_id = heading.data.get('id') if heading.data else None
+        if isinstance(current_id, str) and not overwrite:
+            slugger.use(current_id)
+            continue
+        if heading.data is None:
+            heading.data = {}
+        heading.data['id'] = slugger.slug(plain_text(heading.children))
+
+
+def iter_headings(node: Node) -> list[Heading]:
+    """Return all heading nodes under a node."""
+    headings: list[Heading] = []
+    collect_headings(node, headings)
+    return headings
+
+
+def collect_headings(node: Node, headings: list[Heading]) -> None:
+    """Append heading descendants of ``node`` to ``headings``."""
+    if isinstance(node, Heading):
+        headings.append(node)
+    children = getattr(node, 'children', None)
+    if isinstance(children, list):
+        for child in children:
+            collect_headings(child, headings)
+
+
+def plain_text(nodes: list[Node]) -> str:
+    """Return the plain text content of a node list."""
+    return ''.join(plain_text_node(node) for node in nodes)
+
+
+def plain_text_node(node: Node) -> str:
+    """Return the plain text content of one node."""
+    if isinstance(node, Image):
+        return node.alt
+    if isinstance(node, Literal):
+        return node.value
+    if isinstance(node, Parent):
+        return plain_text(node.children)
+    label = getattr(node, 'label', None)
+    if isinstance(label, str):
+        return label
+    identifier = getattr(node, 'identifier', None)
+    if isinstance(identifier, str):
+        return identifier
+    return ''
+
+
+def slugify(value: str) -> str:
+    """Convert text into a URL-friendly slug."""
+    slug = value.strip().lower()
+    slug = SLUG_PUNCTUATION_RE.sub('', slug)
+    slug = SLUG_SPACE_RE.sub('-', slug)
+    slug = slug.strip('-')
+    return slug or 'section'

wenmode/nodes.py

@@ -0,0 +1,358 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Node:
+    """Base class for all Wenmode AST nodes.
+
+    :param type: mdast-compatible node type name.
+    :param data: Optional extension data used by transforms or renderers.
+    """
+
+    type: str
+    data: dict[str, Any] | None = None
+
+    def to_ast(self) -> dict[str, Any]:
+        """Convert this node and its children to plain Python data.
+
+        :returns: A dictionary made from strings, numbers, lists, and nested
+            dictionaries.
+        """
+        data: dict[str, Any] = {'type': self.type}
+        for key, value in self.__dict__.items():
+            if key == 'type' or key.startswith('_') or value is None:
+                continue
+            if isinstance(value, list):
+                data[key] = [item.to_ast() if isinstance(item, Node) else item for item in value]
+            elif isinstance(value, Node):
+                data[key] = value.to_ast()
+            else:
+                data[key] = value
+        return data
+
+
+@dataclass
+class Parent(Node):
+    """Base class for nodes that contain child nodes."""
+
+    children: list[Node] = field(default_factory=list)
+
+
+@dataclass
+class Literal(Node):
+    """Base class for nodes that store literal text."""
+
+    value: str = ''
+
+
+@dataclass
+class Root(Parent):
+    """Document root node."""
+
+    _footnote_definitions: dict[str, FootnoteDefinition] | None = field(default=None, repr=False)
+    type: str = 'root'
+
+    @property
+    def footnote_definitions(self) -> dict[str, FootnoteDefinition] | None:
+        """Collected footnote definitions, if the footnote transform ran."""
+        return self._footnote_definitions
+
+    @footnote_definitions.setter
+    def footnote_definitions(self, definitions: dict[str, FootnoteDefinition] | None) -> None:
+        self._footnote_definitions = definitions
+
+
+@dataclass
+class Paragraph(Parent):
+    """Paragraph node."""
+
+    type: str = 'paragraph'
+
+
+@dataclass
+class Heading(Parent):
+    """Heading node.
+
+    :param depth: Heading depth from 1 through 6.
+    """
+
+    depth: int = 1
+    type: str = 'heading'
+
+
+@dataclass
+class Blockquote(Parent):
+    """Block quote container node."""
+
+    type: str = 'blockquote'
+
+
+@dataclass
+class BlockSpoiler(Parent):
+    """Block spoiler container node."""
+
+    type: str = 'blockSpoiler'
+
+
+@dataclass
+class List(Parent):
+    """Ordered or unordered list node."""
+
+    ordered: bool = False
+    start: int | None = None
+    spread: bool = False
+    type: str = 'list'
+
+
+@dataclass
+class ListItem(Parent):
+    """List item node."""
+
+    checked: bool | None = None
+    spread: bool = False
+    type: str = 'listItem'
+
+
+@dataclass
+class DefinitionList(Parent):
+    """Definition list node."""
+
+    type: str = 'definitionList'
+
+
+@dataclass
+class DefinitionTerm(Parent):
+    """Definition term node."""
+
+    type: str = 'definitionTerm'
+
+
+@dataclass
+class DefinitionDescription(Parent):
+    """Definition description node."""
+
+    spread: bool = False
+    type: str = 'definitionDescription'
+
+
+@dataclass
+class Code(Literal):
+    """Fenced or indented code block node."""
+
+    lang: str | None = None
+    meta: str | None = None
+    type: str = 'code'
+
+
+@dataclass
+class Math(Literal):
+    """Display math block node."""
+
+    type: str = 'math'
+
+
+@dataclass
+class ThematicBreak(Node):
+    """Thematic break node."""
+
+    type: str = 'thematicBreak'
+
+
+@dataclass
+class Html(Literal):
+    """Raw HTML node."""
+
+    type: str = 'html'
+
+
+@dataclass
+class Text(Literal):
+    """Plain text node."""
+
+    _parse_emphasis: bool = True
+    type: str = 'text'
+
+
+@dataclass
+class InlineCode(Literal):
+    """Inline code span node."""
+
+    type: str = 'inlineCode'
+
+
+@dataclass
+class InlineMath(Literal):
+    """Inline math node."""
+
+    type: str = 'inlineMath'
+
+
+@dataclass
+class Strong(Parent):
+    """Strong emphasis node."""
+
+    type: str = 'strong'
+
+
+@dataclass
+class Emphasis(Parent):
+    """Emphasis node."""
+
+    type: str = 'emphasis'
+
+
+@dataclass
+class Delete(Parent):
+    """Deleted text node."""
+
+    type: str = 'delete'
+
+
+@dataclass
+class Mark(Parent):
+    """Highlighted text node."""
+
+    type: str = 'mark'
+
+
+@dataclass
+class Insert(Parent):
+    """Inserted text node."""
+
+    type: str = 'insert'
+
+
+@dataclass
+class Superscript(Parent):
+    """Superscript node."""
+
+    type: str = 'superscript'
+
+
+@dataclass
+class Subscript(Parent):
+    """Subscript node."""
+
+    type: str = 'subscript'
+
+
+@dataclass
+class Ruby(Node):
+    """Ruby annotation node."""
+
+    segments: list[dict[str, str]] = field(default_factory=list)
+    type: str = 'ruby'
+
+
+@dataclass
+class InlineSpoiler(Parent):
+    """Inline spoiler node."""
+
+    type: str = 'inlineSpoiler'
+
+
+@dataclass
+class Abbreviation(Parent):
+    """Abbreviation node."""
+
+    title: str = ''
+    type: str = 'abbreviation'
+
+
+@dataclass
+class Table(Parent):
+    """Table node."""
+
+    align: list[str | None] = field(default_factory=list)
+    type: str = 'table'
+
+
+@dataclass
+class TableRow(Parent):
+    """Table row node."""
+
+    type: str = 'tableRow'
+
+
+@dataclass
+class TableCell(Parent):
+    """Table cell node."""
+
+    type: str = 'tableCell'
+
+
+@dataclass
+class Link(Parent):
+    """Link node."""
+
+    url: str = ''
+    title: str | None = None
+    type: str = 'link'
+
+
+@dataclass
+class Image(Node):
+    """Image node."""
+
+    url: str = ''
+    alt: str = ''
+    title: str | None = None
+    type: str = 'image'
+
+
+@dataclass
+class Break(Node):
+    """Hard line break node."""
+
+    type: str = 'break'
+
+
+@dataclass
+class FootnoteReference(Node):
+    """Footnote reference node."""
+
+    identifier: str = ''
+    label: str = ''
+    type: str = 'footnoteReference'
+
+
+@dataclass
+class FootnoteDefinition(Parent):
+    """Footnote definition node."""
+
+    identifier: str = ''
+    label: str = ''
+    type: str = 'footnoteDefinition'
+
+
+@dataclass
+class TextDirective(Parent):
+    """Inline directive node."""
+
+    name: str = ''
+    attributes: dict[str, str] | None = None
+    type: str = 'textDirective'
+
+
+@dataclass
+class LeafDirective(Parent):
+    """Leaf block directive node."""
+
+    name: str = ''
+    attributes: dict[str, str] | None = None
+    type: str = 'leafDirective'
+
+
+@dataclass
+class ContainerDirective(Parent):
+    """Container block directive node."""
+
+    name: str = ''
+    attributes: dict[str, str] | None = None
+    type: str = 'containerDirective'
+
+
+DirectiveNode = TextDirective | LeafDirective | ContainerDirective