sphinxnotes.render 1.0a42__py3-none-any.whl

sphinxnotes/render/sources.py

@@ -0,0 +1,129 @@
+"""
+sphinxnotes.render.sources
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:copyright: Copyright 2026 by the Shengyu Zhang.
+:license: BSD, see LICENSE for details.
+
+This module provides helpful BaseContextSource subclasses.
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, override
+from abc import abstractmethod
+from dataclasses import dataclass
+
+from docutils.parsers.rst import directives
+
+from .data import Field, RawData, Schema
+from .ctx import PendingContext, ResolvedContext
+from .render import Template
+from .pipeline import BaseContextSource, BaseContextDirective, BaseContextRole
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class UnparsedData(PendingContext):
+    """A implementation of PendingContext, contains raw data and its schema."""
+
+    raw: RawData
+    schema: Schema
+
+    @override
+    def resolve(self) -> ResolvedContext:
+        return self.schema.parse(self.raw)
+
+    @override
+    def __hash__(self) -> int:
+        return hash((self.raw, self.schema))
+
+
+class BaseRawDataSource(BaseContextSource):
+    """
+    A BaseContextRenderer subclass, which itself is a definition of raw data.
+    """
+
+    """Methods to be implemented."""
+
+    @abstractmethod
+    def current_raw_data(self) -> RawData: ...
+
+    @abstractmethod
+    def current_schema(self) -> Schema: ...
+
+    """Methods to be overrided."""
+
+    @override
+    def current_context(self) -> PendingContext | ResolvedContext:
+        return UnparsedData(self.current_raw_data(), self.current_schema())
+
+
+class BaseDataDefineDirective(BaseRawDataSource, BaseContextDirective):
+    @override
+    def current_raw_data(self) -> RawData:
+        return RawData(
+            ' '.join(self.arguments) if self.arguments else None,
+            self.options.copy(),
+            '\n'.join(self.content) if self.has_content else None,
+        )
+
+
+class BaseDataDefineRole(BaseRawDataSource, BaseContextRole):
+    @override
+    def current_raw_data(self) -> RawData:
+        return RawData(self.name, self.options.copy(), self.text)
+
+
+class StrictDataDefineDirective(BaseDataDefineDirective):
+    final_argument_whitespace = True
+
+    schema: Schema
+    template: Template
+
+    @override
+    def current_template(self) -> Template:
+        return self.template
+
+    @override
+    def current_schema(self) -> Schema:
+        return self.schema
+
+    @classmethod
+    def derive(
+        cls, name: str, schema: Schema, tmpl: Template
+    ) -> type[StrictDataDefineDirective]:
+        if not schema.name:
+            required_arguments = 0
+            optional_arguments = 0
+        elif schema.name.required:
+            required_arguments = 1
+            optional_arguments = 0
+        else:
+            required_arguments = 0
+            optional_arguments = 1
+
+        assert not isinstance(schema.attrs, Field)
+        option_spec = {}
+        for name, field in schema.attrs.items():
+            if field.required:
+                option_spec[name] = directives.unchanged_required
+            else:
+                option_spec[name] = directives.unchanged
+
+        has_content = schema.content is not None
+
+        # Generate directive class
+        return type(
+            'Strict%sDataDefineDirective' % name.title(),
+            (cls,),
+            {
+                'schema': schema,
+                'template': tmpl,
+                'has_content': has_content,
+                'required_arguments': required_arguments,
+                'optional_arguments': optional_arguments,
+                'option_spec': option_spec,
+            },
+        )

sphinxnotes/render/template.py

@@ -0,0 +1,146 @@
+"""
+sphinxnotes.template
+~~~~~~~~~~~~~~~~~~~~
+
+Rendering Jinja2 template to markup text.
+
+:copyright: Copyright 2026 by the Shengyu Zhang.
+:license: BSD, see LICENSE for details.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from pprint import pformat
+from typing import TYPE_CHECKING, override
+
+from jinja2.sandbox import SandboxedEnvironment
+from jinja2 import StrictUndefined, DebugUndefined
+
+from .data import ParsedData
+from .utils import Report
+
+if TYPE_CHECKING:
+    from typing import Any, Iterable
+    from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
+    from sphinx.builders import Builder
+
+
+@dataclass
+class TemplateRenderer:
+    text: str
+
+    def render(
+        self,
+        data: ParsedData | dict[str, Any],
+        extra: dict[str, Any] = {},
+        debug: Report | None = None,
+    ) -> str:
+        if debug:
+            debug.text('Starting Jinja template rendering...')
+
+            debug.text('Data:')
+            debug.code(pformat(data), lang='python')
+            debug.text('Extra context (just key):')
+            debug.code(pformat(list(extra.keys())), lang='python')
+
+        # Convert data to context dict.
+        if isinstance(data, ParsedData):
+            ctx = data.asdict()
+        elif isinstance(data, dict):
+            ctx = data.copy()
+
+        # Merge extra context and main context.
+        conflicts = set()
+        for name, e in extra.items():
+            if name not in ctx:
+                ctx[name] = e
+            else:
+                conflicts.add(name)
+
+        text = self._render(ctx, debug=debug is not None)
+
+        return text
+
+    def _render(self, ctx: dict[str, Any], debug: bool = False) -> str:
+        extensions = [
+            'jinja2.ext.loopcontrols',  # enable {% break %}, {% continue %}
+            'jinja2.ext.do',  # enable {% do ... %}
+        ]
+        if debug:
+            extensions.append('jinja2.ext.debug')
+
+        env = _JinjaEnv(
+            undefined=DebugUndefined if debug else StrictUndefined,
+            extensions=extensions,
+        )
+        # TODO: cache jinja env
+
+        return env.from_string(self.text).render(ctx)
+
+    def _report_self(self, reporter: Report) -> None:
+        reporter.text('Template:')
+        reporter.code(self.text, lang='jinja')
+
+
+class _JinjaEnv(SandboxedEnvironment):
+    _builder: Builder
+    # List of user defined filter factories.
+    _filter_factories = {}
+
+    @classmethod
+    def _on_builder_inited(cls, app: Sphinx):
+        cls._builder = app.builder
+
+    @classmethod
+    def _on_build_finished(cls, app: Sphinx, exception): ...
+
+    @classmethod
+    def add_filter(cls, name: str, ff):
+        cls._filter_factories[name] = ff
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        for name, factory in self._filter_factories.items():
+            self.filters[name] = factory(self._builder.env)
+
+    @override
+    def is_safe_attribute(self, obj, attr, value=None):
+        """
+        The sandboxed environment will call this method to check if the
+        attribute of an object is safe to access. Per default all attributes
+        starting with an underscore are considered private as well as the
+        special attributes of internal python objects as returned by the
+        is_internal_attribute() function.
+
+        .. seealso:: :class:`..utils.ctxproxy.Proxy`
+        """
+        return super().is_safe_attribute(obj, attr, value)
+
+
+def _roles_filter(env: BuildEnvironment):
+    """
+    Fetch artwork picture by ID and install theme to Sphinx's source directory,
+    return the relative URI of current doc root.
+    """
+
+    def _filter(value: Iterable[str], role: str) -> Iterable[str]:
+        """
+        A heplfer filter for converting list of string to list of role.
+
+        For example::
+
+            {{ ["foo", "bar"] | roles("doc") }}
+
+        Produces ``[":doc:`foo`", ":doc:`bar`"]``.
+        """
+        return map(lambda x: ':%s:`%s`' % (role, x), value)
+
+    return _filter
+
+
+def setup(app: Sphinx):
+    app.connect('builder-inited', _JinjaEnv._on_builder_inited)
+    app.connect('build-finished', _JinjaEnv._on_build_finished)
+
+    _JinjaEnv.add_filter('roles', _roles_filter)

