fh-pydantic-form 0.3.5__tar.gz → 0.3.7__tar.gz

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/.github/workflows/build.yaml

@@ -27,6 +27,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
+          cache-dependency-glob: "uv.lock"
 
       - name: "Set up Python"
         uses: actions/setup-python@v5

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fh-pydantic-form
-Version: 0.3.5
+Version: 0.3.7
 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
@@ -480,6 +480,83 @@ form_renderer = PydanticForm(
 
 This automatic default injection means you can safely exclude fields that shouldn't be user-editable while maintaining data integrity.
 
+### SkipJsonSchema Fields
+
+`fh-pydantic-form` provides advanced handling for `SkipJsonSchema` fields with selective visibility control. By default, fields marked with `SkipJsonSchema` are hidden from forms, but you can selectively show specific ones using the `keep_skip_json_fields` parameter.
+
+```python
+from pydantic.json_schema import SkipJsonSchema
+
+class DocumentModel(BaseModel):
+    title: str
+    content: str
+    
+    # Hidden by default - system fields
+    document_id: SkipJsonSchema[str] = Field(
+        default_factory=lambda: f"doc_{uuid4().hex[:12]}",
+        description="Internal document ID"
+    )
+    created_at: SkipJsonSchema[datetime.datetime] = Field(
+        default_factory=datetime.datetime.now,
+        description="Creation timestamp"
+    )
+    version: SkipJsonSchema[int] = Field(
+        default=1, 
+        description="Document version"
+    )
+
+# Normal form - all SkipJsonSchema fields hidden
+form_normal = PydanticForm("doc_form", DocumentModel)
+
+# Admin form - selectively show some SkipJsonSchema fields
+form_admin = PydanticForm(
+    "admin_form", 
+    DocumentModel,
+    keep_skip_json_fields=[
+        "document_id",  # Show document ID
+        "version",      # Show version number
+        # created_at remains hidden
+    ]
+)
+```
+
+#### Nested SkipJsonSchema Fields
+
+The feature supports dot notation for nested objects and list items:
+
+```python
+class Address(BaseModel):
+    street: str
+    city: str
+    # Hidden system field
+    internal_id: SkipJsonSchema[str] = Field(default_factory=lambda: f"addr_{uuid4().hex[:8]}")
+
+class UserModel(BaseModel):
+    name: str
+    main_address: Address
+    other_addresses: List[Address]
+
+# Show specific nested SkipJsonSchema fields
+form = PydanticForm(
+    "user_form",
+    UserModel,
+    keep_skip_json_fields=[
+        "main_address.internal_id",        # Show main address ID
+        "other_addresses.internal_id",     # Show all address IDs in the list
+    ]
+)
+```
+
+**Key Features:**
+- **Hidden by default:** SkipJsonSchema fields are automatically excluded from forms
+- **Selective visibility:** Use `keep_skip_json_fields` to show specific fields
+- **Nested support:** Access nested fields with dot notation (`"main_address.internal_id"`)
+- **List support:** Show fields in all list items (`"addresses.internal_id"`)
+- **Smart defaults:** Non-kept fields use model defaults, kept fields retain initial values
+- **Admin interfaces:** Perfect for admin panels or debugging where you need to see system fields
+
+See `examples/complex_example.py` for a comprehensive demonstration of SkipJsonSchema field handling.
+
 ## Refreshing & Resetting
 
 Forms support dynamic refresh and reset functionality:
@@ -1007,6 +1084,7 @@ form_renderer = PydanticForm(
 | `disabled_fields` | `Optional[List[str]]` | `None` | List of specific field names to disable |
 | `label_colors` | `Optional[Dict[str, str]]` | `None` | Mapping of field names to CSS colors or Tailwind classes |
 | `exclude_fields` | `Optional[List[str]]` | `None` | List of field names to exclude from rendering (auto-injected on submission) |
+| `keep_skip_json_fields` | `Optional[List[str]]` | `None` | List of SkipJsonSchema field paths to selectively show (supports dot notation for nested fields) |
 | `spacing` | `SpacingValue` | `"normal"` | Spacing theme: `"normal"`, `"compact"`, or `SpacingTheme` enum |
 | `metrics_dict` | `Optional[Dict[str, Dict]]` | `None` | Field metrics for highlighting and tooltips |
 
@@ -1025,7 +1103,7 @@ form_renderer = PydanticForm(
 | Method | Purpose |
 |--------|---------|
 | `render_inputs()` | Generate the HTML form inputs (without `<form>` wrapper) |
-| `with_initial_values(initial_values)` | Create a new form instance with same configuration but different initial values |
+| `with_initial_values(initial_values, metrics_dict=None)` | Create a new form instance with same configuration but different initial values |
 | `refresh_button(text=None, **kwargs)` | Create a refresh button component |
 | `reset_button(text=None, **kwargs)` | Create a reset button component |
 | `register_routes(app)` | Register HTMX endpoints for list manipulation |

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/README.md

@@ -455,6 +455,83 @@ form_renderer = PydanticForm(
 
 This automatic default injection means you can safely exclude fields that shouldn't be user-editable while maintaining data integrity.
 
+### SkipJsonSchema Fields
+
+`fh-pydantic-form` provides advanced handling for `SkipJsonSchema` fields with selective visibility control. By default, fields marked with `SkipJsonSchema` are hidden from forms, but you can selectively show specific ones using the `keep_skip_json_fields` parameter.
+
+```python
+from pydantic.json_schema import SkipJsonSchema
+
+class DocumentModel(BaseModel):
+    title: str
+    content: str
+    
+    # Hidden by default - system fields
+    document_id: SkipJsonSchema[str] = Field(
+        default_factory=lambda: f"doc_{uuid4().hex[:12]}",
+        description="Internal document ID"
+    )
+    created_at: SkipJsonSchema[datetime.datetime] = Field(
+        default_factory=datetime.datetime.now,
+        description="Creation timestamp"
+    )
+    version: SkipJsonSchema[int] = Field(
+        default=1, 
+        description="Document version"
+    )
+
+# Normal form - all SkipJsonSchema fields hidden
+form_normal = PydanticForm("doc_form", DocumentModel)
+
+# Admin form - selectively show some SkipJsonSchema fields
+form_admin = PydanticForm(
+    "admin_form", 
+    DocumentModel,
+    keep_skip_json_fields=[
+        "document_id",  # Show document ID
+        "version",      # Show version number
+        # created_at remains hidden
+    ]
+)
+```
+
+#### Nested SkipJsonSchema Fields
+
+The feature supports dot notation for nested objects and list items:
+
+```python
+class Address(BaseModel):
+    street: str
+    city: str
+    # Hidden system field
+    internal_id: SkipJsonSchema[str] = Field(default_factory=lambda: f"addr_{uuid4().hex[:8]}")
+
+class UserModel(BaseModel):
+    name: str
+    main_address: Address
+    other_addresses: List[Address]
+
+# Show specific nested SkipJsonSchema fields
+form = PydanticForm(
+    "user_form",
+    UserModel,
+    keep_skip_json_fields=[
+        "main_address.internal_id",        # Show main address ID
+        "other_addresses.internal_id",     # Show all address IDs in the list
+    ]
+)
+```
+
+**Key Features:**
+- **Hidden by default:** SkipJsonSchema fields are automatically excluded from forms
+- **Selective visibility:** Use `keep_skip_json_fields` to show specific fields
+- **Nested support:** Access nested fields with dot notation (`"main_address.internal_id"`)
+- **List support:** Show fields in all list items (`"addresses.internal_id"`)
+- **Smart defaults:** Non-kept fields use model defaults, kept fields retain initial values
+- **Admin interfaces:** Perfect for admin panels or debugging where you need to see system fields
+
+See `examples/complex_example.py` for a comprehensive demonstration of SkipJsonSchema field handling.
+
 ## Refreshing & Resetting
 
 Forms support dynamic refresh and reset functionality:
@@ -982,6 +1059,7 @@ form_renderer = PydanticForm(
 | `disabled_fields` | `Optional[List[str]]` | `None` | List of specific field names to disable |
 | `label_colors` | `Optional[Dict[str, str]]` | `None` | Mapping of field names to CSS colors or Tailwind classes |
 | `exclude_fields` | `Optional[List[str]]` | `None` | List of field names to exclude from rendering (auto-injected on submission) |
+| `keep_skip_json_fields` | `Optional[List[str]]` | `None` | List of SkipJsonSchema field paths to selectively show (supports dot notation for nested fields) |
 | `spacing` | `SpacingValue` | `"normal"` | Spacing theme: `"normal"`, `"compact"`, or `SpacingTheme` enum |
 | `metrics_dict` | `Optional[Dict[str, Dict]]` | `None` | Field metrics for highlighting and tooltips |
 
@@ -1000,7 +1078,7 @@ form_renderer = PydanticForm(
 | Method | Purpose |
 |--------|---------|
 | `render_inputs()` | Generate the HTML form inputs (without `<form>` wrapper) |
-| `with_initial_values(initial_values)` | Create a new form instance with same configuration but different initial values |
+| `with_initial_values(initial_values, metrics_dict=None)` | Create a new form instance with same configuration but different initial values |
 | `refresh_button(text=None, **kwargs)` | Create a refresh button component |
 | `reset_button(text=None, **kwargs)` | Create a reset button component |
 | `register_routes(app)` | Register HTMX endpoints for list manipulation |

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/RELEASE_NOTES.md

@@ -1,5 +1,50 @@
 # Release Notes
 
+## Version 0.3.7 (2025-09-19)
+
+### 🎉 New Features
+
+#### SkipJsonSchema Field Support with Selective Override
+- **NEW**: Added comprehensive support for fields marked with `SkipJsonSchema` annotation
+- **NEW**: `keep_skip_json_fields` parameter allows selective inclusion of specific SkipJsonSchema fields
+  - Supports dot-notation paths for nested fields (e.g., `"addresses.internal_id"`)
+  - Enables fine-grained control over which internal fields are exposed in forms
+  - Works with complex nested structures and list fields
+- **ENHANCED**: SkipJsonSchema fields are automatically excluded from form rendering by default
+- **IMPROVED**: Better field introspection for complex type scenarios including optional skip fields
+
+### 🔧 Bug Fixes & Improvements
+
+#### Default Values Handling
+- **FIXED**: Default values for simple fields now work correctly without initial values
+- **IMPROVED**: Better handling of field defaults when no initial values are provided
+- **ENHANCED**: More robust form rendering for fields with default values
+
+#### Documentation & Examples
+- **UPDATED**: README.md with SkipJsonSchema handling documentation
+- **ENHANCED**: Complex example updated to demonstrate SkipJsonSchema usage patterns
+- **IMPROVED**: Better code documentation and examples
+
+### 🧪 Testing
+- **NEW**: Comprehensive test coverage for SkipJsonSchema field handling
+- **NEW**: Tests for default values behavior without initial values
+- **IMPROVED**: Enhanced test coverage for edge cases and type introspection
+
+### 📊 Statistics
+- **7 commits** since v0.3.6
+- Focus on optional field handling and default value improvements
+- Enhanced SkipJsonSchema support with comprehensive testing
+
+**Key Highlights:**
+This release significantly improves handling of optional fields, particularly those marked with `SkipJsonSchema`, and fixes important issues with default value handling when no initial values are provided.
+
+---
+
+## Version 0.3.6 (2025-07-21)
+
+- **NEW**: can now pass new metrics_dict to `.with_initial_values()` helper method.
+
+---
 ## Version 0.3.5 (2025-07-17)
 
 - **NEW**: Added support for `decimal.Decimal` fields with dedicated field renderer

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fh-pydantic-form"
-version = "0.3.5"
+version = "0.3.7"
 description = "a library to turn any pydantic BaseModel object into a fasthtml/monsterui input form"
 readme = "README.md"
 requires-python = ">=3.10"

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/src/fh_pydantic_form/field_renderers.py

@@ -14,7 +14,7 @@ from typing import (
 import fasthtml.common as fh
 import monsterui.all as mui
 from fastcore.xml import FT
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 from pydantic.fields import FieldInfo
 
 from fh_pydantic_form.color_utils import (
@@ -23,6 +23,7 @@ from fh_pydantic_form.color_utils import (
     robust_color_to_rgba,
 )
 from fh_pydantic_form.constants import _UNSET
+from fh_pydantic_form.defaults import default_dict_for_model, default_for_annotation
 from fh_pydantic_form.registry import FieldRendererRegistry
 from fh_pydantic_form.type_helpers import (
     DecorationScope,
@@ -30,7 +31,9 @@ from fh_pydantic_form.type_helpers import (
     MetricsDict,
     _get_underlying_type_if_optional,
     _is_optional_type,
+    _is_skip_json_schema_field,
     get_default,
+    normalize_path_segments,
 )
 from fh_pydantic_form.ui_style import (
     SpacingTheme,
@@ -379,6 +382,7 @@ class BaseFieldRenderer(MetricsRendererMixin):
         metric_entry: Optional[MetricEntry] = None,
         metrics_dict: Optional[MetricsDict] = None,
         refresh_endpoint_override: Optional[str] = None,
+        keep_skip_json_pathset: Optional[set[str]] = None,
         **kwargs,  # Accept additional kwargs for extensibility
     ):
         """
@@ -402,6 +406,14 @@ class BaseFieldRenderer(MetricsRendererMixin):
         self.field_name = f"{prefix}{field_name}" if prefix else field_name
         self.original_field_name = field_name
         self.field_info = field_info
+        # Normalize PydanticUndefined → None so it never renders as text
+        try:
+            from pydantic_core import PydanticUndefined
+
+            if value is PydanticUndefined:
+                value = None
+        except Exception:
+            pass
         self.value = value
         self.prefix = prefix
         self.field_path: List[str] = field_path or []
@@ -412,6 +424,7 @@ class BaseFieldRenderer(MetricsRendererMixin):
         self.spacing = _normalize_spacing(spacing)
         self.metrics_dict = metrics_dict
         self._refresh_endpoint_override = refresh_endpoint_override
+        self._keep_skip_json_pathset = keep_skip_json_pathset or set()
 
         # Initialize metric entry attribute
         self.metric_entry: Optional[MetricEntry] = None
@@ -447,6 +460,15 @@ class BaseFieldRenderer(MetricsRendererMixin):
                 parts.append(segment)
         return ".".join(parts)
 
+    def _normalized_dot_path(self, path_segments: List[str]) -> str:
+        """Normalize path segments by dropping indices and joining with dots."""
+        return normalize_path_segments(path_segments)
+
+    def _is_kept_skip_field(self, full_path: List[str]) -> bool:
+        """Return True if a SkipJsonSchema field should be kept based on keep list."""
+        normalized = self._normalized_dot_path(full_path)
+        return bool(normalized) and normalized in self._keep_skip_json_pathset
+
     def _is_inline_color(self, color: str) -> bool:
         """
         Determine if a color should be applied as an inline style or CSS class.
@@ -1249,18 +1271,26 @@ class BaseModelFieldRenderer(BaseFieldRenderer):
 
                 # Only use defaults if field wasn't provided
                 if not field_was_provided:
-                    if nested_field_info.default is not None:
-                        nested_field_value = nested_field_info.default
-                    elif (
-                        getattr(nested_field_info, "default_factory", None) is not None
-                    ):
-                        try:
-                            nested_field_value = nested_field_info.default_factory()
-                        except Exception as e:
-                            logger.warning(
-                                f"Default factory failed for {nested_field_name}: {e}"
-                            )
-                            nested_field_value = None
+                    dv = get_default(nested_field_info)  # _UNSET if truly unset
+                    if dv is not _UNSET:
+                        nested_field_value = dv
+                    else:
+                        ann = nested_field_info.annotation
+                        base_ann = get_origin(ann) or ann
+                        if isinstance(base_ann, type) and issubclass(
+                            base_ann, BaseModel
+                        ):
+                            nested_field_value = default_dict_for_model(base_ann)
+                        else:
+                            nested_field_value = default_for_annotation(ann)
+
+                # Skip SkipJsonSchema fields unless explicitly kept
+                if _is_skip_json_schema_field(
+                    nested_field_info
+                ) and not self._is_kept_skip_field(
+                    self.field_path + [nested_field_name]
+                ):
+                    continue
 
                 # Get renderer for this nested field
                 registry = FieldRendererRegistry()  # Get singleton instance
@@ -1290,6 +1320,7 @@ class BaseModelFieldRenderer(BaseFieldRenderer):
                     metric_entry=None,  # Let auto-lookup handle it
                     metrics_dict=self.metrics_dict,  # Pass down the metrics dict
                     refresh_endpoint_override=self._refresh_endpoint_override,  # Propagate refresh override
+                    keep_skip_json_pathset=self._keep_skip_json_pathset,  # Propagate keep paths
                 )
 
                 nested_inputs.append(renderer.render())
@@ -1843,6 +1874,7 @@ class ListFieldRenderer(BaseFieldRenderer):
                         metric_entry=None,  # Let auto-lookup handle it
                         metrics_dict=self.metrics_dict,  # Pass down the metrics dict
                         refresh_endpoint_override=self._refresh_endpoint_override,  # Propagate refresh override
+                        keep_skip_json_pathset=self._keep_skip_json_pathset,  # Propagate keep paths
                     )
                     # Add the rendered input to content elements
                     item_content_elements.append(item_renderer.render_input())
@@ -1866,18 +1898,28 @@ class ListFieldRenderer(BaseFieldRenderer):
 
                             # Use defaults only if field not provided
                             if not field_was_provided:
-                                if nested_field_info.default is not None:
-                                    nested_field_value = nested_field_info.default
-                                elif (
-                                    getattr(nested_field_info, "default_factory", None)
-                                    is not None
-                                ):
-                                    try:
-                                        nested_field_value = (
-                                            nested_field_info.default_factory()
+                                dv = get_default(nested_field_info)
+                                if dv is not _UNSET:
+                                    nested_field_value = dv
+                                else:
+                                    ann = nested_field_info.annotation
+                                    base_ann = get_origin(ann) or ann
+                                    if isinstance(base_ann, type) and issubclass(
+                                        base_ann, BaseModel
+                                    ):
+                                        nested_field_value = default_dict_for_model(
+                                            base_ann
                                         )
-                                    except Exception:
-                                        continue  # Skip fields with problematic defaults
+                                    else:
+                                        nested_field_value = default_for_annotation(ann)
+
+                            # Skip SkipJsonSchema fields unless explicitly kept
+                            if _is_skip_json_schema_field(
+                                nested_field_info
+                            ) and not self._is_kept_skip_field(
+                                self.field_path + [nested_field_name]
+                            ):
+                                continue
 
                             # Get renderer and render field with error handling
                             renderer_cls = FieldRendererRegistry().get_renderer(
@@ -1902,6 +1944,7 @@ class ListFieldRenderer(BaseFieldRenderer):
                                 metric_entry=None,  # Let auto-lookup handle it
                                 metrics_dict=self.metrics_dict,  # Pass down the metrics dict
                                 refresh_endpoint_override=self._refresh_endpoint_override,  # Propagate refresh override
+                                keep_skip_json_pathset=self._keep_skip_json_pathset,  # Propagate keep paths
                             )
 
                             # Add rendered field to valid fields

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/src/fh_pydantic_form/form_parser.py

@@ -54,6 +54,8 @@ def _parse_non_list_fields(
     list_field_defs: Dict[str, Dict[str, Any]],
     base_prefix: str = "",
     exclude_fields: Optional[List[str]] = None,
+    keep_skip_json_pathset: Optional[set[str]] = None,
+    current_field_path: Optional[List[str]] = None,
 ) -> Dict[str, Any]:
     """
     Parses non-list fields from form data based on the model definition.
@@ -64,12 +66,30 @@ def _parse_non_list_fields(
         list_field_defs: Dictionary of list field definitions (to skip)
         base_prefix: Prefix to use when looking up field names in form_data
         exclude_fields: Optional list of field names to exclude from parsing
+        keep_skip_json_pathset: Optional set of normalized paths for SkipJsonSchema fields to keep
 
     Returns:
         Dictionary with parsed non-list fields
     """
     result: Dict[str, Any] = {}
     exclude_fields = exclude_fields or []
+    keep_skip_json_pathset = keep_skip_json_pathset or set()
+
+    # Helper function to check if a SkipJsonSchema field should be kept
+    def _should_keep_skip_field(path_segments: List[str]) -> bool:
+        from fh_pydantic_form.type_helpers import normalize_path_segments
+
+        normalized = normalize_path_segments(path_segments)
+        return bool(normalized) and normalized in keep_skip_json_pathset
+
+    # Calculate the current path context for fields at this level
+    # For top-level parsing, this will be empty
+    # For nested parsing, this will contain the nested path segments
+    current_path_segments: List[str] = []
+    if current_field_path is not None:
+        # Use explicitly passed field path
+        current_path_segments = current_field_path
+    # For top-level parsing (base_prefix is just form name), current_path_segments remains empty
 
     for field_name, field_info in model_class.model_fields.items():
         if field_name in list_field_defs:
@@ -79,9 +99,11 @@ def _parse_non_list_fields(
         if field_name in exclude_fields:
             continue
 
-        # Skip SkipJsonSchema fields - they should not be parsed from form data
+        # Skip SkipJsonSchema fields unless they're explicitly kept
         if _is_skip_json_schema_field(field_info):
-            continue
+            field_path_segments = current_path_segments + [field_name]
+            if not _should_keep_skip_field(field_path_segments):
+                continue
 
         # Create full key with prefix
         full_key = f"{base_prefix}{field_name}"
@@ -128,7 +150,8 @@ def _parse_non_list_fields(
             # Get the nested model class (unwrap Optional if needed)
             nested_model_class = _get_underlying_type_if_optional(annotation)
 
-            # Parse the nested model - pass the base_prefix and exclude_fields
+            # Parse the nested model - pass the base_prefix, exclude_fields, and keep paths
+            nested_field_path = current_path_segments + [field_name]
             nested_value = _parse_nested_model_field(
                 field_name,
                 form_data,
@@ -136,6 +159,8 @@ def _parse_non_list_fields(
                 field_info,
                 base_prefix,
                 exclude_fields,
+                keep_skip_json_pathset,
+                nested_field_path,
             )
 
             # Only assign if we got a non-None value or the field is not optional
@@ -276,6 +301,8 @@ def _parse_nested_model_field(
     field_info,
     parent_prefix: str = "",
     exclude_fields: Optional[List[str]] = None,
+    keep_skip_json_pathset: Optional[set[str]] = None,
+    current_field_path: Optional[List[str]] = None,
 ) -> Optional[Dict[str, Any]]:
     """
     Parse a nested Pydantic model field from form data.
@@ -286,6 +313,8 @@ def _parse_nested_model_field(
         nested_model_class: The nested model class
         field_info: The field info from the parent model
         parent_prefix: Prefix from parent form/model to use when constructing keys
+        exclude_fields: Optional list of field names to exclude from parsing
+        keep_skip_json_pathset: Optional set of normalized paths for SkipJsonSchema fields to keep
 
     Returns:
         Dictionary with nested model structure or None/default if no data found
@@ -302,6 +331,16 @@ def _parse_nested_model_field(
             break
 
     if found_any_subfield:
+        # Helper function to check if a SkipJsonSchema field should be kept
+        def _should_keep_skip_field_nested(path_segments: List[str]) -> bool:
+            from fh_pydantic_form.type_helpers import normalize_path_segments
+
+            normalized = normalize_path_segments(path_segments)
+            return bool(normalized) and normalized in (keep_skip_json_pathset or set())
+
+        # Use the passed field path for calculating nested paths
+        nested_path_segments: List[str] = current_field_path or []
+
         # ------------------------------------------------------------------
         # 1. Process each **non-list** field in the nested model
         # ------------------------------------------------------------------
@@ -309,12 +348,14 @@ def _parse_nested_model_field(
             sub_key = f"{current_prefix}{sub_field_name}"
             annotation = getattr(sub_field_info, "annotation", None)
 
-            # Skip SkipJsonSchema fields - they should not be parsed from form data
+            # Skip SkipJsonSchema fields unless they're explicitly kept
             if _is_skip_json_schema_field(sub_field_info):
-                logger.debug(
-                    f"Skipping SkipJsonSchema field in nested model during parsing: {sub_field_name}"
-                )
-                continue
+                sub_field_path_segments = nested_path_segments + [sub_field_name]
+                if not _should_keep_skip_field_nested(sub_field_path_segments):
+                    logger.debug(
+                        f"Skipping SkipJsonSchema field in nested model during parsing: {sub_field_name}"
+                    )
+                    continue
 
             # Handle based on field type, with Optional unwrapping
             is_optional = _is_optional_type(annotation)
@@ -326,9 +367,17 @@ def _parse_nested_model_field(
 
             # Handle nested model fields (including Optional[NestedModel])
             elif isinstance(base_type, type) and hasattr(base_type, "model_fields"):
-                # Pass the current_prefix to the recursive call
+                # Pass the current_prefix and keep paths to the recursive call
+                sub_field_path = nested_path_segments + [sub_field_name]
                 sub_value = _parse_nested_model_field(
-                    sub_field_name, form_data, base_type, sub_field_info, current_prefix
+                    sub_field_name,
+                    form_data,
+                    base_type,
+                    sub_field_info,
+                    current_prefix,
+                    exclude_fields,
+                    keep_skip_json_pathset,
+                    sub_field_path,
                 )
                 if sub_value is not None:
                     nested_data[sub_field_name] = sub_value
@@ -358,6 +407,7 @@ def _parse_nested_model_field(
                 nested_list_defs,
                 current_prefix,  # ← prefix for this nested model
                 exclude_fields,  # Pass through exclude_fields
+                keep_skip_json_pathset,
             )
             # Merge without clobbering keys already set in step 1
             for lf_name, lf_val in list_results.items():
@@ -438,6 +488,7 @@ def _parse_list_fields(
     list_field_defs: Dict[str, Dict[str, Any]],
     base_prefix: str = "",
     exclude_fields: Optional[List[str]] = None,
+    keep_skip_json_pathset: Optional[set[str]] = None,
 ) -> Dict[str, Optional[List[Any]]]:
     """
     Parse list fields from form data by analyzing keys and reconstructing ordered lists.
@@ -447,6 +498,7 @@ def _parse_list_fields(
         list_field_defs: Dictionary of list field definitions
         base_prefix: Prefix to use when looking up field names in form_data
         exclude_fields: Optional list of field names to exclude from parsing
+        keep_skip_json_pathset: Optional set of normalized paths for SkipJsonSchema fields to keep
 
     Returns:
         Dictionary with parsed list fields
@@ -504,7 +556,15 @@ def _parse_list_fields(
             # ------------------------------------------------------------------
             if field_def["is_model_type"]:
                 item_prefix = f"{base_prefix}{field_name}_{idx_str}_"
-                parsed_item = _parse_model_list_item(form_data, item_type, item_prefix)
+                # For list items, the field path is the list field name (without index)
+                item_field_path = [field_name]
+                parsed_item = _parse_model_list_item(
+                    form_data,
+                    item_type,
+                    item_prefix,
+                    keep_skip_json_pathset,
+                    item_field_path,
+                )
                 items.append(parsed_item)
                 continue
 
@@ -558,6 +618,8 @@ def _parse_model_list_item(
     form_data: Dict[str, Any],
     item_type,
     item_prefix: str,
+    keep_skip_json_pathset: Optional[set[str]] = None,
+    current_field_path: Optional[List[str]] = None,
 ) -> Dict[str, Any]:
     """
     Fully parse a single BaseModel list item – including its own nested lists.
@@ -568,6 +630,7 @@ def _parse_model_list_item(
         form_data: Dictionary containing form field data
         item_type: The BaseModel class for this list item
         item_prefix: Prefix for this specific list item (e.g., "main_form_compact_other_addresses_0_")
+        keep_skip_json_pathset: Optional set of normalized paths for SkipJsonSchema fields to keep
 
     Returns:
         Dictionary with fully parsed item data including nested lists
@@ -579,11 +642,18 @@ def _parse_model_list_item(
         item_type,
         nested_list_defs,
         base_prefix=item_prefix,
+        exclude_fields=[],
+        keep_skip_json_pathset=keep_skip_json_pathset,
+        current_field_path=current_field_path,
     )
     # 2. Parse inner lists
     result.update(
         _parse_list_fields(
-            form_data, nested_list_defs, base_prefix=item_prefix, exclude_fields=[]
+            form_data,
+            nested_list_defs,
+            base_prefix=item_prefix,
+            exclude_fields=[],
+            keep_skip_json_pathset=keep_skip_json_pathset,
         )
     )
     return result

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/src/fh_pydantic_form/form_renderer.py

@@ -34,6 +34,7 @@ from fh_pydantic_form.registry import FieldRendererRegistry
 from fh_pydantic_form.type_helpers import (
     _is_skip_json_schema_field,
     get_default,
+    normalize_path_segments,
 )
 from fh_pydantic_form.ui_style import (
     SpacingTheme,
@@ -48,6 +49,21 @@ logger = logging.getLogger(__name__)
 ModelType = TypeVar("ModelType", bound=BaseModel)
 
 
+def _compile_keep_paths(paths: Optional[List[str]]) -> set[str]:
+    """Normalize and compile keep paths for fast membership tests."""
+    if not paths:
+        return set()
+
+    compiled: set[str] = set()
+    for raw_path in paths:
+        if not raw_path:
+            continue
+        normalized = raw_path.strip()
+        if normalized:
+            compiled.add(normalized)
+    return compiled
+
+
 def list_manipulation_js():
     return fh.Script("""  
 function moveItem(buttonElement, direction) {
@@ -281,6 +297,7 @@ class PydanticForm(Generic[ModelType]):
         disabled_fields: Optional[List[str]] = None,
         label_colors: Optional[Dict[str, str]] = None,
         exclude_fields: Optional[List[str]] = None,
+        keep_skip_json_fields: Optional[List[str]] = None,
         spacing: SpacingValue = SpacingTheme.NORMAL,
         metrics_dict: Optional[Dict[str, Any]] = None,
     ):
@@ -298,6 +315,7 @@ class PydanticForm(Generic[ModelType]):
             disabled_fields: Optional list of top-level field names to disable specifically
             label_colors: Optional dictionary mapping field names to label colors (CSS color values)
             exclude_fields: Optional list of top-level field names to exclude from the form
+            keep_skip_json_fields: Optional list of dot-paths for SkipJsonSchema fields to force-keep
             spacing: Spacing theme to use for form layout ("normal", "compact", or SpacingTheme enum)
             metrics_dict: Optional metrics dictionary for field-level visual feedback
         """
@@ -342,6 +360,8 @@ class PydanticForm(Generic[ModelType]):
         self.exclude_fields = exclude_fields or []  # Store excluded fields list
         self.spacing = _normalize_spacing(spacing)  # Store normalized spacing
         self.metrics_dict = metrics_dict or {}  # Store metrics dictionary
+        self.keep_skip_json_fields = keep_skip_json_fields or []
+        self._keep_skip_json_pathset = _compile_keep_paths(self.keep_skip_json_fields)
 
         # Register custom renderers with the global registry if provided
         if custom_renderers:
@@ -349,6 +369,13 @@ class PydanticForm(Generic[ModelType]):
             for field_type, renderer_cls in custom_renderers:
                 registry.register_type_renderer(field_type, renderer_cls)
 
+    @property
+    def form_name(self) -> str:
+        """
+        LLMs like to hallucinate this property, so might as well make it real.
+        """
+        return self.name
+
     def _compact_wrapper(self, inner: FT) -> FT:
         """
         Wrap inner markup in a wrapper div.
@@ -356,6 +383,15 @@ class PydanticForm(Generic[ModelType]):
         wrapper_cls = "fhpf-wrapper w-full flex-1"
         return fh.Div(inner, cls=wrapper_cls)
 
+    def _normalized_dot_path(self, path_segments: List[str]) -> str:
+        """Normalize path segments by dropping indices and joining with dots."""
+        return normalize_path_segments(path_segments)
+
+    def _is_kept_skip_field(self, full_path: List[str]) -> bool:
+        """Return True if a SkipJsonSchema field should be kept based on keep list."""
+        normalized = self._normalized_dot_path(full_path)
+        return bool(normalized) and normalized in self._keep_skip_json_pathset
+
     def reset_state(self) -> None:
         """
         Restore the live state of the form to its immutable baseline.
@@ -364,7 +400,9 @@ class PydanticForm(Generic[ModelType]):
         self.values_dict = self.initial_values_dict.copy()
 
     def with_initial_values(
-        self, initial_values: Optional[Union[ModelType, Dict[str, Any]]] = None
+        self,
+        initial_values: Optional[Union[ModelType, Dict[str, Any]]] = None,
+        metrics_dict: Optional[Dict[str, Any]] = None,
     ) -> "PydanticForm":
         """
         Create a new PydanticForm instance with the same configuration but different initial values.
@@ -376,6 +414,7 @@ class PydanticForm(Generic[ModelType]):
         Args:
             initial_values: New initial values as BaseModel instance or dict.
                            Same format as the constructor accepts.
+            metrics_dict: Optional metrics dictionary for field-level visual feedback
 
         Returns:
             A new PydanticForm instance with identical configuration but updated initial values
@@ -390,8 +429,11 @@ class PydanticForm(Generic[ModelType]):
             disabled_fields=self.disabled_fields,
             label_colors=self.label_colors,
             exclude_fields=self.exclude_fields,
+            keep_skip_json_fields=self.keep_skip_json_fields,
             spacing=self.spacing,
-            metrics_dict=self.metrics_dict,
+            metrics_dict=metrics_dict
+            if metrics_dict is not None
+            else self.metrics_dict,
         )
 
         return clone
@@ -411,8 +453,10 @@ class PydanticForm(Generic[ModelType]):
             if field_name in self.exclude_fields:
                 continue
 
-            # Skip SkipJsonSchema fields (they should not be rendered in the form)
-            if _is_skip_json_schema_field(field_info):
+            # Skip SkipJsonSchema fields unless explicitly kept
+            if _is_skip_json_schema_field(field_info) and not self._is_kept_skip_field(
+                [field_name]
+            ):
                 continue
 
             # Only use what was explicitly provided in initial values
@@ -428,24 +472,14 @@ class PydanticForm(Generic[ModelType]):
 
             # Only use defaults if field was not provided at all
             if not field_was_provided:
-                # Field not provided - use model defaults
-                if field_info.default is not None:
-                    initial_value = field_info.default
-                elif getattr(field_info, "default_factory", None) is not None:
-                    try:
-                        default_factory = field_info.default_factory
-                        if callable(default_factory):
-                            initial_value = default_factory()  # type: ignore[call-arg]
-                        else:
-                            initial_value = None
-                            logger.warning(
-                                f"  - default_factory for '{field_name}' is not callable"
-                            )
-                    except Exception as e:
-                        initial_value = None
-                        logger.warning(
-                            f"  - Error in default_factory for '{field_name}': {e}"
-                        )
+                # Field not provided - use model defaults in order of priority
+                # 1. Try explicit field default
+                default_val = get_default(field_info)
+                if default_val is not _UNSET:
+                    initial_value = default_val
+                else:
+                    # 2. Fall back to smart defaults for the type
+                    initial_value = default_for_annotation(field_info.annotation)
             # If field was provided (even as None), respect that value
 
             # Get renderer from global registry
@@ -476,6 +510,7 @@ class PydanticForm(Generic[ModelType]):
                 field_path=[field_name],  # Set top-level field path
                 form_name=self.name,  # Pass form name
                 metrics_dict=self.metrics_dict,  # Pass the metrics dict
+                keep_skip_json_pathset=self._keep_skip_json_pathset,
             )
 
             rendered_field = renderer.render()
@@ -642,19 +677,25 @@ class PydanticForm(Generic[ModelType]):
             if field_name not in self.exclude_fields
         }
 
-        # Parse non-list fields first - pass the base_prefix and exclude_fields
+        # Parse non-list fields first - pass the base_prefix, exclude_fields, and keep paths
         result = _parse_non_list_fields(
             form_dict,
             self.model_class,
             list_field_defs,
             self.base_prefix,
             self.exclude_fields,
+            self._keep_skip_json_pathset,
+            None,  # Top-level parsing, no field path
         )
 
-        # Parse list fields based on keys present in form_dict - pass the base_prefix
+        # Parse list fields based on keys present in form_dict - pass the base_prefix and keep paths
         # Use filtered list field definitions to skip excluded list fields
         list_results = _parse_list_fields(
-            form_dict, filtered_list_field_defs, self.base_prefix
+            form_dict,
+            filtered_list_field_defs,
+            self.base_prefix,
+            self.exclude_fields,
+            self._keep_skip_json_pathset,
         )
 
         # Merge list results into the main result
@@ -683,12 +724,33 @@ class PydanticForm(Generic[ModelType]):
         """
         # Process ALL model fields, not just excluded ones
         for field_name, field_info in self.model_class.model_fields.items():
-            # Skip if already present in parsed data
-            if field_name in data:
-                continue
+            # Special handling for SkipJsonSchema fields
+            if _is_skip_json_schema_field(field_info):
+                # If keep_skip_json_fields was specified and this field is not kept, always use defaults
+                if self.keep_skip_json_fields and not self._is_kept_skip_field(
+                    [field_name]
+                ):
+                    # Remove any existing value and inject default
+                    if field_name in data:
+                        del data[field_name]
+                    # Fall through to default injection logic below
+                elif field_name in data:
+                    # This is either a kept SkipJsonSchema field or no keep list was specified, keep it
+                    continue
+                # If it's a kept field but not in data, fall through to default injection
+            else:
+                # Skip if already present in parsed data (normal fields)
+                if field_name in data:
+                    continue
 
             # First priority: check if initial_values_dict has this field
-            if field_name in self.initial_values_dict:
+            # Use initial values for non-SkipJsonSchema fields, or SkipJsonSchema fields that are kept,
+            # or SkipJsonSchema fields when no keep_skip_json_fields list was specified
+            if field_name in self.initial_values_dict and (
+                not _is_skip_json_schema_field(field_info)
+                or not self.keep_skip_json_fields
+                or self._is_kept_skip_field([field_name])
+            ):
                 initial_val = self.initial_values_dict[field_name]
                 # If the initial value is a BaseModel, convert to dict for consistency
                 if hasattr(initial_val, "model_dump"):
@@ -796,6 +858,7 @@ class PydanticForm(Generic[ModelType]):
                 field_path=segments,  # Pass the full path segments
                 form_name=self.name,  # Pass the explicit form name
                 metrics_dict=self.metrics_dict,  # Pass the metrics dict
+                keep_skip_json_pathset=self._keep_skip_json_pathset,
             )
 
             # Generate a unique placeholder index

{fh_pydantic_form-0.3.5 → fh_pydantic_form-0.3.7}/src/fh_pydantic_form/type_helpers.py

@@ -5,6 +5,7 @@ __all__ = [
     "_is_literal_type",
     "_is_enum_type",
     "_is_skip_json_schema_field",
+    "normalize_path_segments",
     "MetricEntry",
     "MetricsDict",
     "DecorationScope",
@@ -18,6 +19,7 @@ from typing import (
     Annotated,
     Any,
     Dict,
+    List,
     Literal,
     TypedDict,
     Union,
@@ -38,6 +40,18 @@ class DecorationScope(str, Enum):
     BOTH = "both"
 
 
+def normalize_path_segments(path_segments: List[str]) -> str:
+    """Collapse path segments into a dot path ignoring list indices and placeholders."""
+    normalized: List[str] = []
+    for segment in path_segments:
+        # Coerce to string to avoid surprises from enums or numbers
+        seg_str = str(segment)
+        if seg_str.isdigit() or seg_str.startswith("new_"):
+            continue
+        normalized.append(seg_str)
+    return ".".join(normalized)
+
+
 def _is_skip_json_schema_field(annotation_or_field_info: Any) -> bool:
     """
     Check if a field annotation or field_info indicates it should be skipped in JSON schema.
@@ -101,8 +115,14 @@ def _is_skip_json_schema_field(annotation_or_field_info: Any) -> bool:
             ):
                 return True
 
-    # 3. Fallback – cheap but effective
-    return "SkipJsonSchema" in repr(annotation)
+    # 3. Fallback – cheap but effective, but be more specific to avoid false positives
+    # Only match if SkipJsonSchema appears as a standalone word (not part of a class name)
+    repr_str = repr(annotation)
+    # Look for patterns like "SkipJsonSchema[" or "SkipJsonSchema(" or "SkipJsonSchema]"
+    # but not "SomeClassNameSkipJsonSchema"
+    import re
+
+    return bool(re.search(r"\bSkipJsonSchema\b", repr_str))
 
 
 # Metrics types for field-level annotations