fh-pydantic-form 0.1.2__py3-none-any.whl

fh_pydantic_form/registry.py

@@ -0,0 +1,145 @@
+from logging import getLogger
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+)
+
+from pydantic.fields import FieldInfo
+
+from fh_pydantic_form.type_helpers import _get_underlying_type_if_optional
+
+logger = getLogger(__name__)
+
+
+class FieldRendererRegistry:
+    """
+    Registry for field renderers with support for type and predicate-based registration
+
+    This registry manages:
+    - Type-specific renderers (e.g., for str, int, bool)
+    - Type-name-specific renderers (by class name)
+    - Predicate-based renderers (e.g., for Literal fields)
+    - List item renderers for specialized list item rendering
+
+    It uses a singleton pattern to ensure consistent registration across the app.
+    """
+
+    _instance = None  # Add class attribute to hold the single instance
+
+    # Use ClassVar for all registry storage
+    _type_renderers: ClassVar[Dict[Type, Any]] = {}
+    _type_name_renderers: ClassVar[Dict[str, Any]] = {}
+    _predicate_renderers: ClassVar[List[Tuple[Any, Any]]] = []
+    _list_item_renderers: ClassVar[Dict[Type, Any]] = {}
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            logger.debug("Creating new FieldRendererRegistry singleton instance.")
+            cls._instance = super().__new__(cls)
+        else:
+            logger.debug("Returning existing FieldRendererRegistry singleton instance.")
+        return cls._instance
+
+    @classmethod
+    def register_type_renderer(cls, field_type: Type, renderer_cls: Any) -> None:
+        """Register a renderer for a field type"""
+        cls._type_renderers[field_type] = renderer_cls
+
+    @classmethod
+    def register_type_name_renderer(
+        cls, field_type_name: str, renderer_cls: Any
+    ) -> None:
+        """Register a renderer for a specific field type name"""
+        cls._type_name_renderers[field_type_name] = renderer_cls
+
+    @classmethod
+    def register_type_renderer_with_predicate(cls, predicate_func, renderer_cls):
+        """
+        Register a renderer with a predicate function
+
+        The predicate function should accept a field_info parameter and return
+        True if the renderer should be used for that field.
+        """
+        cls._predicate_renderers.append((predicate_func, renderer_cls))
+
+    @classmethod
+    def register_list_item_renderer(cls, item_type: Type, renderer_cls: Any) -> None:
+        """Register a renderer for list items of a specific type"""
+        cls._list_item_renderers[item_type] = renderer_cls
+
+    @classmethod
+    def get_renderer(cls, field_name: str, field_info: FieldInfo) -> Any:
+        """
+        Get the appropriate renderer for a field
+
+        The selection algorithm:
+        1. Check exact type matches
+        2. Check predicate renderers (for special cases like Literal fields)
+        3. Check for subclass relationships
+        4. Fall back to string renderer
+
+        Args:
+            field_name: The name of the field being rendered
+            field_info: The FieldInfo for the field
+
+        Returns:
+            A renderer class appropriate for the field
+        """
+        # Get the field type (unwrap Optional if present)
+        original_annotation = field_info.annotation
+        field_type = _get_underlying_type_if_optional(original_annotation)
+
+        # 1. Check exact type matches first
+        if field_type in cls._type_renderers:
+            return cls._type_renderers[field_type]
+
+        # 2. Check predicates second
+        for predicate, renderer in cls._predicate_renderers:
+            if predicate(field_info):
+                return renderer
+
+        # 3. Check for subclass relationships
+        if isinstance(field_type, type):
+            for typ, renderer in cls._type_renderers.items():
+                try:
+                    if isinstance(typ, type) and issubclass(field_type, typ):
+                        return renderer
+                except TypeError:
+                    # Handle non-class types
+                    continue
+
+        # 4. Fall back to string renderer
+        from_imports = globals()
+        return from_imports.get("StringFieldRenderer", None)
+
+    @classmethod
+    def get_list_item_renderer(cls, item_type: Type) -> Optional[Any]:
+        """
+        Get renderer for summarizing list items of a given type
+
+        Args:
+            item_type: The type of the list items
+
+        Returns:
+            A renderer class for list items, or None if none is registered
+        """
+        # Check for exact type match
+        if item_type in cls._list_item_renderers:
+            return cls._list_item_renderers[item_type]
+
+        # Check for subclass matches
+        for registered_type, renderer in cls._list_item_renderers.items():
+            try:
+                if isinstance(registered_type, type) and issubclass(
+                    item_type, registered_type
+                ):
+                    return renderer
+            except TypeError:
+                continue
+
+        return None

