sphinxnotes-render 1.0b4__tar.gz → 1.0b5__tar.gz

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/.cruft.json

@@ -9,7 +9,7 @@
       "full_name": "sphinxnotes-render",
       "author": "Shengyu Zhang",
       "description": "Define, constrain, and render data in Sphinx documentation",
-      "version": "1.0a0",
+      "version": "1.0b4",
       "github_owner": "sphinx-notes",
       "github_repo": "data",
       "pypi_name": "sphinxnotes-render",

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/.gitignore

@@ -135,3 +135,4 @@ poetry.lock
 docs/_build/
 # sphinxnotes-any >= 2.5
 docs/.any*
+.worktrees/

{sphinxnotes_render-1.0b4/src/sphinxnotes_render.egg-info → sphinxnotes_render-1.0b5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-render
-Version: 1.0b4
+Version: 1.0b5
 Summary: Define, constrain, and render data in Sphinx documentation
 Author: Shengyu Zhang
 Maintainer: Shengyu Zhang

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/docs/api.rst

@@ -55,22 +55,22 @@ Context refers to the dynamic content of a Jinja template. It can be:
   Our dedicated data type (:py:class:`sphinxnotes.render.ParsedData`), or any
   Python ``dict``.
 
-:py:class:`~sphinxnotes.render.PendingContext`:
+:py:class:`~sphinxnotes.render.UnresolvedContext`:
    Context that is not yet available. For example, it may contain
    :py:class:`unparsed data <sphinxnotes.render.RawData>`,
    remote data, and more.
 
-   :py:class:`PendingContext` can be resolved to
+   :py:class:`UnresolvedContext` can be resolved to
    :py:class:`~sphinxnotes.render.ResolvedContext` by calling
-   :py:meth:`~sphinxnotes.render.PendingContext.resolve`.
+   :py:meth:`~sphinxnotes.render.UnresolvedContext.resolve`.
 
 .. autotype:: sphinxnotes.render.ResolvedContext
 
-.. autoclass:: sphinxnotes.render.PendingContext
+.. autoclass:: sphinxnotes.render.UnresolvedContext
    :members: resolve
 
-``PendingContext`` Implementations
-----------------------------------
+``UnresolvedContext`` Implementations
+-------------------------------------
 
 .. autoclass:: sphinxnotes.render.UnparsedData
    :show-inheritance:
@@ -92,24 +92,16 @@ Extra Context
 =============
 
 See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
-``sphinx``, plus usage examples.
+``env``, plus usage examples.
 
 .. autodecorator:: sphinxnotes.render.extra_context
 
-.. autoclass:: sphinxnotes.render.ParsingPhaseExtraContext
-   :members: phase, generate
+.. autoclass:: sphinxnotes.render.ExtraContext
+   :members: generate
    :undoc-members:
 
-.. autoclass:: sphinxnotes.render.ParsedPhaseExtraContext
-   :members: phase, generate
-   :undoc-members:
-
-.. autoclass:: sphinxnotes.render.ResolvingPhaseExtraContext
-   :members: phase, generate
-   :undoc-members:
-
-.. autoclass:: sphinxnotes.render.GlobalExtraContext
-   :members: phase, generate
+.. autoclass:: sphinxnotes.render.ExtraContextRequest
+   :members:
    :undoc-members:
 
 Filters

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/docs/conf.py

@@ -14,7 +14,7 @@ author = 'Shengyu Zhang'
 copyright = "2025, " + author
 
 # The full version, including alpha/beta/rc tags
-version = release = '1.0a0'
+version = release = '1.0b4'
 
 # -- General configuration ---------------------------------------------------
 

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/docs/conf.rst

@@ -25,7 +25,5 @@ The extension provides the following configuration:
      - ``text`` (str): the Jinja2 template text.
      - ``on`` (str, optional): same as :rst:dir:`data.template:on`
      - ``debug`` (bool, optional): same as :rst:dir:`data.template:debug`
-     - ``extra`` (list[str], optional): same as :rst:dir:`data.template:extra`
 
    See :ref:`usage-custom-directive` for example.
-

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/docs/ext.rst

@@ -69,11 +69,8 @@ Extending Extra Contexts
 Extra contexts are registered by a
 :py:deco:`sphinxnotes.render.extra_context` class decorator.
 
-The decorated class must be one of the following classes:
-:py:class:`~sphinxnotes.render.ParsingPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.ParsedPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.ResolvingPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.GlobalExtraContext`.
+The decorated class must be a subclass of
+:py:class:`~sphinxnotes.render.ExtraContext`.
 
 .. literalinclude:: ../tests/roots/test-extra-context/conf.py
    :language: python
@@ -88,7 +85,6 @@ The decorated class must be one of the following classes:
    :style: grid
 
    .. data.render::
-      :extra: cat
 
       {{ load_extra('cat').name }}
 

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/docs/tmpl.rst

@@ -158,20 +158,13 @@ sources (such as Sphinx application, JSON file, and etc.). Unlike main context
 which comes from the directive/role itself, extra context lets you fetch data
 that was prepared beforehand.
 
-Extra contexts are typically generated on demand at different construction stages,
-so you need to declare them in advance, and load it in the template using the
-``load_extra()`` function:
-
-The way of declaring extra context is vary depending on the extension you use.
-For ``sphinxnotes.render.ext`` extension, :rst:dir:`data.template:extra`,
-:rst:dir:`data.render:extra` and the ``templat.extra`` field of
-:confval:`render_ext_data_define_directives` are for this.
+Extra contexts are generated on demand. Load them in the template using the
+``load_extra()`` function.
 
 .. example::
    :style: grid
 
    .. data.render::
-      :extra: doc
 
       {% set doc = load_extra('doc') %}
 
@@ -191,7 +184,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: app
 
          {% set app = load_extra('app') %}
 
@@ -207,7 +199,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: env
 
          {% set env = load_extra('env') %}
 
@@ -215,7 +206,7 @@ The following extra contexts are available:
          documents found.
 
 ``markup``
-   :Phase: parsing and later
+   :Phase: :term:`parsing`
 
    Information about the current directive or role invocation, such as its
    type, name, source text, and line number.
@@ -224,7 +215,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: markup
 
          {%
          set m = load_extra('markup')
@@ -238,22 +228,22 @@ The following extra contexts are available:
             {% endfor %}
  
 ``section``
-   :Phase: parsing and later
+   :Phase: :term:`parsed` and :term:`resolving`
 
    A proxy to the current :py:class:`docutils.nodes.section` node, when one
-   exists.
+   exists. This extra context is not available during the parsing phase.
 
    .. example::
       :style: grid
 
       .. data.render::
-         :extra: section
+         :on: parsed
 
-          Section Title:
+         Section Title:
          "{{ load_extra('section').title }}"
 
 ``doc``
-   :Phase: parsing and later
+   :Phase: all
 
    A proxy to the current :py:class:`docutils.notes.document` node.
 
@@ -261,7 +251,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: doc
 
          Document title:
          "{{ load_extra('doc').title }}".
@@ -331,7 +320,6 @@ Each template has a render phase that determines when it is processed:
 
          .. data.render::
             :on: parsing
-            :extra: doc env
 
             {% set doc = load_extra('doc') %}
             {% set env = load_extra('env') %}
@@ -354,7 +342,6 @@ Each template has a render phase that determines when it is processed:
 
          .. data.render::
             :on: parsed
-            :extra: doc env
 
             {% set doc = load_extra('doc') %}
             {% set env = load_extra('env') %}
@@ -378,7 +365,6 @@ Each template has a render phase that determines when it is processed:
 
          .. data.render::
             :on: resolving
-            :extra: doc env
 
             {% set doc = load_extra('doc') %}
             {% set env = load_extra('env') %}

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/docs/usage.rst

@@ -57,11 +57,6 @@ Directives
 
       Enable :ref:`debug report <debug>` for template rendering.
 
-   .. rst:directive:option:: extra
-      :type: space separted list
-
-      List of :ref:`extra-context` to be used in the template.
-
    The content of the directive should be Jinja2 Template, please refer to
    ::doc:`tmpl`.
 
@@ -116,7 +111,6 @@ Directives
 
    .. rst:directive:option:: on
    .. rst:directive:option:: debug
-   .. rst:directive:option:: extra
 
       The options of this directive are same to :rst:dir:`data.template`.
 

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/src/sphinxnotes/render/__init__.py

@@ -22,14 +22,12 @@ from .data import (
     Schema,
 )
 from .template import Phase, Template
-from .ctx import PendingContext, ResolvedContext
+from .ctx import UnresolvedContext, ResolvedContext
 from .ctxnodes import pending_node
 from .extractx import (
     extra_context,
-    ParsingPhaseExtraContext,
-    ParsedPhaseExtraContext,
-    ResolvingPhaseExtraContext,
-    GlobalExtraContext,
+    ExtraContext,
+    ExtraContextRequest,
 )
 from .pipeline import BaseContextRole, BaseContextDirective
 from .sources import (
@@ -56,12 +54,10 @@ __all__ = [
     'Schema',
     'Phase',
     'Template',
-    'PendingContext',
+    'UnresolvedContext',
     'ResolvedContext',
-    'ParsingPhaseExtraContext',
-    'ParsedPhaseExtraContext',
-    'ResolvingPhaseExtraContext',
-    'GlobalExtraContext',
+    'ExtraContext',
+    'ExtraContextRequest',
     'extra_context',
     'pending_node',
     'BaseContextRole',

sphinxnotes_render-1.0b5/src/sphinxnotes/render/ctx.py

@@ -0,0 +1,23 @@
+"""
+This module wraps the :py:mod:`sphinxnotes.render.data` module into context
+suitable for use with Jinja templates.
+"""
+
+from __future__ import annotations
+from typing import Any
+from abc import ABC, abstractmethod
+from collections.abc import Hashable
+from .data import ParsedData
+
+type ResolvedContext = ParsedData | dict[str, Any]
+"""Resolved context types used by template rendering."""
+
+
+class UnresolvedContext(ABC, Hashable):
+    """An abstract representation of context that will be resolved later."""
+
+    @abstractmethod
+    def resolve(self) -> ResolvedContext:
+        """This method will be called when rendering to get the available
+        :py:type:`ResolvedContext`."""
+        ...

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/src/sphinxnotes/render/ctxnodes.py

@@ -1,17 +1,18 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING, override
+import pickle
 from pprint import pformat
 
 from docutils import nodes
 from docutils.parsers.rst.states import Inliner
 
-from .template import Template
+from .data import ValueWrapper, ParsedData
+from .template import Template, Phase
 from .ctx import (
-    PendingContextRef,
-    PendingContext,
-    PendingContextStorage,
+    UnresolvedContext,
     ResolvedContext,
 )
+from .extractx import ExtraContextRequest, extra_context_loader, extra_context_names
 from .markup import MarkupRenderer
 from .jinja import TemplateRenderer
 from .utils import (
@@ -21,7 +22,7 @@ from .utils import (
 )
 
 if TYPE_CHECKING:
-    from typing import Any, Callable, ClassVar
+    from typing import Callable, Any
     from .markup import Host
     from .ctx import ResolvedContext
 
@@ -30,25 +31,19 @@ class pending_node(nodes.Element):
     """A docutils node to be rendered."""
 
     # The context to be rendered by Jinja template.
-    ctx: PendingContextRef | ResolvedContext
-    # The extra context as supplement to ctx.
-    extra: dict[str, Any]
+    ctx: UnresolvedContext | ResolvedContext
     #: Jinja template for rendering the context.
     template: Template
     #: Whether rendering to inline nodes.
     inline: bool
     #: Whether the rendering pipeline is finished (failed is also finished).
     rendered: bool
-
-    #: Mapping of PendingContextRef -> PendingContext.
-    #:
-    #: NOTE: ``PendingContextStorage`` holds Unpicklable data (``PendingContext``)
-    #: but it is doesn't matters :-), cause pickle doesn't deal with ClassVar.
-    _PENDING_CONTEXTS: ClassVar[PendingContextStorage] = PendingContextStorage()
+    #: Stored pickling error for later-phase unresolved context.
+    _ctx_pickle_error: Exception | None
 
     def __init__(
         self,
-        ctx: PendingContext | ResolvedContext,
+        ctx: UnresolvedContext | ResolvedContext,
         tmpl: Template,
         inline: bool = False,
         rawsource='',
@@ -56,18 +51,20 @@ class pending_node(nodes.Element):
         **attributes,
     ) -> None:
         super().__init__(rawsource, *children, **attributes)
-        if not isinstance(ctx, PendingContext):
-            self.ctx = ctx
-        else:
-            self.ctx = self._PENDING_CONTEXTS.stash(ctx)
-        self.extra = {}
+        self._ctx_pickle_error = None
+        if isinstance(ctx, UnresolvedContext) and tmpl.phase != Phase.Parsing:
+            try:
+                pickle.dumps(ctx)
+            except Exception as exc:
+                self._ctx_pickle_error = exc
+        self.ctx = ctx
         self.template = tmpl
         self.inline = inline
         self.rendered = False
 
         # Init hook lists.
-        self._pending_context_hooks = []
-        self._resolved_data_hooks = []
+        self._unresolved_context_hooks = []
+        self._resolved_context_hooks = []
         self._markup_text_hooks = []
         self._rendered_nodes_hooks = []
 
@@ -75,7 +72,7 @@ class pending_node(nodes.Element):
         """
         The core function for rendering context and template to docutils nodes.
 
-        1. PendingContextRef -> PendingContext -> ResolvedContext
+        1. UnresolvedContext -> ResolvedContext
         2. TemplateRenderer.render(ResolvedContext) -> Markup Text (``str``)
         3. MarkupRenderer.render(Markup Text) -> doctree Nodes (list[nodes.Node])
         """
@@ -97,48 +94,55 @@ class pending_node(nodes.Element):
                 return report
             return Report('Render Report', 'ERROR', source=self.source, line=self.line)
 
-        # 1. Prepare context for Jinja template.
-        if isinstance(self.ctx, PendingContextRef):
-            report.text('Pending context ref:')
-            report.code(pformat(self.ctx), lang='python')
-
-            pdata = self._PENDING_CONTEXTS.retrieve(self.ctx)
-            if pdata is None:
-                report = err_report()
-                report.text(f'Failed to retrieve pending context from ref {self.ctx}')
-                self += report
-                return None
+        if self._ctx_pickle_error is not None:
+            report = err_report()
+            report.text(
+                f'UnresolvedContext used by {self.template.phase} phase templates '
+                'must be picklable:'
+            )
+            report.exception(self._ctx_pickle_error)
+            self += report
+            return None
 
-            report.text('Pending context:')
+        # 1. Prepare context for Jinja template.
+        if isinstance(self.ctx, UnresolvedContext):
+            pdata = self.ctx
+            report.text('Unresolved context:')
             report.code(pformat(pdata), lang='python')
 
-            for hook in self._pending_context_hooks:
+            for hook in self._unresolved_context_hooks:
                 hook(self, pdata)
 
             try:
                 ctx = self.ctx = pdata.resolve()
             except Exception as e:
                 report = err_report()
-                report.text('Failed to resolve pending context:')
+                report.text('Failed to resolve unresolved context:')
                 report.exception(e)
                 self += report
                 return None
         else:
             ctx = self.ctx
 
-        for hook in self._resolved_data_hooks:
+        for hook in self._resolved_context_hooks:
             hook(self, ctx)
 
         report.text(f'Resolved context (type: {type(ctx)}):')
         report.code(pformat(ctx), lang='python')
-        report.text('Extra context (only keys):')
-        report.code(pformat(list(self.extra.keys())), lang='python')
         report.text(f'Template (phase: {self.template.phase}):')
         report.code(self.template.text, lang='jinja')
 
+        extractx_req = ExtraContextRequest(self.template.phase, self, host.env, host)
+        report.text('Available extra context names:')
+        report.code(pformat(sorted(extra_context_names())), lang='python')
+
         # 2. Render the template and context to markup text.
         try:
-            markup = TemplateRenderer(self.template.text).render(ctx, extra=self.extra)
+            markup = TemplateRenderer(self.template.text).render(
+                ctx,
+                globals={'load_extra': extra_context_loader(extractx_req)},
+                debug=self.template.debug,
+            )
         except Exception as e:
             report = err_report()
             report.text('Failed to render Jinja template:')
@@ -221,21 +225,21 @@ class pending_node(nodes.Element):
 
     """Hooks for processing render intermediate products."""
 
-    type PendingContextHook = Callable[[pending_node, PendingContext], None]
+    type UnresolvedContextHook = Callable[[pending_node, UnresolvedContext], None]
     type ResolvedContextHook = Callable[[pending_node, ResolvedContext], None]
     type MarkupTextHook = Callable[[pending_node, str], str]
     type RenderedNodesHook = Callable[[pending_node, list[nodes.Node]], None]
 
-    _pending_context_hooks: list[PendingContextHook]
-    _resolved_data_hooks: list[ResolvedContextHook]
+    _unresolved_context_hooks: list[UnresolvedContextHook]
+    _resolved_context_hooks: list[ResolvedContextHook]
     _markup_text_hooks: list[MarkupTextHook]
     _rendered_nodes_hooks: list[RenderedNodesHook]
 
-    def hook_pending_context(self, hook: PendingContextHook) -> None:
-        self._pending_context_hooks.append(hook)
+    def hook_unresolved_context(self, hook: UnresolvedContextHook) -> None:
+        self._unresolved_context_hooks.append(hook)
 
     def hook_resolved_context(self, hook: ResolvedContextHook) -> None:
-        self._resolved_data_hooks.append(hook)
+        self._resolved_context_hooks.append(hook)
 
     def hook_markup_text(self, hook: MarkupTextHook) -> None:
         self._markup_text_hooks.append(hook)
@@ -259,3 +263,16 @@ class pending_node(nodes.Element):
     def deepcopy(self) -> Any:
         # NOTE: Same to :meth:`copy`.
         return self.copy()
+
+    @override
+    def astext(self) -> str:
+        ctx = self.ctx
+        if isinstance(ctx, UnresolvedContext):
+            try:
+                ctx = ctx.resolve()
+            except Exception:
+                return ''
+        if isinstance(ctx, ParsedData):
+            return ValueWrapper(ctx.content).as_str() or ''
+        else:
+            return ''

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/src/sphinxnotes/render/data.py

@@ -14,8 +14,6 @@ import re
 from dataclasses import dataclass, asdict, field as dataclass_field
 from ast import literal_eval
 
-from .utils import Unpicklable
-
 if TYPE_CHECKING:
     from typing import Any, Callable, Generator, Self
 
@@ -287,7 +285,7 @@ class ParsedData:
 
 
 @dataclass
-class Field(Unpicklable):
+class Field:
     #: Type of element.
     etype: type = str
     #: Type of container (if the field holds multiple values).
@@ -374,8 +372,9 @@ class Field(Unpicklable):
             raise ValueError(f"Failed to parse '{rawval}' as {self.etype}: {e}") from e
 
     def __getattr__(self, name: str) -> Value:
-        if name in self.flags:
-            return self.flags[name]
+        flags = self.__dict__.get('flags')
+        if flags is not None and name in flags:
+            return flags[name]
         raise AttributeError(name)
 
 
@@ -491,7 +490,7 @@ class DSLParser:
 
 
 @dataclass(frozen=True)
-class Schema(Unpicklable):
+class Schema:
     name: Field | None
     attrs: dict[str, Field] | Field
     content: Field | None

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/src/sphinxnotes/render/ext/adhoc.py

@@ -33,7 +33,7 @@ if TYPE_CHECKING:
     from types import ModuleType
     from docutils.utils import Reporter
     from sphinx.util.typing import RoleFunction
-    from .. import PendingContext, ResolvedContext
+    from .. import UnresolvedContext, ResolvedContext
 
 
 # Keys of env.temp_data.
@@ -50,19 +50,15 @@ class TemplateDefineDirective(SphinxDirective):
     option_spec = {
         'on': phase_option_spec,
         'debug': directives.flag,
-        'extra': directives.unchanged,
     }
     has_content = True
 
     @override
     def run(self) -> list[nodes.Node]:
-        extra = self.options.get('extra', '')
-
         self.env.temp_data[TEMPLATE_KEY] = Template(
             '\n'.join(self.content),
             phase=self.options.get('on', Phase.default()),
             debug='debug' in self.options,
-            extra=extra.split() if extra else [],
         )
 
         return []
@@ -135,24 +131,19 @@ class DataRenderDirective(BaseContextDirective):
     option_spec = {
         'on': phase_option_spec,
         'debug': directives.flag,
-        'extra': directives.unchanged,
     }
     has_content = True
 
     @override
-    def current_context(self) -> PendingContext | ResolvedContext:
+    def current_context(self) -> UnresolvedContext | ResolvedContext:
         return {}
 
     @override
     def current_template(self) -> Template:
-        extra_str = self.options.get('extra', '')
-        extra_list = extra_str.split() if extra_str else []
-
         return Template(
             '\n'.join(self.content),
             phase=self.options.get('on', Phase.default()),
             debug='debug' in self.options,
-            extra=extra_list,
         )
 
 

{sphinxnotes_render-1.0b4 → sphinxnotes_render-1.0b5}/src/sphinxnotes/render/ext/derive.py

@@ -31,7 +31,6 @@ DATA_DEFINE_DIRECTIVE = DictSchema(
             Optional('on', default='parsing'): Or('parsing', 'parsed', 'resolving'),
             'text': str,
             Optional('debug', default=False): bool,
-            Optional('extra', default=[]): list,
         },
     }
 )
@@ -50,7 +49,6 @@ def _validate_directive_define(d: dict, config: Config) -> tuple[Schema, Templat
         text=tmpldef['text'],
         phase=Phase[tmpldef['on'].title()],
         debug=tmpldef['debug'],
-        extra=tmpldef['extra'],
     )
 
     return schema, template