fastlifeweb 0.17.0__py3-none-any.whl → 0.19.0__py3-none-any.whl

fastlife/adapters/jinjax/jinjax_ext/jinjax_doc.py

@@ -0,0 +1,298 @@
+import ast
+import re
+from pathlib import Path
+from typing import Any, ClassVar, cast
+
+from docutils import nodes
+from sphinx.addnodes import index, pending_xref
+from sphinx.application import Sphinx
+from sphinx.builders import Builder
+from sphinx.directives import ObjectDescription
+from sphinx.domains import Domain, ObjType
+from sphinx.environment import BuildEnvironment
+from sphinx.roles import XRefRole
+from sphinx.util import relative_uri  # type: ignore
+
+from fastlife.adapters.jinjax.renderer import JinjaxEngine
+from fastlife.config.settings import Settings
+
+
+def create_ref_node(arg_type: str) -> nodes.Node:
+    """
+    Creates a cross-reference node if a type has been inferred.
+
+    At the monent, type inferred are types containing a `.`, otherwise
+    considered as a simple type from the python standard library.
+
+    This function is used to create links in component parameters.
+
+    :param arg_type: type to render.
+    """
+    if "|" in arg_type:
+        typs = [t.strip() for t in arg_type.split("|")]
+        typs_group = nodes.literal()
+        for idx, typ in enumerate(typs):
+            if idx:
+                typs_group += nodes.Text(" | ")
+            typs_group += create_ref_node(typ)
+        return typs_group
+
+    if "." in arg_type:
+        ref_node = pending_xref(
+            "",
+            refdomain="py",
+            reftype="class",
+            reftarget=arg_type,
+            refexplicit=True,
+            refwarn=True,
+            classes=[],
+        )
+        ref_node += nodes.Text(arg_type)
+        return ref_node
+    else:
+        return nodes.inline(text=arg_type, classes=["jinjax-type"])
+
+
+def handle_arg_type(arg_type: str, signature_node: nodes.literal) -> None:
+    """Add arg_type to signature_node."""
+    complex_type_pattern = r"(\w+)\[(.+)\]"
+
+    match = re.match(complex_type_pattern, arg_type)
+    if match:
+        outer_type, inner_type = match.groups()
+        signature_node += nodes.inline(text=f"{outer_type}[", classes=["jinjax-type"])
+        signature_node += create_ref_node(inner_type)
+        signature_node += nodes.inline(text="]", classes=["jinjax-type"])
+    else:
+        signature_node += create_ref_node(arg_type)
+
+
+class JinjaxComponent(ObjectDescription[str]):
+    """Description of a Jinjax component."""
+
+    def run(self) -> list[nodes.Node]:
+        """Generate structured and styled documentation for the directive."""
+        container_node = nodes.container(classes=["jinjax-component"])
+
+        # Extract the signature (first line of arguments)
+        signature_text = self.arguments[0]
+        component_name, rest = signature_text.split("(", 1)
+
+        params = rest.rstrip(")")
+        if params:
+            signature = f"def component(*, {params}): pass"
+        else:
+            # no parameters in the component
+            signature = "def component(): pass"
+
+        astree = ast.parse(signature)
+        func_def = cast(ast.FunctionDef, astree.body[0])
+
+        # Create a colorized signature line with separate spans for each part
+        signature_node = nodes.literal(classes=["jinjax-signature"])
+        signature_node += nodes.inline(text="<")
+        signature_node += nodes.inline(
+            text=component_name, classes=["jinjax-component-name"]
+        )
+
+        def process_arg(arg: ast.arg, default_value: Any, signature_node: Any) -> None:
+            arg_name = arg.arg.replace("_", "-").rstrip("-")
+            arg_type = ast.unparse(arg.annotation) if arg.annotation else "Any"
+            signature_node += nodes.inline(text=" ")
+
+            signature_node += nodes.inline(text=arg_name, classes=["jinjax-arg"])
+            signature_node += nodes.inline(text=": ")
+
+            handle_arg_type(arg_type, signature_node)
+
+            if default_value is not None:
+                signature_node += nodes.inline(text=" = ")
+                signature_node += nodes.inline(
+                    text=ast.unparse(default_value), classes=["jinjax-default"]
+                )
+
+        # Process keyword-only arguments
+        kwonlyargs = func_def.args.kwonlyargs
+        kw_defaults = func_def.args.kw_defaults
+
+        has_content = False
+        for arg, default in zip(kwonlyargs, kw_defaults, strict=False):
+            if arg.arg == "content":
+                has_content = True
+            else:
+                process_arg(arg, default, signature_node)
+
+        signature_close_wrapper = nodes.container(classes=["jinjax-signature-close"])
+        if has_content:
+            signature_node += nodes.inline(text=">")
+            signature_node += nodes.inline(
+                text="{{- content -}}", classes=["jinjax-child-content"]
+            )
+            signature_close_wrapper += nodes.inline(text="</")
+            signature_close_wrapper += nodes.inline(
+                text=component_name, classes=["jinjax-component-name"]
+            )
+            signature_close_wrapper += nodes.inline(text=">")
+        else:
+            signature_node += nodes.inline(text=" />")
+            signature_close_wrapper += nodes.inline(text="")
+        signature_node += signature_close_wrapper
+
+        signature_node_wrapper = nodes.container(classes=["jinjax-signature-wrapper"])
+        signature_node_wrapper += signature_node
+
+        container_node += nodes.paragraph("", "", signature_node_wrapper)
+
+        if self.content:
+            content = self.parse_content_to_nodes(allow_section_headings=True)
+            for content_node in content:
+                container_node += content_node
+
+        index_entry = index(
+            entries=[
+                (
+                    "single",
+                    f"{component_name} (JinjaX component)",
+                    f"jinjax-component-{component_name}",
+                    "",
+                    None,
+                )
+            ]
+        )
+        return [index_entry, container_node]
+
+
+class JinjaxDomain(Domain):
+    """Custom domain for Jinjax components."""
+
+    name = "jinjax"
+    label = "Jinjax"
+    roles = {  # noqa: RUF012
+        "component": XRefRole(),
+    }
+    directives = {  # noqa: RUF012
+        "component": JinjaxComponent,
+    }
+    object_types = {  # noqa: RUF012
+        "component": ObjType("component", "component"),
+    }
+
+    _components: ClassVar[list[str]] = []
+
+    @classmethod
+    def register(cls, component: str) -> None:
+        cls._components.append(component)
+
+    def resolve_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: nodes.Element,
+    ) -> nodes.Element | None:
+        """Resolve the pending_xref *node* with the given *typ* and *target*.
+
+        This method should return a new node, to replace the xref node,
+        containing the *contnode* which is the markup content of the
+        cross-reference.
+
+        If no resolution can be found, None can be returned; the xref node will
+        then given to the :event:`missing-reference` event, and if that yields no
+        resolution, replaced by *contnode*.
+
+        The method can also raise :exc:`sphinx.environment.NoUri` to suppress
+        the :event:`missing-reference` event being emitted.
+        """
+        ret = self.resolve_any_xref(env, fromdocname, builder, target, node, contnode)
+        return ret[0][1] if ret else None
+
+    def resolve_any_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        target: str,
+        node: pending_xref,
+        contnode: nodes.Element,
+    ) -> list[tuple[str, nodes.Element]]:
+        """Resolve the pending_xref *node* with the given *target*.
+
+        The reference comes from an "any" or similar role, which means that we
+        don't know the type.  Otherwise, the arguments are the same as for
+        {meth}`JinjaxDomain.resolve_xref`.
+
+        The method must return a list (potentially empty) of tuples
+        ``('domain:role', newnode)``, where ``'domain:role'`` is the name of a
+        role that could have created the same reference, e.g. ``'py:func'``.
+        ``newnode`` is what {meth}`JinjaxDomain.resolve_xref` would return.
+
+        .. versionadded:: 1.3
+        """
+        if target in self._components:
+            ref_uri = f"components/{target}.html"
+            relative_link = relative_uri(fromdocname, ref_uri)
+
+            if isinstance(contnode, nodes.literal) and contnode.astext() == target:
+                contnode = nodes.literal("", f"<{target}/>")
+
+            newnode = nodes.reference("", "", contnode, refuri=relative_link)
+            return [("jinjax:component", newnode)]
+
+        return []
+
+
+def run_autodoc(app: Sphinx) -> None:
+    """Run autodoc for a single package.
+
+    :return: The top level module name, relative to the api directory.
+    """
+    renderer = JinjaxEngine(
+        Settings(template_search_path=app.config.jinjax_template_search_path)
+    )
+    outdir = Path(app.srcdir) / app.config.jinjax_doc_output_dir
+    outdir.mkdir(parents=True, exist_ok=True)
+    toctree = ""
+
+    ignores = [re.compile(rx) for rx in app.config.jinjax_ignores_pattern.split(",")]
+
+    for component in renderer.catalog.iter_components(ignores=ignores):
+        outfile = outdir / f"{component.name}.rst"
+
+        outfile.write_text(
+            f"{component.name}\n"
+            f"{'=' * len(component.name)}\n"
+            f"\n{component.build_docstring()}"
+        )
+        toctree += f"   {component.name}\n"
+        JinjaxDomain.register(component.name)
+
+    outfile = outdir / "index.rst"
+    outfile.write_text(INDEX_TPL.format(toctree=toctree))
+
+
+INDEX_TPL = """\
+
+.. _jinjax-components:
+
+JinjaX Components
+=================
+
+fastlife comes with a set of compoments:
+
+.. toctree::
+   :titlesonly:
+
+{toctree}
+"""
+
+
+def setup(app: Sphinx) -> None:
+    app.add_config_value("jinjax_doc_index_template", INDEX_TPL, "env")
+    app.add_config_value("jinjax_doc_output_dir", "components", "env")
+    app.add_config_value("jinjax_template_search_path", "fastlife:components", "env")
+    app.add_config_value("jinjax_ignores_pattern", r"^icons\..*", "env")
+    app.add_domain(JinjaxDomain)
+    app.connect("builder-inited", run_autodoc)

