fastlifeweb 0.9.7__py3-none-any.whl → 0.11.0__py3-none-any.whl

fastlife/templating/renderer/constants.py

@@ -1,3 +1,14 @@
+"""
+Template Constants injects as global variables in templates.
+
+Constants are configurable using the setting :attrs:`jinjax_global_catalog_class`,
+in order to customize templates.
+
+Those constants are heavy used to inject CSS classes in primary html element
+that are bound to Jinja component.
+
+"""
+
 from pydantic import BaseModel
 
 
@@ -6,6 +17,8 @@ def space_join(*segments: str) -> str:
 
 
 class Constants(BaseModel):
+    """Templates constants."""
+
     A_CLASS: str = space_join(
         "text-primary-600",
         "hover:text-primary-500",
@@ -13,6 +26,7 @@ class Constants(BaseModel):
         "dark:text-primary-300",
         "dark:hover:text-primary-400",
     )
+    """Default css class for {jinjax:component}`A`."""
 
     BUTTON_CLASS: str = space_join(
         "bg-primary-600",
@@ -32,8 +46,10 @@ class Constants(BaseModel):
         "dark:focus:ring-primary-800",
         "dark:hover:bg-primary-700",
     )
+    """Default css class for {jinjax:component}`Button`."""
 
     DETAILS_CLASS: str = "border border-neutral-100 p-4 rounded-m"
+    """Default css class for {jinjax:component}`Details`."""
 
     SECONDARY_BUTTON_CLASS: str = space_join(
         "bg-neutral-300",
@@ -52,6 +68,15 @@ class Constants(BaseModel):
         "dark:focus:ring-neutral-100",
         "dark:hover:bg-neutral-300",
     )
+    """
+    css class for {jinjax:component}`Button`.
+
+    usage:
+
+    ```html
+    <Button :class="SECONDARY_BUTTON_CLASS">secondary</Button>
+    ```
+    """
 
     ICON_BUTTON_CLASS: str = space_join(
         "bg-white",
@@ -70,6 +95,18 @@ class Constants(BaseModel):
         "dark:focus:ring-primary-500",
         "dark:hover:text-primary-300",
     )
+    """
+    css class for {jinjax:component}`Button`.
+
+    usage:
+
+    ```html
+    <Button :class="ICON_BUTTON_CLASS">
+      <icons.PencilSquare class="w-6 h-6" title="Copy" />
+    </Button>
+
+    ```
+    """
 
     CHECKBOX_CLASS: str = space_join(
         "bg-neutral-100",
@@ -85,7 +122,11 @@ class Constants(BaseModel):
         "focus:ring-2",
         "focus:ring-primary-500",
     )
+    """Default css class for {jinjax:component}`Checkbox`."""
+
     FORM_CLASS: str = "space-y-4 md:space-y-6"
+    """Default css class for {jinjax:component}`Form`."""
+
     H1_CLASS: str = space_join(
         "block",
         "font-bold",
@@ -98,6 +139,8 @@ class Constants(BaseModel):
         "dark:text-white",
         "md:text-4xl",
     )
+    """Default css class for {jinjax:component}`H1`."""
+
     H2_CLASS: str = space_join(
         "block",
         "font-bold",
@@ -110,6 +153,8 @@ class Constants(BaseModel):
         "dark:text-white",
         "md:text-4xl",
     )
+    """Default css class for {jinjax:component}`H2`."""
+
     H3_CLASS: str = space_join(
         "block",
         "font-bold",
@@ -122,6 +167,8 @@ class Constants(BaseModel):
         "dark:text-white",
         "md:text-3xl",
     )
+    """Default css class for {jinjax:component}`H3`."""
+
     H3_SUMMARY_CLASS: str = space_join(
         "block",
         "font-bold",
@@ -133,6 +180,9 @@ class Constants(BaseModel):
         "dark:text-white",
         "md:text-3xl",
     )