fh_pydantic_form/type_helpers.py

@@ -0,0 +1,42 @@
+from typing import Any, Literal, Union, get_args, get_origin
+
+
+def _is_optional_type(annotation: Any) -> bool:
+    """
+    Check if an annotation is Optional[T] (Union[T, None]).
+
+    Args:
+        annotation: The type annotation to check
+
+    Returns:
+        True if the annotation is Optional[T], False otherwise
+    """
+    origin = get_origin(annotation)
+    if origin is Union:
+        args = get_args(annotation)
+        # Check if NoneType is one of the args and there are exactly two args
+        return len(args) == 2 and type(None) in args
+    return False
+
+
+def _get_underlying_type_if_optional(annotation: Any) -> Any:
+    """
+    Extract the type T from Optional[T], otherwise return the original annotation.
+
+    Args:
+        annotation: The type annotation, potentially Optional[T]
+
+    Returns:
+        The underlying type if Optional, otherwise the original annotation
+    """
+    if _is_optional_type(annotation):
+        args = get_args(annotation)
+        # Return the non-None type
+        return args[0] if args[1] is type(None) else args[1]
+    return annotation
+
+
+def _is_literal_type(annotation: Any) -> bool:
+    """Check if the underlying type of an annotation is Literal."""
+    underlying_type = _get_underlying_type_if_optional(annotation)
+    return get_origin(underlying_type) is Literal