fastlife/adapters/jinjax/renderer.py

@@ -2,24 +2,14 @@
 Template rending based on JinjaX.
 """
 
-import ast
 import logging
-import re
 import textwrap
-from collections.abc import Iterator, Mapping, MutableMapping, Sequence
-from pathlib import Path
+from collections.abc import Mapping, MutableMapping, Sequence
 from typing import (
     TYPE_CHECKING,
     Any,
-    cast,
 )
 
-from jinja2 import Template
-from jinja2.exceptions import TemplateSyntaxError
-from jinjax import InvalidArgument
-from jinjax.catalog import Catalog
-from jinjax.component import RX_ARGS_START, RX_META_HEADER, Component
-from jinjax.exceptions import DuplicateDefDeclaration
 from markupsafe import Markup
 from pydantic.fields import FieldInfo
 
@@ -27,6 +17,7 @@ from fastlife import Request
 from fastlife.adapters.jinjax.widget_factory.factory import WidgetFactory
 from fastlife.request.form import FormModel
 from fastlife.request.localizer import get_localizer
+from fastlife.templates.inline import InlineTemplate
 
 if TYPE_CHECKING:
     from fastlife.config.settings import Settings  # coverage: ignore
@@ -37,247 +28,9 @@ from fastlife.services.templates import (
 )
 from fastlife.shared_utils.resolver import resolve, resolve_path
 
-log = logging.getLogger(__name__)
-
-RX_DOC_START = re.compile(r"{#-?\s*doc\s+")
-RX_CONTENT = re.compile(r"\{\{-?\s*content\s*-?\}\}", re.DOTALL)
-RX_COMMENT_REPLACE = re.compile(r"{#[^#]+#}")
-
-
-def has_content(source: str) -> bool:
-    nocomment = RX_COMMENT_REPLACE.sub("", source)
-    return len(RX_CONTENT.findall(nocomment)) > 0
-
-
-def generate_docstring(
-    func_def: ast.FunctionDef, component_name: str, add_content: bool
-) -> str:
-    """Generate a docstring for the component."""
-    # Extract function name and docstring
-    docstring = (ast.get_docstring(func_def, clean=True) or "").strip()
-    if docstring:
-        docstring = textwrap.dedent(docstring)
-        docstring_lines = [line for line in docstring.split("\n")]
-        # Add a newline for separation after the function docstring
-        docstring_lines.append("")
-    else:
-        docstring_lines = []
-
-    component_params: list[str] = []
-
-    # Function for processing an argument and adding its docstring lines
-    def process_arg(arg: ast.arg, default_value: Any = None) -> None:
-        arg_name = arg.arg
-        param_desc = ""
-        # Extract the type annotation (if any)
-        if (
-            isinstance(arg.annotation, ast.Subscript)
-            and isinstance(arg.annotation.value, ast.Name)
-            and arg.annotation.value.id == "Annotated"
-        ):
-            # For Annotated types, we expect the first argument to be the type and
-            # the second to be the description
-            type_annotation = arg.annotation.slice.elts[0]  # type: ignore
-            param_type = ast.unparse(type_annotation)  # type: ignore
-
-            if len(arg.annotation.slice.elts) > 1 and isinstance(  # type: ignore
-                arg.annotation.slice.elts[1],  # type: ignore
-                ast.Constant,  # type: ignore
-            ):
-                param_desc = arg.annotation.slice.elts[1].value  # type: ignore
-        else:
-            # Otherwise, just use the type if available
-            param_type = ast.unparse(arg.annotation) if arg.annotation else "Any"
-
-        # Build the parameter docstring line
-        docstring_lines.append(f":param {arg_name.rstrip('_')}: {param_desc}".strip())
-
-        # Build the string representation of the parameter
-        param_str = f"{arg_name}: {param_type}"
-        if default_value is not None:
-            param_str += f" = {ast.unparse(default_value)}"  # type: ignore
-
-        component_params.append(param_str)
-
-    # Process keyword-only arguments
-    kwonlyargs = func_def.args.kwonlyargs
-    kw_defaults = func_def.args.kw_defaults
-
-    for arg, default in zip(kwonlyargs, kw_defaults, strict=False):
-        process_arg(arg, default)
-
-    if add_content:
-        component_params.append("content: Any")
-        docstring_lines.append(":param content: child node.")
-
-    return (
-        f"{component_name}({', '.join(component_params)})"
-        + "\n"
-        + "\n    "
-        + ("\n    ".join(docstring_lines).strip()).replace("\n    \n", "\n\n")
-        + "\n"
-    )
-
-
-class InspectableComponent(Component):
-    """
-    JinjaX Components override that support intropspection.
-
-    The Component class of JinjaX does not support documentation by default.
-    """
-
-    __slots__ = (
-        "name",
-        "prefix",
-        "url_prefix",
-        "required",
-        "optional",
-        "css",
-        "js",
-        "path",
-        "mtime",
-        "tmpl",
-        "source",
-    )
-
-    def __init__(
-        self,
-        *,
-        name: str,
-        prefix: str = "",
-        url_prefix: str = "",
-        source: str = "",
-        mtime: float = 0,
-        tmpl: "Template | None" = None,
-        path: "Path | None" = None,
-    ) -> None:
-        super().__init__(
-            name=name,
-            prefix=prefix,
-            url_prefix=url_prefix,
-            source=source,
-            mtime=mtime,
-            tmpl=tmpl,
-            path=path,
-        )
-        self.source = source
-
-    def as_def(self) -> ast.FunctionDef:
-        """Return the component definition as a python function definition."""
-        signature = "def component(): pass"
-        match = RX_META_HEADER.match(self.source)
-        if match:
-            headers = match.group(0)
-            header = headers.split("#}")[:-1]
-            def_found = False
-            docstring = ""
-
-            expr = None
-            while header:
-                item = header.pop(0).strip(" -\n")
-
-                expr = self.read_metadata_item(item, RX_ARGS_START)  # type: ignore
-                if expr:
-                    if def_found:
-                        raise DuplicateDefDeclaration(self.name)
-                    def_found = True
-                    continue
-
-                doc = self.read_metadata_item(item, RX_DOC_START)  # type: ignore
-                if doc:
-                    docstring += f"    {doc.strip()}\n"
-                    continue
-
-            if expr:
-                signature = f"""\
-def component(*, {expr}):
-    '''
-    {docstring or ""}
-    '''
-    ...
-"""
-            elif docstring:
-                signature = f"""\
-def component():
-    '''
-    {docstring}
-    '''
-    ...
-"""
-
-        try:
-            astree = ast.parse(signature)
-        except SyntaxError as err:
-            raise InvalidArgument(err) from err
-        return cast(ast.FunctionDef, astree.body[0])
-
-    def build_docstring(self) -> str:
-        """Build a rst docstring for the jinjax component."""
-        func_def = self.as_def()
-        prefix = f"{self.prefix}." if self.prefix else ""
-        ret = ".. jinjax:component:: " + generate_docstring(
-            func_def, f"{prefix}{self.name}", has_content(self.source)
-        )
-        return ret
+from .jinjax_ext.inspectable_catalog import InspectableCatalog
 
-
-def to_include(
-    name: str,
-    ignores: Sequence[re.Pattern[str]] | None = None,
-    includes: Sequence[re.Pattern[str]] | None = None,
-) -> bool:
-    if includes and not any(include.match(name) for include in includes):
-        return False
-
-    if ignores and any(ignore.match(name) for ignore in ignores):
-        return False
-
-    return True
-
-
-class InspectableCatalog(Catalog):
-    """
-    JinjaX Catalog with introspection support.
-
-    Override the catalog in order to iterate over components to build the doc.
-    """
-
-    def iter_components(
-        self,
-        ignores: Sequence[re.Pattern[str]] | None = None,
-        includes: Sequence[re.Pattern[str]] | None = None,
-    ) -> Iterator[InspectableComponent]:
-        """
-        Walk into every templates from the settings, iterate over components.
-
-        :params ignores: filter components using an block list.
-        :params includes: filter components using an allowed list.
-        """
-        for prefix, loader in self.prefixes.items():
-            for t in loader.list_templates():
-                name, file_ext = t.split(".", maxsplit=1)
-                name = name.replace("/", ".")
-                path, tmpl_name = self._get_component_path(
-                    prefix, name, file_ext=file_ext
-                )
-
-                is_included = to_include(name, ignores, includes)
-
-                if is_included:
-                    component = InspectableComponent(
-                        name=name, prefix=prefix, path=path, source=path.read_text()
-                    )
-
-                    self.jinja_env.loader = loader
-                    try:
-                        component.tmpl = self.jinja_env.get_template(
-                            tmpl_name, globals=self._tmpl_globals
-                        )
-                    except TemplateSyntaxError as exc:
-                        log.error(f"Syntax Error: {exc} on {exc.lineno} :")
-                        log.error(path.read_text())
-                        continue
-                    yield component
+log = logging.getLogger(__name__)
 
 
 def build_searchpath(template_search_path: str) -> Sequence[str]:
@@ -351,8 +104,7 @@ class JinjaxRenderer(AbstractTemplateRenderer):
             child components without "props drilling".
         :param params: parameters used to render the template.
         """