sphinxnotes/render/utils/__init__.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar, cast
+import pickle
+import traceback
+
+from docutils import nodes
+from docutils.frontend import get_default_settings
+from docutils.parsers.rst import Parser
+from docutils.parsers.rst.states import Struct, Inliner as RstInliner
+from docutils.utils import new_document
+from sphinx.util import logging
+
+if TYPE_CHECKING:
+    from typing import Literal, Iterable, Callable
+    from sphinx.util.docutils import SphinxRole
+
+logger = logging.getLogger(__name__)
+
+
+def parse_text_to_nodes(text: str) -> list[nodes.Node]:
+    """
+    Utility for parsing standard reStructuredText (without Sphinx stuffs) to nodes.
+    Used when there is not a SphinxDirective/SphinxRole available.
+    """
+    # TODO: markdown support
+    document = new_document('<string>', settings=get_default_settings(Parser))  # type: ignore
+    Parser().parse(text, document)
+    return document.children
+
+
+def role_parse_text_to_nodes(self: SphinxRole, text: str) -> list[nodes.Node]:
+    """
+    Utility for parsing reStructuredText (without Sphinx stuffs) to nodes in
+    SphinxRole Context.
+    """
+    memo = Struct(
+        document=self.inliner.document,
+        reporter=self.inliner.reporter,
+        language=self.inliner.language,
+    )
+    ns, msgs = self.inliner.parse(text, self.lineno, memo, self.inliner.parent)
+    return ns + msgs
+
+
+_Node = TypeVar('_Node', bound=nodes.Node)
+
+
+def find_parent(node: nodes.Node | None, typ: type[_Node]) -> _Node | None:
+    if node is None or isinstance(node, typ):
+        return node
+    return find_parent(node.parent, typ)
+
+
+def find_current_section(node: nodes.Node | None) -> nodes.section | None:
+    return find_parent(node, nodes.section)
+
+
+def find_current_document(node: nodes.Node | None) -> nodes.document | None:
+    return find_parent(node, nodes.document)
+
+
+def find_first_child(node: nodes.Element, cls: type[_Node]) -> _Node | None:
+    if (index := node.first_child_matching_class(cls)) is None:
+        return None
+    return cast(_Node, node[index])
+
+
+def find_titular_node_upward(node: nodes.Element | None) -> nodes.Element | None:
+    if node is None:
+        return None
+    if isinstance(node, (nodes.section, nodes.sidebar)):
+        if title := find_first_child(node, nodes.title):
+            return title
+    if isinstance(node, nodes.definition_list_item):
+        if term := find_first_child(node, nodes.term):
+            return term
+    if isinstance(node, nodes.field):
+        if field := find_first_child(node, nodes.field_name):
+            return field
+    if isinstance(node, nodes.list_item):
+        if para := find_first_child(node, nodes.paragraph):
+            return para
+    return find_titular_node_upward(node.parent)
+
+
+def find_nearest_block_element(node: nodes.Node | None) -> nodes.Element | None:
+    """
+    Finds the nearest ancestor that is suitable for block-level placement.
+    Typically a Body element (paragraph, table, list) or Structural element (section).
+    """
+    while node:
+        if isinstance(node, (nodes.Body, nodes.Structural, nodes.document)):
+            return node
+        node = node.parent
+    return None
+
+
+class Report(nodes.system_message):
+    type Type = Literal['DEBUG', 'INFO', 'WARNING', 'ERROR']
+
+    title: str
+
+    def __init__(
+        self, title: str, typ: Type = 'DEBUG', *children, **attributes
+    ) -> None:
+        super().__init__(title + ':', type=typ, level=2, *children, **attributes)
+        self.title = title
+
+    def empty(self) -> bool:
+        # title is the only children
+        return len(self.children) <= 1
+
+    def node(self, node: nodes.Node) -> None:
+        self += node
+        self.log(f'report: {node.astext()}')
+
+    def log(self, msg: str) -> None:
+        if self['type'] in 'ERROR':
+            logger.error(msg)
+        elif self['type'] in 'WARNING':
+            logger.warning(msg)
+
+    def text(self, text: str) -> None:
+        self.node(nodes.paragraph(text, text))
+
+    def code(self, code: str, lang: str | None = None) -> None:
+        blk = nodes.literal_block(code, code)
+        if lang:
+            blk['language'] = lang
+        self.node(blk)
+
+    def list(self, lines: Iterable[str]) -> None:
+        bullet_list = nodes.bullet_list(bullet='*')
+
+        for line in lines:
+            list_item = nodes.list_item()
+            para = nodes.paragraph()
+            para += nodes.Text(line)
+            list_item += para
+            bullet_list += list_item
+
+        self.node(bullet_list)
+
+    def traceback(self) -> None:
+        # https://pygments.org/docs/lexers/#pygments.lexers.python.PythonTracebackLexer
+        self.code(traceback.format_exc(), lang='pytb')
+
+    def exception(self, e: Exception) -> None:
+        # https://pygments.org/docs/lexers/#pygments.lexers.python.PythonTracebackLexer
+        self.code(str(e), lang='pytb')
+
+    def is_error(self) -> bool:
+        return self['type'] == 'ERROR'
+
+    type Inliner = RstInliner | tuple[nodes.document, nodes.Element]
+
+    def problematic(self, inliner: Inliner) -> nodes.problematic:
+        """Create a crossed referenced inline problematic nodes."""
+
+        if isinstance(inliner, RstInliner):
+            prb = inliner.problematic('', '', self)
+        else:
+            # See also :meth:`docutils.parsers.rst.Inliner.problematic`.
+            msgid = inliner[0].set_id(self, inliner[1])
+            prb = nodes.problematic('', '', refid=msgid)
+            prbid = inliner[0].set_id(prb)
+            self.add_backref(prbid)
+
+        prb += nodes.Text(' ')
+        prb += nodes.superscript(self.title, self.title)
+
+        return prb
+
+
+@dataclass
+class Reporter:
+    """A helper class for storing :class:`Report` to nodes."""
+
+    node: nodes.Element
+
+    @property
+    def reports(self) -> list[Report]:
+        """Use ``node += Report('xxx')`` to append a report."""
+        return [x for x in self.node if isinstance(x, Report)]
+
+    def append(self, report: Report) -> None:
+        self.node += report
+
+    def clear(self, pred: Callable[[Report], bool] | None = None) -> list[Report]:
+        """Clear report children from node if pred returns True."""
+        msgs = []
+        for report in self.reports:
+            if not pred or pred(report):
+                msgs.append(report)
+                self.node.remove(report)
+        return msgs
+
+    def clear_empty(self) -> list[Report]:
+        return self.clear(lambda x: x.empty())
+
+
+class Unpicklable:
+    """
+    Make objects unpickable to prevent them from being stored in the
+    on-disk doctree.
+    """
+
+    def __reduce_ex__(self, protocol):
+        # Prevent pickling explicitly
+        raise pickle.PicklingError(f'{type(self)} is unpicklable')