fh_pydantic_form-0.1.2.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: fh-pydantic-form
+Version: 0.1.2
+Summary: a library to turn any pydantic BaseModel object into a fasthtml/monsterui input form
+Project-URL: Homepage, https://github.com/Marcura/fh-pydantic-form
+Project-URL: Repository, https://github.com/Marcura/fh-pydantic-form
+Project-URL: Documentation, https://github.com/Marcura/fh-pydantic-form
+Author-email: Oege Dijk <o.dijk@marcura.com>
+Maintainer-email: Oege Dijk <o.dijk@marcura.com>
+License-File: LICENSE
+Keywords: fasthtml,forms,monsterui,pydantic,ui,web
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: monsterui>=1.0.19
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-fasthtml>=0.12.12
+Description-Content-Type: text/markdown
+
+# fh-pydantic-form
+
+**Generate HTML forms from Pydantic models for your FastHTML applications.**
+
+`fh-pydantic-form` simplifies creating web forms for [FastHTML](https://github.com/AnswerDotAI/fasthtml) by automatically generating the necessary HTML input elements based on your Pydantic model definitions. It integrates seamlessly with  and leverages [MonsterUI](https://github.com/AnswerDotAI/monsterui) components for styling.
+
+<details >
+    <summary>show demo screen recording</summary>
+<video src="https://private-user-images.githubusercontent.com/27999937/436237879-feabf388-22af-43e6-b054-f103b8a1b6e6.mp4" controls="controls" style="max-width: 730px;">
+</video>
+</details>
+
+## Purpose
+
+-   **Reduce Boilerplate:** Automatically render form inputs (text, number, checkbox, select, date, time, etc.) based on Pydantic field types and annotations.
+-   **Data Validation:** Leverage Pydantic's validation rules directly from form submissions.
+-   **Nested Structures:** Support for nested Pydantic models and lists of models/simple types.
+-   **Dynamic Lists:** Built-in HTMX endpoints and JavaScript for adding, deleting, and reordering items in lists within the form.
+-   **Customization:** Easily register custom renderers for specific Pydantic types or fields.
+
+## Installation
+
+You can install `fh-pydantic-form` using either `pip` or `uv`.
+
+**Using pip:**
+
+```bash
+pip install fh-pydantic-form
+```
+
+Using uv:
+```bash
+uv add fh-pydantic-form
+```
+
+This will also install necessary dependencies like `pydantic`, `python-fasthtml`, and `monsterui`.
+
+
+# Basic Usage
+
+
+```python
+
+# examples/simple_example.py
+import fasthtml.common as fh
+import monsterui.all as mui
+from pydantic import BaseModel, ValidationError
+
+# 1. Import the form renderer
+from fh_pydantic_form import PydanticForm
+
+app, rt = fh.fast_app(
+    hdrs=[
+        mui.Theme.blue.headers(),
+        # Add list_manipulation_js() if using list fields
+        # from fh_pydantic_form import list_manipulation_js
+        # list_manipulation_js(),
+    ],
+    pico=False, # Using MonsterUI, not PicoCSS
+    live=True,  # Enable live reload for development
+)
+
+# 2. Define your Pydantic model
+class SimpleModel(BaseModel):
+    """Model representing a simple form"""
+    name: str = "Default Name"
+    age: int
+    is_active: bool = True
+
+# 3. Create a form renderer instance
+#    - 'my_form': Unique name for the form (used for prefixes and routes)
+#    - SimpleModel: The Pydantic model class
+form_renderer = PydanticForm("my_form", SimpleModel)
+
+# (Optional) Register list manipulation routes if your model has List fields
+# form_renderer.register_routes(app)
+
+# 4. Define routes
+@rt("/")
+def get():
+    """Display the form"""
+    return fh.Div(
+        mui.Container(
+            mui.Card(
+                mui.CardHeader("Simple Pydantic Form"),
+                mui.CardBody(
+                    # Use MonsterUI Form component for structure
+                    mui.Form(
+                        # Render the inputs using the renderer
+                        form_renderer.render_inputs(),
+                        # Add standard form buttons
+                        mui.Button("Submit", type="submit", cls=mui.ButtonT.primary),
+                        # HTMX attributes for form submission
+                        hx_post="/submit_form",
+                        hx_target="#result", # Target div for response
+                        hx_swap="innerHTML",
+                        # Set a unique ID for the form itself for refresh/reset inclusion
+                        id=f"{form_renderer.name}-form",
+                    )
+                ),
+            ),
+            # Div to display validation results
+            fh.Div(id="result"),
+        ),
+    )
+
+@rt("/submit_form")
+async def post_submit_form(req):
+    """Handle form submission and validation"""
+    try:
+        # 5. Validate the request data against the model
+        validated_data: SimpleModel = await form_renderer.model_validate_request(req)
+
+        # Success: Display the validated data
+        return mui.Card(
+            mui.CardHeader(fh.H3("Validation Successful")),
+            mui.CardBody(
+                fh.Pre(
+                    validated_data.model_dump_json(indent=2),
+                )
+            ),
+            cls="mt-4",
+        )
+    except ValidationError as e:
+        # Validation Error: Display the errors
+        return mui.Card(
+            mui.CardHeader(fh.H3("Validation Error", cls="text-red-500")),
+            mui.CardBody(
+                fh.Pre(
+                    e.json(indent=2),
+                )
+            ),
+            cls="mt-4",
+        )
+
+if __name__ == "__main__":
+    fh.serve()
+
+```
+## Key Features
+
+-   **Automatic Field Rendering:** Handles `str`, `int`, `float`, `bool`, `date`, `time`, `Optional`, `Literal`, nested `BaseModel`s, and `List`s out-of-the-box.
+-   **Sensible Defaults:** Uses appropriate HTML5 input types (`text`, `number`, `date`, `time`, `checkbox`, `select`).
+-   **Labels & Placeholders:** Generates labels from field names (converting snake_case to Title Case) and basic placeholders.
+-   **Descriptions as Tooltips:** Uses `Field(description=...)` from Pydantic to create tooltips (`uk-tooltip` via UIkit).
+-   **Required Fields:** Automatically adds the `required` attribute based on field definitions (considering `Optional` and defaults).
+-   **Disabled Fields:** Disable the whole form with `disabled=True` or disable specific fields with `disabled_fields`
+-   **Collapsible Nested Models:** Renders nested Pydantic models in collapsible details/summary elements for better form organization and space management.
+-   **List Manipulation:**
+    -   Renders lists of simple types or models in accordion-style cards with an enhanced UI.
+    -   Provides HTMX endpoints (registered via `register_routes`) for adding and deleting list items.
+    -   Includes JavaScript (`list_manipulation_js()`) for client-side reordering (moving items up/down).
+-   **Form Refresh & Reset:**
+    -   Provides HTMX-powered "Refresh" and "Reset" buttons (`form_renderer.refresh_button()`, `form_renderer.reset_button()`).
+    -   Refresh updates list item summaries or other dynamic parts without full page reload.
+    -   Reset reverts the form to its initial values.
+-   **Custom Renderers:** Register your own `BaseFieldRenderer` subclasses for specific Pydantic types or complex field logic using `FieldRendererRegistry` or by passing `custom_renderers` during `PydanticForm` initialization.
+-   **Form Data Parsing:** Includes logic (`form_renderer.parse` and `form_renderer.model_validate_request`) to correctly parse submitted form data (handling prefixes, list indices, nested structures, boolean checkboxes, etc.) back into a dictionary suitable for Pydantic validation.
+
+## disabled fields
+
+You can disable the full form with `PydanticForm("my_form", FormModel, disabled=True)` or disable specific fields with `PydanticForm("my_form", FormModel, disabled_fields=["field1", "field3"])`.
+
+ 
+## Manipulating lists fields 
+
+When you have `BaseModels` with fields that are e.g. `List[str]` or even `List[BaseModel]` you want to be able to easily edit the list by adding, deleting and moving items. For this we need a little bit of javascript and register some additional routes:
+
+```python
+from fh_pydantic_form import PydanticForm, list_manipulation_js
+
+app, rt = fh.fast_app(
+    hdrs=[
+        mui.Theme.blue.headers(),
+        list_manipulation_js(),
+    ],
+    pico=False,
+    live=True,
+)
+
+
+class ListModel(BaseModel):
+    name: str = ""
+    tags: List[str] = Field(["tag1", "tag2"])
+
+
+form_renderer = PydanticForm("list_model", ListModel)
+form_renderer.register_routes(app)
+```
+
+## Refreshing and resetting the form
+
+You can set the initial values of the form by passing an instantiated BaseModel:
+
+```python
+form_renderer = PydanticForm("my_form", ListModel, initial_values=ListModel(name="John", tags=["happy", "joy"]))
+```
+
+You can reset the form back to these initial values by adding a `form_render.reset_button()` to your UI:
+
+```python
+mui.Form(
+    form_renderer.render_inputs(),
+    fh.Div(
+        mui.Button("Validate and Show JSON",cls=mui.ButtonT.primary,),
+        form_renderer.refresh_button(),
+        form_renderer.reset_button(),
+    ),
+    hx_post="/submit_form",
+    hx_target="#result",
+    hx_swap="innerHTML",
+)
+```
+
+The refresh button 🔄 refreshes the list item labels. These are rendered initially to summarize the underlying item, but do not automatically update after editing unless refreshed. You can also use the 🔄 icon next to the list field label. 
+
+
+## Custom renderers
+
+The library is extensible by adding your own input renderers for your types. This can be used to override e.g. the default BaseModelFieldRenderer for nested BaseModels, but also to register types that are not (yet) supported (but submit a PR then as well!)
+
+You can register a renderer based on type, type str, or a predicate function:
+
+```python
+from fh_pydantic_form import FieldRendererRegistry
+
+from fh_pydantic_form.field_renderers import BaseFieldRenderer
+
+class CustomDetail(BaseModel):
+    value: str = "Default value"
+    confidence: Literal["HIGH", "MEDIUM", "LOW"] = "MEDIUM"
+
+    def __str__(self) -> str:
+        return f"{self.value} ({self.confidence})"
+
+
+class CustomDetailFieldRenderer(BaseFieldRenderer):
+    """display value input and dropdown side by side"""
+
+    def render_input(self):
+        value_input = fh.Div(
+            mui.Input(
+                value=self.value.get("value", ""),
+                id=f"{self.field_name}_value",
+                name=f"{self.field_name}_value",
+                placeholder=f"Enter {self.original_field_name.replace('_', ' ')} value",
+                cls="uk-input w-full",  
+            ),
+            cls="flex-grow", # apply some custom css
+        )
+
+        confidence_options_ft = [
+            fh.Option(
+                opt, value=opt, selected=(opt == self.value.get("confidence", "MEDIUM"))
+            )
+            for opt in ["HIGH", "MEDIUM", "LOW"]
+        ]
+
+        confidence_select = mui.Select(
+            *confidence_options_ft,
+            id=f"{self.field_name}_confidence",
+            name=f"{self.field_name}_confidence",
+            cls_wrapper="w-[110px] min-w-[110px] flex-shrink-0",  # apply some custom css
+        )
+
+        return fh.Div(
+            value_input,
+            confidence_select,
+            cls="flex items-start gap-2 w-full",  # apply some custom css
+        )
+
+
+# these are all equivalent. You can either register the type directly
+FieldRendererRegistry.register_type_renderer(CustomDetail, CustomDetailFieldRender)
+# or just by the name of the type
+FieldRendererRegistry.register_type_name_renderer("CustomDetail", CustomDetailFieldRender)
+# or register I predicate function
+FieldRendererRegistry.register_type_renderer_with_predicate(lambda: x: isinstance(x, CustomDetail), CustomDetailFieldRender)
+```
+
+You can also pass these directly to the `PydanticForm` with the custom_renderers argument:
+
+```python
+
+form_renderer = PydanticForm(
+    form_name="main_form",
+    model_class=ComplexSchema,
+    initial_values=initial_values,
+    custom_renderers=[
+        (CustomDetail, CustomDetailFieldRenderer)
+    ],  # Register Detail renderer
+)
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to open an issue or submit a pull request.
+
+
+
+
+

fh_pydantic_form-0.1.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+fh_pydantic_form/__init__.py,sha256=oifnGdBOS1XaO9Q8gcZ1SJ98Xzz9TfbZH9kvHg9_beo,3056
+fh_pydantic_form/field_renderers.py,sha256=zgGEgR09Oop_-lyYvcHw52L7Uz4X26dWcxyFqUCBSN0,39461
+fh_pydantic_form/form_parser.py,sha256=3EGy4YHbLskH76V0ieTG8zmQ0b02ty8bOZf9AEg89ZY,20629
+fh_pydantic_form/form_renderer.py,sha256=U4njGebyysKEy88wd2oSf756nndXm1qYc0Dxm_ltmH8,27709
+fh_pydantic_form/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fh_pydantic_form/registry.py,sha256=sufK-85ST3rc3Vu0XmjjjdTqTAqgHr_ZbMGU0xRgTK8,4996
+fh_pydantic_form/type_helpers.py,sha256=ZCU8m4xxFk_ofMsAwxb8CunZhsDBsrEFjpJdtncreT0,1322
+fh_pydantic_form-0.1.2.dist-info/METADATA,sha256=D6xJkgYCio3dhL4m1JIwa2L26kSRIo9MrR3dPYZXAKY,12555
+fh_pydantic_form-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fh_pydantic_form-0.1.2.dist-info/licenses/LICENSE,sha256=AOi2eNK3D2aDycRHfPRiuACZ7WPBsKHTV2tTYNl7cls,577
+fh_pydantic_form-0.1.2.dist-info/RECORD,,

fh_pydantic_form-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fh_pydantic_form-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,13 @@
+   Copyright 2025 Marcura
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.