fastlifeweb 0.16.4__tar.gz → 0.17.0__tar.gz

{fastlifeweb-0.16.4 → fastlifeweb-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastlifeweb
-Version: 0.16.4
+Version: 0.17.0
 Summary: High-level web framework
 Home-page: https://github.com/mardiros/fastlife
 License: BSD-derived
@@ -37,24 +37,24 @@ Description-Content-Type: text/markdown
 [![Documentation](https://github.com/mardiros/fastlife/actions/workflows/gh-pages.yml/badge.svg)](https://mardiros.github.io/fastlife/)
 [![Continuous Integration](https://github.com/mardiros/fastlife/actions/workflows/main.yml/badge.svg)](https://github.com/mardiros/fastlife/actions/workflows/main.yml)
 [![Coverage Report](https://codecov.io/gh/mardiros/fastlife/graph/badge.svg?token=DTpi73d7mf)](https://codecov.io/gh/mardiros/fastlife)
-
+[![Maintainability](https://api.codeclimate.com/v1/badges/94d107797b15b5e8843e/maintainability)](https://codeclimate.com/github/mardiros/fastlife/maintainability)
 
 > ⚠️ **Under Heavy Development**
 > Please note that this project is still in active development. Features and APIs may change frequently.
 > Even the name is not definitive.
 
-An opinionated Python web framework (based on FastAPI).
+An opinionated Python web framework (based on {term}`FastAPI`).
 
 ## Purpose
 
 Fastlife helps at building Web Application with session, security, html test client,
 and html form generated from pydantic schema using customizable widget.
 
-Templates are made using [JinjaX](https://jinjax.scaletti.dev/) and an extensible [set of
+Templates are made using {term}`JinjaX` and an extensible [set of
 component](https://mardiros.github.io/fastlife/components/index.html) is available
 in order to build pages.
 
-Those components are currently stylized by [tailwindcss](https://tailwindcss.com/),
+Those components are currently stylized by {term}`Tailwind CSS`,
 using [pytailwindcss](https://github.com/timonweb/pytailwindcss).
 
 Moreover, you can also write API, in an opinionated way to enforce documentation
@@ -63,7 +63,7 @@ consistency.
 
 ## First class configuration.
 
-Fastlife is adding a "Configurator", like Pyramid to get a better scallable codebase.
+Fastlife is adding a "Configurator", like {term}`Pyramid` to get a better scallable codebase.
 
 The configurator in fastlife organizes configuration settings hierarchically,
 enabling easy management and overriding at different levels.

{fastlifeweb-0.16.4 → fastlifeweb-0.17.0}/README.md

@@ -3,24 +3,24 @@
 [![Documentation](https://github.com/mardiros/fastlife/actions/workflows/gh-pages.yml/badge.svg)](https://mardiros.github.io/fastlife/)
 [![Continuous Integration](https://github.com/mardiros/fastlife/actions/workflows/main.yml/badge.svg)](https://github.com/mardiros/fastlife/actions/workflows/main.yml)
 [![Coverage Report](https://codecov.io/gh/mardiros/fastlife/graph/badge.svg?token=DTpi73d7mf)](https://codecov.io/gh/mardiros/fastlife)
-
+[![Maintainability](https://api.codeclimate.com/v1/badges/94d107797b15b5e8843e/maintainability)](https://codeclimate.com/github/mardiros/fastlife/maintainability)
 
 > ⚠️ **Under Heavy Development**
 > Please note that this project is still in active development. Features and APIs may change frequently.
 > Even the name is not definitive.
 
-An opinionated Python web framework (based on FastAPI).
+An opinionated Python web framework (based on {term}`FastAPI`).
 
 ## Purpose
 
 Fastlife helps at building Web Application with session, security, html test client,
 and html form generated from pydantic schema using customizable widget.
 
-Templates are made using [JinjaX](https://jinjax.scaletti.dev/) and an extensible [set of
+Templates are made using {term}`JinjaX` and an extensible [set of
 component](https://mardiros.github.io/fastlife/components/index.html) is available
 in order to build pages.
 
-Those components are currently stylized by [tailwindcss](https://tailwindcss.com/),
+Those components are currently stylized by {term}`Tailwind CSS`,
 using [pytailwindcss](https://github.com/timonweb/pytailwindcss).
 
 Moreover, you can also write API, in an opinionated way to enforce documentation
@@ -29,7 +29,7 @@ consistency.
 
 ## First class configuration.
 
-Fastlife is adding a "Configurator", like Pyramid to get a better scallable codebase.
+Fastlife is adding a "Configurator", like {term}`Pyramid` to get a better scallable codebase.
 
 The configurator in fastlife organizes configuration settings hierarchically,
 enabling easy management and overriding at different levels.

{fastlifeweb-0.16.4 → fastlifeweb-0.17.0}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.16.4"
+version = "0.17.0"
 
 [tool.poetry.dependencies]
 python = "^3.11"
@@ -63,6 +63,7 @@ sphinx = "^7.0.1"
 sphinx-autodoc-typehints = "^1.12.0"
 sphinx-autodoc2 = "^0.5.0"
 tomlkit = "^0.12.5"
+linkify-it-py = "^2.0.3"
 
 [tool.pyright]
 include = ["src"]

{fastlifeweb-0.16.4 → fastlifeweb-0.17.0}/src/fastlife/adapters/jinjax/renderer.py

@@ -24,7 +24,7 @@ from markupsafe import Markup
 from pydantic.fields import FieldInfo
 
 from fastlife import Request
-from fastlife.adapters.jinjax.widgets.factory import WidgetFactory
+from fastlife.adapters.jinjax.widget_factory.factory import WidgetFactory
 from fastlife.request.form import FormModel
 from fastlife.request.localizer import get_localizer
 
@@ -221,6 +221,20 @@ def component():
         return ret
 
 
+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.
@@ -247,20 +261,9 @@ class InspectableCatalog(Catalog):
                     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:
+                is_included = to_include(name, ignores, includes)
+
+                if is_included:
                     component = InspectableComponent(
                         name=name, prefix=prefix, path=path, source=path.read_text()
                     )
@@ -340,6 +343,14 @@ class JinjaxRenderer(AbstractTemplateRenderer):
         globals: Mapping[str, Any] | None = None,
         **params: Any,
     ) -> 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.
+        """
         # 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]
@@ -357,6 +368,13 @@ class JinjaxRenderer(AbstractTemplateRenderer):
     def pydantic_form(
         self, model: FormModel[Any], *, token: str | None = None
     ) -> Markup:
+        """
+        Generate HTML markup to build a form from the given form model.
+
+        :param model: the form model that will be transformed to markup.
+        :param token: a token used to ensure that unique identifier are unique.
+        :return: HTML Markup generated by composign fields widgets.
+        """
         return WidgetFactory(self, token).get_markup(model)
 
     def pydantic_form_field(
@@ -368,6 +386,17 @@ class JinjaxRenderer(AbstractTemplateRenderer):
         removable: bool,
         field: FieldInfo | None,
     ) -> Markup:
+        """
+        Generate HTML for a particular field in a form.
+
+        This function is used to generate union subtypes in Ajax requests.
+        :param model: a pydantic or python builtin type that is requests to be rendered
+        :param name: name for the field
+        :param token: the token of the form to render unique identifiers
+        :param removable: add a way let the user remove the widget
+        :param field: only render this particular field for the model.
+        :return: HTML Markup.
+        """
         return (
             WidgetFactory(self, token)
             .get_widget(

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/__init__.py

@@ -0,0 +1 @@
+"""Factory for widgets in order to edit pydantic model."""

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/base.py

@@ -0,0 +1,38 @@
+"""Abstract class for builder."""
+
+import abc
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+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
+
+T = TypeVar("T")
+
+
+class BaseWidgetBuilder(abc.ABC, Generic[T]):
+    """Base class for the builder of widget."""
+
+    def __init__(self, factory: "WidgetFactory") -> None:
+        self.factory = factory
+
+    @abc.abstractmethod
+    def accept(self, typ: type[Any], origin: type[Any] | None) -> bool:
+        """Return true if the builder accept to build a widget for this type."""
+
+    @abc.abstractmethod
+    def build(
+        self,
+        *,
+        field_name: str,
+        field_type: type[Any],
+        field: FieldInfo | None,
+        value: T | None,
+        form_errors: Mapping[str, Any],
+        removable: bool,
+    ) -> Widget[T]:
+        """Build the widget"""

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/bool_builder.py

@@ -0,0 +1,43 @@
+"""Handle boolean values."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic.fields import FieldInfo
+
+from fastlife.adapters.jinjax.widget_factory.base import BaseWidgetBuilder
+from fastlife.adapters.jinjax.widgets.boolean import BooleanWidget
+
+
+class BoolBuilder(BaseWidgetBuilder[bool]):
+    """Builder for boolean."""
+
+    def accept(self, typ: type[Any], origin: type[Any] | None) -> bool:
+        """True for boolean."""
+        return issubclass(typ, bool)
+
+    def build(
+        self,
+        *,
+        field_name: str,
+        field_type: type[Any],
+        field: FieldInfo | None,
+        value: bool | None,
+        form_errors: Mapping[str, Any],
+        removable: bool,
+    ) -> BooleanWidget:
+        """Build the widget."""
+        return BooleanWidget(
+            field_name,
+            removable=removable,
+            title=field.title if field else "",
+            hint=field.description if field else None,
+            aria_label=(
+                field.json_schema_extra.get("aria_label")  # type:ignore
+                if field and field.json_schema_extra
+                else None
+            ),
+            token=self.factory.token,
+            value=value or False,
+            error=form_errors.get(field_name),
+        )

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/emailstr_builder.py

@@ -0,0 +1,46 @@
+"""Handle EmailStr pydantic type."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic.fields import FieldInfo
+from pydantic.networks import EmailStr
+
+from fastlife.adapters.jinjax.widget_factory.base import BaseWidgetBuilder
+from fastlife.adapters.jinjax.widgets.text import TextWidget
+
+
+class EmailStrBuilder(BaseWidgetBuilder[EmailStr]):
+    """Builder for Pydantic EmailStr."""
+
+    def accept(self, typ: type[Any], origin: type[Any] | None) -> bool:
+        """True for EmailStr."""
+        return issubclass(typ, EmailStr)  # type: ignore
+
+    def build(
+        self,
+        *,
+        field_name: str,
+        field_type: type[Any],
+        field: FieldInfo | None,
+        value: EmailStr | None,
+        form_errors: Mapping[str, Any],
+        removable: bool,
+    ) -> TextWidget:
+        """Build the widget."""
+        return TextWidget(
+            field_name,
+            input_type="email",
+            placeholder=str(field.examples[0]) if field and field.examples else None,
+            removable=removable,
+            title=field.title if field else "",
+            hint=field.description if field else None,
+            aria_label=(
+                field.json_schema_extra.get("aria_label")  # type:ignore
+                if field and field.json_schema_extra
+                else None
+            ),
+            token=self.factory.token,
+            value=str(value),
+            error=form_errors.get(field_name),
+        )

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/enum_builder.py

@@ -0,0 +1,47 @@
+"""Handle Enum type."""
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+from pydantic.fields import FieldInfo
+
+from fastlife.adapters.jinjax.widget_factory.base import BaseWidgetBuilder
+from fastlife.adapters.jinjax.widgets.base import Widget
+from fastlife.adapters.jinjax.widgets.dropdown import DropDownWidget
+
+
+class EnumBuilder(BaseWidgetBuilder[Enum]):
+    """Builder for Enum."""
+
+    def accept(self, typ: type[Any], origin: type[Any] | None) -> bool:
+        """True for Enum."""
+        return issubclass(typ, Enum)
+
+    def build(
+        self,
+        *,
+        field_name: str,
+        field_type: type[Any],  # an enum subclass
+        field: FieldInfo | None,
+        value: Enum | None,  # str | int | float,
+        form_errors: Mapping[str, Any],
+        removable: bool,
+    ) -> Widget[Enum]:
+        """Build the widget."""
+        options = [(item.name, item.value) for item in field_type]  # type: ignore
+        return DropDownWidget(
+            field_name,
+            options=options,  # type: ignore
+            removable=removable,
+            title=field.title if field else "",
+            hint=field.description if field else None,
+            aria_label=(
+                field.json_schema_extra.get("aria_label")  # type:ignore
+                if field and field.json_schema_extra
+                else None
+            ),
+            token=self.factory.token,
+            value=str(value),
+            error=form_errors.get(field_name),
+        )

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/factory.py

@@ -0,0 +1,165 @@
+"""
+Create markup for pydantic forms.
+"""
+
+import secrets
+from collections.abc import Mapping
+from inspect import isclass
+from typing import Any, cast, get_origin
+
+from markupsafe import Markup
+from pydantic.fields import FieldInfo
+
+from fastlife.adapters.jinjax.widgets.base import Widget
+from fastlife.request.form import FormModel
+from fastlife.services.templates import AbstractTemplateRenderer
+
+from .base import BaseWidgetBuilder
+from .bool_builder import BoolBuilder
+from .emailstr_builder import EmailStrBuilder
+from .enum_builder import EnumBuilder
+from .literal_builder import LiteralBuilder
+from .model_builder import ModelBuilder
+from .secretstr_builder import SecretStrBuilder
+from .sequence_builder import SequenceBuilder
+from .set_builder import SetBuilder
+from .simpletype_builder import SimpleTypeBuilder
+from .union_builder import UnionBuilder
+
+
+class WidgetFactory:
+    """
+    Form builder for pydantic model.
+
+    :param renderer: template engine to render widget.
+    :param token: reuse a token.
+    """
+
+    def __init__(self, renderer: AbstractTemplateRenderer, token: str | None = None):
+        self.renderer = renderer
+        self.token = token or secrets.token_urlsafe(4).replace("_", "-")
+        self.builders: list[BaseWidgetBuilder[Any]] = [
+            # Order is super important here
+            # starts by the union type
+            UnionBuilder(self),
+            # and to other types that have an origin
+            SetBuilder(self),
+            LiteralBuilder(self),
+            SequenceBuilder(self),
+            # from this part, order does not really matter
+            ModelBuilder(self),
+            BoolBuilder(self),
+            EnumBuilder(self),
+            EmailStrBuilder(self),
+            SecretStrBuilder(self),
+            # we keep simple types, str, int at the end
+            SimpleTypeBuilder(self),
+        ]
+
+    def get_markup(
+        self,
+        model: FormModel[Any],
+        *,
+        removable: bool = False,
+        field: FieldInfo | None = None,
+    ) -> Markup:
+        """
+        Get the markup for the given model.
+
+        :param model: the model to build the html markup.
+        :param removable: Include a button to remove the model in the markup.
+        :param field: only build the markup of this field is not None.
+        """
+        return self.get_widget(
+            model.model.__class__,
+            model.form_data,
+            model.errors,
+            prefix=model.prefix,
+            removable=removable,
+            field=field,
+        ).to_html(self.renderer)
+
+    def get_widget(
+        self,
+        base: type[Any],
+        form_data: Mapping[str, Any],
+        form_errors: Mapping[str, Any],
+        *,
+        prefix: str,
+        removable: bool,
+        field: FieldInfo | None = None,
+    ) -> Widget[Any]:
+        """
+        build the widget for the given type and return it.
+        :param base: the type to build, it has to be a builtin or a Pydantic model.
+        :param form_data: form values to render.
+        :param form_errors: form errors to render.
+        """
+        return self.build(
+            base,
+            value=form_data.get(prefix, {}),
+            form_errors=form_errors,
+            name=prefix,
+            removable=removable,
+            field=field,
+        )
+
+    def build(
+        self,
+        typ: type[Any],
+        *,
+        name: str = "",
+        value: Any,
+        removable: bool,
+        form_errors: Mapping[str, Any],
+        field: FieldInfo | None = None,
+    ) -> Widget[Any]:
+        """
+        build widget tree for the given type.
+        This function is recurive and shoud not be used directly.
+        The type is a composite, it can be pydantic model, builtin, list or unions.
+
+        The {meth}`WidgetFactory.get_widget` or {meth}`WidgetFactory.get_markup`
+        should be used.
+
+        :param typ: the type to build, it has to be a builtin or a Pydantic model.
+        :param name: name of the widget to build.
+        :param value: value for the widget.
+        :param removable: True if it has to include a remove button.
+        :param form_errors: errors in the form.
+        :param field: field information used to customize the widget.
+        """
+        if field and field.metadata:
+            for widget in field.metadata:
+                if isclass(widget) and issubclass(widget, Widget):
+                    return cast(
+                        Widget[Any],
+                        widget(
+                            name,
+                            value=value,
+                            removable=removable,
+                            title=field.title if field else "",
+                            hint=field.description if field else None,
+                            aria_label=(
+                                field.json_schema_extra.get("aria_label")  # type:ignore
+                                if field and field.json_schema_extra
+                                else None
+                            ),
+                            token=self.token,
+                            error=form_errors.get(name),
+                        ),
+                    )
+
+        type_origin = get_origin(typ)
+        for builder in self.builders:
+            if builder.accept(typ, type_origin):
+                return builder.build(
+                    field_name=name,
+                    field_type=typ,
+                    field=field,
+                    value=value,
+                    form_errors=form_errors,
+                    removable=removable,
+                )
+
+        raise NotImplementedError(f"{typ} not implemented")  # coverage: ignore

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/literal_builder.py

@@ -0,0 +1,52 @@
+"""Handle Literal type."""
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+from pydantic.fields import FieldInfo
+
+from fastlife.adapters.jinjax.widget_factory.base import BaseWidgetBuilder
+from fastlife.adapters.jinjax.widgets.dropdown import DropDownWidget
+from fastlife.adapters.jinjax.widgets.hidden import HiddenWidget
+
+
+class LiteralBuilder(BaseWidgetBuilder[str]):  # str|int|bool
+    """Builder for Literal."""
+
+    def accept(self, typ: type[Any], origin: type[Any] | None) -> bool:
+        """True for Literal."""
+        return origin is Literal
+
+    def build(
+        self,
+        *,
+        field_name: str,
+        field_type: type[Any],  # a literal actually
+        field: FieldInfo | None,
+        value: str | None,
+        form_errors: Mapping[str, Any],
+        removable: bool,
+    ) -> HiddenWidget | DropDownWidget:
+        """Build the widget."""
+        choices: list[str] = field_type.__args__  # type: ignore
+        if len(choices) == 1:
+            return HiddenWidget(
+                field_name,
+                value=choices[0],
+                token=self.factory.token,
+            )
+        return DropDownWidget(
+            field_name,
+            options=choices,
+            removable=removable,
+            title=field.title if field else "",
+            hint=field.description if field else None,
+            aria_label=(
+                field.json_schema_extra.get("aria_label")  # type:ignore
+                if field and field.json_schema_extra
+                else None
+            ),
+            token=self.factory.token,
+            value=str(value),
+            error=form_errors.get(field_name),
+        )

fastlifeweb-0.17.0/src/fastlife/adapters/jinjax/widget_factory/model_builder.py

@@ -0,0 +1,64 @@
+"""Handle Pydantic BaseModel type."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+
+from fastlife.adapters.jinjax.widget_factory.base import BaseWidgetBuilder
+from fastlife.adapters.jinjax.widgets.base import Widget
+from fastlife.adapters.jinjax.widgets.model import ModelWidget
+
+
+class ModelBuilder(BaseWidgetBuilder[Mapping[str, Any]]):
+    """Builder for Pydantic BaseModel values."""
+
+    def accept(self, typ: type[Any], origin: type[Any] | None) -> bool:
+        """True for Pydantic BaseModel."""
+        return issubclass(typ, BaseModel)
+
+    def build(
+        self,
+        *,
+        field_name: str,
+        field_type: type[BaseModel],
+        field: FieldInfo | None,
+        value: Mapping[str, Any] | None,
+        form_errors: Mapping[str, Any],
+        removable: bool,
+    ) -> Widget[Any]:
+        """Build the widget."""
+        value = value or {}
+        ret: dict[str, Any] = {}
+        for key, child_field in field_type.model_fields.items():
+            child_key = f"{field_name}.{key}" if field_name else key
+            if child_field.exclude:
+                continue
+            if child_field.annotation is None:
+                raise ValueError(  # coverage: ignore
+                    f"Missing annotation for {child_field} in {child_key}"
+                )
+            ret[key] = self.factory.build(
+                child_field.annotation,
+                name=child_key,
+                field=child_field,
+                value=value.get(key),
+                form_errors=form_errors,
+                removable=False,
+            )
+        return ModelWidget(
+            field_name,
+            value=list(ret.values()),
+            removable=removable,
+            title=field.title if field and field.title else "",
+            hint=field.description if field else None,
+            aria_label=(
+                field.json_schema_extra.get("aria_label")  # type:ignore
+                if field and field.json_schema_extra
+                else None
+            ),
+            token=self.factory.token,
+            error=form_errors.get(field_name),
+            nested=field is not None,
+        )