sphinxnotes/render/utils/ctxproxy.py

@@ -0,0 +1,144 @@
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable
+from types import MappingProxyType
+
+from docutils import nodes
+from sphinx.util import logging
+from sphinx.config import Config as SphinxConfig
+
+from ..utils import find_first_child
+
+
+logger = logging.getLogger(__name__)
+
+
+def proxy_property(func: Callable[[Any], Any]) -> property:
+    @wraps(func)
+    def wrapped(self: Proxy) -> Any:
+        return self._normalize(func(self))
+
+    return property(wrapped)
+
+
+# FIXME: Unpicklable?
+@dataclass(frozen=True)
+class Proxy:
+    """
+    Proxy complex objects into context for convenient and secure access within
+    Jinja templates.
+
+    Porxy might point to very complex, unpredictable objects, therefore
+    disallowing pickling is necessary.
+    """
+
+    _obj: Any
+
+    def __getattr__(self, name: str) -> Any:
+        # Internal attr is not accessable.
+        if name.startswith('_'):
+            raise AttributeError(name)
+
+        v = getattr(self._obj, name)
+        if callable(v):
+            # Deny callable attr for safety.
+            raise AttributeError(name)
+
+        return self._wrap(v)
+
+    @staticmethod
+    def _wrap(v: Any) -> Any:
+        cls = SPECIFIC_TYPE_REGISTRY.get(type(v))
+        if cls:
+            return cls(v)
+        for types, cls in TYPE_REGISTRY.items():
+            if isinstance(v, types):
+                return cls(v)
+        return v
+
+    @staticmethod
+    def _normalize(val: Any) -> Any:
+        if val is None or isinstance(val, (str, int, float, bool)):
+            return val
+
+        if isinstance(val, Proxy):
+            return val
+
+        wrapped_val = Proxy._wrap(val)
+        if wrapped_val is not val:
+            return wrapped_val
+
+        if isinstance(val, (set, frozenset)):
+            return frozenset(Proxy._normalize(x) for x in val)
+        if isinstance(val, (list, tuple)):
+            return tuple(Proxy._normalize(x) for x in val)
+        if isinstance(val, dict):
+            copied = {k: Proxy._normalize(v) for k, v in val.items()}
+            return MappingProxyType(copied)
+        return str(val)
+
+
+@dataclass(frozen=True)
+class Node(Proxy):
+    _obj: nodes.Element
+
+    @proxy_property
+    def attrs(self) -> dict[str, str]:
+        """Shortcut to :attr:`nodes.Element.attributes`."""
+        return self._obj.attributes
+
+    def __str__(self) -> str:
+        return self._obj.astext()
+
+
+@dataclass(frozen=True)
+class NodeWithTitle(Node):
+    @proxy_property
+    def title(self) -> Node | None:
+        return find_first_child(self._obj, nodes.Titular)  # type: ignore
+
+
+@dataclass(frozen=True)
+class Section(NodeWithTitle):
+    _obj: nodes.section
+
+    @proxy_property
+    def sections(self) -> tuple['Section', ...]:
+        sect_nodes = self._obj[0].findall(
+            nodes.section, descend=False, ascend=False, siblings=True
+        )
+        return list(sect_nodes)
+
+
+@dataclass(frozen=True)
+class Document(NodeWithTitle):
+    _obj: nodes.document
+
+    def _top_section(self) -> Section:
+        section = self._obj.next_node(nodes.section)
+        assert section
+        return Section(section)
+
+    @proxy_property
+    def sections(self) -> tuple[Section, ...]:
+        return self._top_section().sections
+
+
+@dataclass(frozen=True)
+class Config(Proxy):
+    _obj: SphinxConfig
+
+
+TYPE_REGISTRY: dict[type | tuple[type, ...], type[Proxy]] = {
+    nodes.Node: Node,
+}
+
+SPECIFIC_TYPE_REGISTRY: dict[type, type[Proxy]] = {
+    nodes.document: Document,
+    nodes.section: Section,
+    SphinxConfig: Config,
+}
+
+
+def proxy(v: Any) -> Proxy:
+    return Proxy._wrap(v)