-        # Jinja template does accept the file extention while rendering the template
-        # we strip it before rendering.
+
         template = template[: -len(self.settings.jinjax_file_ext) - 1]
         if globals:
             self.globals.update(globals)
@@ -365,6 +117,27 @@ class JinjaxRenderer(AbstractTemplateRenderer):
             template, __globals=self.build_globals(), **params
         )
 
+    def render_inline(self, template: InlineTemplate) -> str:
+        """
+        Render the JinjaX component with the given parameter.
+
+        :param template: the template to render
+        :param globals: parameters that will be used by the JinjaX component and all its
+            child components without "props drilling".
+        :param params: parameters used to render the template.
+        """
+        params = template.model_dump()
+        src = (
+            f"{{# def {', '.join(params.keys())} #}}\n"
+            f"{textwrap.dedent(template.template)}"
+        )
+        return self.catalog.render(
+            template.__class__.__qualname__,
+            __source=src,
+            __globals=self.build_globals(),
+            **params,
+        )
+
     def pydantic_form(
         self, model: FormModel[Any], *, token: str | None = None
     ) -> Markup:
@@ -411,7 +184,7 @@ class JinjaxRenderer(AbstractTemplateRenderer):
         )
 
 
-class JinjaxTemplateRenderer(AbstractTemplateRendererFactory):
+class JinjaxEngine(AbstractTemplateRendererFactory):
     """
     The default template renderer factory. Based on JinjaX.
 

fastlife/adapters/jinjax/widget_factory/base.py

@@ -9,7 +9,9 @@ from pydantic.fields import FieldInfo
 from fastlife.adapters.jinjax.widgets.base import Widget
 
 if TYPE_CHECKING:
-    from fastlife.adapters.jinjax.widget_factory.factory import WidgetFactory
+    from fastlife.adapters.jinjax.widget_factory.factory import (  # coverage: ignore
+        WidgetFactory,
+    )
 
 T = TypeVar("T")
 

fastlife/components/icons/AcademicCap.jinja

@@ -1,6 +1,9 @@
 {# def
-    id=None,
-    title=None,
+    id: Annotated[str | None, "identifier of the element."] = None,
+    title: Annotated[str | None, "title element of the svg"] = None,
+    class_: Annotated[
+        str | None, "css class applied to the svg element"
+    ] = None,
     mode: Literal["micro","mini","outline","solid"] = "solid"
 #}
 

fastlife/components/icons/AdjustmentsHorizontal.jinja

@@ -1,6 +1,9 @@
 {# def
-    id=None,
-    title=None,
+    id: Annotated[str | None, "identifier of the element."] = None,
+    title: Annotated[str | None, "title element of the svg"] = None,
+    class_: Annotated[
+        str | None, "css class applied to the svg element"
+    ] = None,
     mode: Literal["micro","mini","outline","solid"] = "solid"
 #}
 

fastlife/components/icons/AdjustmentsVertical.jinja

@@ -1,6 +1,9 @@
 {# def
-    id=None,
-    title=None,
+    id: Annotated[str | None, "identifier of the element."] = None,
+    title: Annotated[str | None, "title element of the svg"] = None,
+    class_: Annotated[
+        str | None, "css class applied to the svg element"
+    ] = None,
     mode: Literal["micro","mini","outline","solid"] = "solid"
 #}
 

fastlife/components/icons/ArchiveBox.jinja

@@ -1,6 +1,9 @@
 {# def
-    id=None,
-    title=None,
+    id: Annotated[str | None, "identifier of the element."] = None,
+    title: Annotated[str | None, "title element of the svg"] = None,
+    class_: Annotated[
+        str | None, "css class applied to the svg element"
+    ] = None,
     mode: Literal["micro","mini","outline","solid"] = "solid"
 #}