+    """
+    Default css class for {jinjax:component}`H3` inside {jinjax:component}`Summary`.
+    """
 
     H4_CLASS: str = space_join(
         "block",
@@ -146,6 +196,8 @@ class Constants(BaseModel):
         "dark:text-white",
         "md:text-2xl",
     )
+    """Default css class for {jinjax:component}`H4`."""
+
     H5_CLASS: str = space_join(
         "block",
         "font-bold",
@@ -158,6 +210,8 @@ class Constants(BaseModel):
         "dark:text-white",
         "md:text-xl",
     )
+    """Default css class for {jinjax:component}`H5`."""
+
     H6_CLASS: str = space_join(
         "block",
         "font-bold",
@@ -170,6 +224,8 @@ class Constants(BaseModel):
         "dark:text-white",
         "md:text-l",
     )
+    """Default css class for {jinjax:component}`H6`."""
+
     INPUT_CLASS: str = space_join(
         "bg-neutral-50",
         "block",
@@ -189,6 +245,8 @@ class Constants(BaseModel):
         "focus:border-primary-500",
         "focus:ring-primary-500",
     )
+    """Default css class for {jinjax:component}`Input`."""
+
     LABEL_CLASS: str = space_join(
         "block",
         "font-bold",
@@ -197,12 +255,18 @@ class Constants(BaseModel):
         "text-neutral-900",
         "dark:text-white",
     )
+    """Default css class for {jinjax:component}`Label`."""
+
     P_CLASS: str = space_join(
         "text-base",
         "text-neutral-900",
         "dark:text-white",
     )
+    """Default css class for {jinjax:component}`P`."""
+
     RADIO_DIV_CLASS: str = "flex items-center mb-4"
+    """Default css class for {jinjax:component}`Radio` `<div>` container."""
+
     RADIO_INPUT_CLASS: str = space_join(
         "bg-neutral-100",
         "border-neutral-300",
@@ -216,9 +280,17 @@ class Constants(BaseModel):
         "dark:focus:ring-primary-600",
         "dark:ring-offset-neutral-800",
     )
+    """
+    Default css class for {jinjax:component}`Radio` `<input type="radio">`.
+    """
+
     RADIO_LABEL_CLASS: str = (
         "ms-2 text-sm font-medium text-neutral-900 dark:text-neutral-300"
     )
+    """
+    Default css class for {jinjax:component}`Radio` `<label>` element.
+    """
+
     SELECT_CLASS: str = space_join(
         "bg-neutral-50",
         "block",
@@ -238,6 +310,16 @@ class Constants(BaseModel):
         "dark:placeholder-neutral-400",
         "dark:text-white",
     )
+    """Default css class for {jinjax:component}`Select`."""
+
+    SUMMARY_CLASS: str = "flex items-center items-center font-medium cursor-pointer"
+    """Default css class for {jinjax:component}`Summary`."""
+
     TABLE_CLASS: str = "table-auto w-full text-left border-colapse"
+    """Default css class for {jinjax:component}`Table`."""
+
     TD_CLASS: str = "px-4 py-2 font-normal border-b dark:border-neutral-500"
+    """Default css class for {jinjax:component}`Td`."""
+
     TH_CLASS: str = "px-4 py-2 font-medium border-b dark:border-neutral-500"
+    """Default css class for {jinjax:component}`Th`."""

fastlife/templating/renderer/jinjax.py

@@ -1,22 +1,277 @@
-from typing import TYPE_CHECKING, Any, Mapping, MutableMapping, Optional, Sequence, Type
+"""Template rending based on JinjaX."""
+
+import ast
+import logging
+import re
+import textwrap
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Iterator,
+    Mapping,
+    MutableMapping,
+    Optional,
+    Sequence,
+    Type,
+    cast,
+)
 
 from fastapi import Request
+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
 
-from fastlife.request.model_result import ModelResult
+from fastlife.request.form import FormModel
 from fastlife.templating.renderer.widgets.factory import WidgetFactory
 
 if TYPE_CHECKING:
-    from fastlife.configurator.settings import Settings  # coverage: ignore
+    from fastlife.config.settings import Settings  # coverage: ignore
 
 from fastlife.shared_utils.resolver import resolve, resolve_path
 
 from .abstract import AbstractTemplateRenderer, AbstractTemplateRendererFactory
 
+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 = [l for l 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)
+
+            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):
+        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):
+    __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:
+        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)
+                if expr:
+                    if def_found:
+                        raise DuplicateDefDeclaration(self.name)
+                    def_found = True
+                    continue
+
+                doc = self.read_metadata_item(item, RX_DOC_START)
+                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:
+        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
+
+
+class InspectableCatalog(Catalog):
+    """
+    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]:
+        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
+                )
+
+                to_include = True
+                if includes:
+                    to_include = False
+                    for include in includes:
+                        if include.match(name):
+                            to_include = True
+                            break
+                if to_include and ignores:
+                    for ignore in ignores:
+                        if ignore.match(name):
+                            to_include = False
+                            break
+
+                if to_include:
+                    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
+
 
 def build_searchpath(template_search_path: str) -> Sequence[str]:
+    """
+    Build the path containing templates.
+
+    Path may be absolute directories or directories relative to a python
+    package. For instance, the `fastlife:templates` is the directory templates
+    inside the fastlife installation dir.
+
+    :param template_search_path: list of path separated by a comma (`,`).
+    :return: List resolved path.
+    """
     searchpath: list[str] = []
     paths = template_search_path.split(",")
 
@@ -29,9 +284,11 @@ def build_searchpath(template_search_path: str) -> Sequence[str]:
 
 
 class JinjaxRenderer(AbstractTemplateRenderer):
+    """Render templates using JinjaX."""
+
     def __init__(
         self,
-        catalog: Catalog,
+        catalog: InspectableCatalog,
         request: Request,
         csrf_token_name: str,
         form_data_model_prefix: str,
@@ -45,6 +302,12 @@ class JinjaxRenderer(AbstractTemplateRenderer):
         self.globals: MutableMapping[str, Any] = {}
 
     def build_globals(self) -> Mapping[str, Any]:
+        """
+        Build globals variables accessible in any templates.
+
+        * `request` is the {class}`current request <fastlife.request.request.Request>`
+        * `csrf_token` is used to build for {jinjax:component}`CsrfToken`.
+        """
         return {
             "request": self.request,
             "csrf_token": {
@@ -69,7 +332,7 @@ class JinjaxRenderer(AbstractTemplateRenderer):
         )
 
     def pydantic_form(
-        self, model: ModelResult[Any], *, token: Optional[str] = None
+        self, model: FormModel[Any], *, token: Optional[str] = None
     ) -> Markup:
         return WidgetFactory(self, token).get_markup(model)
 
@@ -112,7 +375,7 @@ class JinjaxTemplateRenderer(AbstractTemplateRendererFactory):
         self.csrf_token_name = settings.csrf_token_name
         globals = resolve(settings.jinjax_global_catalog_class)().model_dump()
 
-        self.catalog = Catalog(
+        self.catalog = InspectableCatalog(
             use_cache=settings.jinjax_use_cache,
             auto_reload=settings.jinjax_auto_reload,
             globals=globals,

fastlife/templating/renderer/widgets/base.py

@@ -19,16 +19,35 @@ def get_title(typ: Type[Any]) -> str:
 
 
 class Widget(abc.ABC, Generic[T]):
+    """
+    Base class for widget of pydantic fields.
+
+    :param name: field name.
+    :param value: field value.
+    :param title: title for the widget.
+    :param hint: hint for human.
+    :param aria_label: html input aria-label value.
+    :param value: current value.
+    :param error: error of the value if any.
+    :param children_types: childrens types list.
+    :param removable: display a button to remove the widget for optional fields.
+    :param token: token used to get unique id on the form.
+    """
+
     name: str
-    "variable name, nested variables have dots"
+    "variable name, nested variables have dots."
+    value: T | None
+    """Value of the field."""
     title: str
-    "Human title for the widget"
+    "Human title for the widget."
+    hint: str
+    "A help message for the the widget."
     aria_label: str
-    "Non visible text alternative"
+    "Non visible text alternative."
     token: str
-    "unique token to ensure id are unique in the DOM"
+    "unique token to ensure id are unique in the DOM."
     removable: bool
-    "Indicate that the widget is removable from the dom"
+    "Indicate that the widget is removable from the dom."
 
     def __init__(
         self,
@@ -37,6 +56,7 @@ class Widget(abc.ABC, Generic[T]):
         value: T | None = None,
         error: str | None = None,
         title: str | None = None,
+        hint: str | None = None,
         token: str | None = None,
         aria_label: str | None = None,
         removable: bool = False,
@@ -45,6 +65,7 @@ class Widget(abc.ABC, Generic[T]):
         self.value = value
         self.error = error
         self.title = title or name.split(".")[-1]
+        self.hint = hint or ""
         self.aria_label = aria_label or ""
         self.token = token or secrets.token_urlsafe(4).replace("_", "-")
         self.removable = removable
@@ -52,10 +73,10 @@ class Widget(abc.ABC, Generic[T]):
 
     @abc.abstractmethod
     def get_template(self) -> str:
-        ...
+        """Get the widget component template."""
 
     def to_html(self, renderer: AbstractTemplateRenderer) -> Markup:
-        """Return the html version"""
+        """Return the html version."""
         return Markup(renderer.render_template(self.get_template(), widget=self))
 
 
@@ -67,6 +88,17 @@ def _get_fullname(typ: Type[Any]) -> str:
 
 
 class TypeWrapper:
+    """
+    Wrap children types for union type.
+
+    :param typ: Wrapped type.
+    :param route_prefix: route prefix used for ajax query to build type.
+    :param name: name of the field wrapped.
+    :param token: unique token to render unique id.
+    :param title: title to display.
+
+    """
+
     def __init__(
         self,
         typ: Type[Any],
@@ -83,19 +115,23 @@ class TypeWrapper:
 
     @property
     def fullname(self) -> str:
+        """Full name for the type."""
         return _get_fullname(self.typ)
 
     @property
     def id(self) -> str:
+        """Unique id to inject in the DOM."""
         name = self.name.replace("_", "-").replace(".", "-").replace(":", "-")
         typ = self.typ.__name__.replace("_", "-")
         return f"{name}-{typ}-{self.token}"
 
     @property
     def params(self) -> Mapping[str, str]:
+        """Params for the widget to render."""
         return {"name": self.name, "token": self.token, "title": self.title}
 
     @property
     def url(self) -> str:
+        """Url to fetch the widget."""
         ret = f"{self.route_prefix}/pydantic-form/widgets/{self.fullname}"
         return ret

fastlife/templating/renderer/widgets/boolean.py

@@ -1,12 +1,31 @@
+"""
+Widget for field of type bool.
+"""
+
 from .base import Widget
 
 
 class BooleanWidget(Widget[bool]):
+    """
+    Widget for field of type bool.
+
+    :param name: field name.
+    :param title: title for the widget.
+    :param hint: hint for human.
+    :param aria_label: html input aria-label value.
+    :param value: current value.
+    :param error: error of the value if any.
+    :param removable: display a button to remove the widget for optional fields.
+    :param token: token used to get unique id on the form.
+    """
+
     def __init__(
         self,
         name: str,
         *,
         title: str | None,
+        hint: str | None = None,
+        aria_label: str | None = None,
         value: bool = False,
         error: str | None = None,
         removable: bool = False,
@@ -15,6 +34,8 @@ class BooleanWidget(Widget[bool]):
         super().__init__(
             name,
             title=title,
+            hint=hint,
+            aria_label=aria_label,
             value=value,
             error=error,
             removable=removable,