pydantic-forms 2.6.0__tar.gz → 2.7.0__tar.gz

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydantic-forms
-Version: 2.6.0
+Version: 2.7.0
 Summary: Pydantic-forms engine.
 Author: SURF
 Author-email: SURF <automation-beheer@surf.nl>
@@ -39,7 +39,7 @@ Requires-Dist: pydantic-i18n==0.4.5
 Requires-Dist: fastapi>=0.103.2 ; extra == 'fastapi'
 Requires-Dist: orjson>=3.10.7,<4.0.0 ; extra == 'orjson'
 Requires-Python: >=3.10, <3.15
-Project-URL: Documentation, https://github.com/workfloworchestrator/pydantic-forms/blob/main/README.md
+Project-URL: Documentation, https://workfloworchestrator.org/pydantic-forms/
 Project-URL: Homepage, https://github.com/workfloworchestrator/pydantic-forms
 Project-URL: Source, https://github.com/workfloworchestrator/pydantic-forms
 Provides-Extra: fastapi
@@ -61,8 +61,8 @@ Forms can also consist out of a wizard, so you can create complex form flows con
 consecutive forms. The forms and the validation logic are defined by
 using [Pydantic](https://pydantic-docs.helpmanual.io/) models.
 
-Documentation regarding the usage of Forms can be found
-[here](https://github.com/workfloworchestrator/orchestrator-core/blob/main/docs/architecture/application/forms-frontend.md)
+Documentation regarding the usage of Forms can be found at
+[workfloworchestrator.org/pydantic-forms](https://workfloworchestrator.org/pydantic-forms/).
 
 ### Installation (Development standalone)
 

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/README.md

@@ -13,8 +13,8 @@ Forms can also consist out of a wizard, so you can create complex form flows con
 consecutive forms. The forms and the validation logic are defined by
 using [Pydantic](https://pydantic-docs.helpmanual.io/) models.
 
-Documentation regarding the usage of Forms can be found
-[here](https://github.com/workfloworchestrator/orchestrator-core/blob/main/docs/architecture/application/forms-frontend.md)
+Documentation regarding the usage of Forms can be found at
+[workfloworchestrator.org/pydantic-forms](https://workfloworchestrator.org/pydantic-forms/).
 
 ### Installation (Development standalone)
 

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/core/asynchronous.py

@@ -18,11 +18,12 @@ import structlog
 from pydantic import ValidationError
 from pydantic_i18n import PydanticI18n
 
-from pydantic_forms.core.shared import FORMS, GenerateFormJsonSchema
+from pydantic_forms.core.shared import FORMS, GenerateFormJsonSchema, get_form_meta
 from pydantic_forms.core.translations import translations
 from pydantic_forms.exceptions import (
     FormException,
     FormNotCompleteError,
+    FormNotFoundError,
     FormOverflowError,
     FormValidationError,
 )
@@ -104,13 +105,13 @@ async def post_form(
     # Form is not completely filled raise next form
     raise FormNotCompleteError(
         generated_form.model_json_schema(schema_generator=GenerateFormJsonSchema),
-        meta=getattr(generated_form, "meta__", None),
+        meta=get_form_meta(generated_form),
     )
 
 
 def _get_form(key: str) -> StateInputFormGeneratorAsync:
     if not (func := FORMS.get(key)):
-        raise FormException(f"Form {key} does not exist.")
+        raise FormNotFoundError(f"Form {key} does not exist.")
 
     if not isasyncgenfunction(func):
         raise FormException(f"Form {key} is not an asyncgenerator function")

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/core/shared.py

@@ -11,13 +11,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from inspect import isasyncgenfunction, isgeneratorfunction
-from typing import Any, Callable, cast
+from typing import Any, Callable, ClassVar, cast
 
 import structlog
 from pydantic import BaseModel, ConfigDict, PydanticUndefinedAnnotation, version
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 from pydantic_core import core_schema
 
+from pydantic_forms.types import FormMeta
+from pydantic_forms.validators.components.buttons import merge_buttons_into_meta
+
 logger = structlog.get_logger(__name__)
 
 
@@ -65,6 +68,18 @@ class FormPage(BaseModel):
         validate_default=True,
     )
 
+    meta__: ClassVar[FormMeta | None] = None
+    """Data about the page itself, passed to the frontend alongside its JSON schema.
+
+    Set it on a subclass to tell the frontend something the schema cannot express, such as whether
+    another page follows (`hasNext`). It travels out as the `meta` key of the `FormNotCompleteError`
+    response, see `form_meta()`. Being a `ClassVar` it is not a form field, so it stays out of the
+    schema and the validated result.
+
+    Relabel or restyle the previous/next buttons with a `ButtonsConfig` field, or else with
+    `customButtons` here. The two can't be combined.
+    """
+
     def __init__(self, **data: Any):
         frozen_fields = {k: v for k, v in self.__class__.model_fields.items() if v.frozen}
 
@@ -76,6 +91,11 @@ class FormPage(BaseModel):
         mutable_data = {k: get_value(k, v) for k, v in data.items()}
         super().__init__(**mutable_data)
 
+    @classmethod
+    def form_meta(cls) -> FormMeta | None:
+        """Return `meta__` with the page's `ButtonsConfig` field added."""
+        return merge_buttons_into_meta(cls.__name__, cls.meta__, cls.model_fields)
+
     if PYDANTIC_VERSION in ("2.9", "2.10", "2.11"):
 
         @classmethod
@@ -83,6 +103,7 @@ class FormPage(BaseModel):
             # The default and requiredness of a field is not a property of a field
             # In the case of DisplayOnlyFieldTypes, we do kind of want that.
             # Using this method we set the right properties after the form is created
+            cls.form_meta()  # run now so a conflicting declaration fails on import, not when the page is first sent
             needs_rebuild = False
 
             for field in cls.model_fields.values():
@@ -115,6 +136,7 @@ class FormPage(BaseModel):
             # The default and requiredness of a field is not a property of a field
             # In the case of DisplayOnlyFieldTypes, we do kind of want that.
             # Using this method we set the right properties after the form is created
+            cls.form_meta()
             needs_rebuild = False
 
             for field in cls.model_fields.values():
@@ -142,3 +164,13 @@ def register_form(key: str, form: Callable) -> None:
 
 def list_forms() -> list[str]:
     return list(FORMS.keys())
+
+
+def get_form_meta(form: type[BaseModel]) -> Any:
+    """Return the meta to send to the frontend with `form`.
+
+    A generator may yield any pydantic model, not only a `FormPage`; such a model can still carry a `meta__`.
+    """
+    if issubclass(form, FormPage):
+        return form.form_meta()
+    return getattr(form, "meta__", None)

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/core/sync.py

@@ -18,9 +18,15 @@ import structlog
 from pydantic import ValidationError
 from pydantic_i18n import PydanticI18n
 
-from pydantic_forms.core.shared import FORMS, GenerateFormJsonSchema
+from pydantic_forms.core.shared import FORMS, GenerateFormJsonSchema, get_form_meta
 from pydantic_forms.core.translations import translations
-from pydantic_forms.exceptions import FormException, FormNotCompleteError, FormOverflowError, FormValidationError
+from pydantic_forms.exceptions import (
+    FormException,
+    FormNotCompleteError,
+    FormNotFoundError,
+    FormOverflowError,
+    FormValidationError,
+)
 from pydantic_forms.types import InputForm, State, StateInputFormGenerator
 
 logger = structlog.get_logger(__name__)
@@ -90,7 +96,7 @@ def post_form(
         # Form is not completely filled; raise next form
         raise FormNotCompleteError(
             generated_form.model_json_schema(schema_generator=GenerateFormJsonSchema),
-            meta=getattr(generated_form, "meta__", None),
+            meta=get_form_meta(generated_form),
         )
     except StopIteration as e:
         if user_inputs:
@@ -102,7 +108,7 @@ def post_form(
 
 def _get_form(key: str) -> StateInputFormGenerator:
     if not (func := FORMS.get(key)):
-        raise FormException(f"Form {key} does not exist.")
+        raise FormNotFoundError(f"Form {key} does not exist.")
 
     if not isgeneratorfunction(func):
         raise FormException(f"Form {key} is not a generator function")

pydantic_forms-2.7.0/pydantic_forms/exception_handlers/fastapi.py

@@ -0,0 +1,84 @@
+# Copyright 2019-2023 SURF.
+# 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.
+import os
+
+# TODO Decide how to expose this so pydantic-forms can be framework agnostic
+from http import HTTPStatus
+from typing import Any
+
+import structlog
+from fastapi.requests import Request
+from fastapi.responses import JSONResponse
+
+from pydantic_forms.exceptions import (
+    FormException,
+    FormNotCompleteError,
+    FormNotFoundError,
+    FormValidationError,
+    show_ex,
+)
+from pydantic_forms.utils.json import json_dumps, json_loads
+
+logger = structlog.get_logger(__name__)
+
+
+async def form_error_handler(request: Request, exc: FormException) -> JSONResponse:
+    """FastAPI exception handler that turns a FormException into a HTTP 4xx/5xx response with JSON body."""
+    match exc:
+        case FormValidationError():
+            status = HTTPStatus.BAD_REQUEST
+            base_content = _create_content(exc, status, "Form not valid")
+            detail_content = base_content | {
+                "validation_errors": json_loads(json_dumps(exc.errors)),
+            }
+            debug_content = _add_traceback(exc, detail_content)
+            return JSONResponse(debug_content, status_code=status)
+
+        case FormNotCompleteError():
+            status = HTTPStatus.NOT_EXTENDED
+            base_content = _create_content(exc, status, "Form not complete")
+            detail_content = base_content | {
+                "form": json_loads(json_dumps(exc.form)),
+                "meta": getattr(exc, "meta", None),
+            }
+            debug_content = _add_traceback(exc, detail_content)
+            return JSONResponse(debug_content, status_code=status)
+
+        case FormNotFoundError():
+            status = HTTPStatus.NOT_FOUND
+            base_content = _create_content(exc, status, "Form not found")
+            return JSONResponse(base_content, status_code=status)
+
+        case _:
+            status = HTTPStatus.INTERNAL_SERVER_ERROR
+            base_content = _create_content(exc, status, "Internal Server Error")
+            return JSONResponse(base_content, status_code=status)
+
+
+def _create_content(exc: FormException, status: HTTPStatus, title: str) -> dict[str, str | HTTPStatus]:
+    return {
+        "type": type(exc).__name__,
+        "detail": str(exc),
+        "title": title,
+        "status": status,
+    }
+
+
+def _add_traceback(exc: FormException, content: dict[str, Any]) -> dict[str, Any]:
+    LOG_LEVEL_PYDANTIC_FORMS = "DEBUG" if os.getenv("LOG_LEVEL_PYDANTIC_FORMS", "INFO").upper() == "DEBUG" else "INFO"
+    if LOG_LEVEL_PYDANTIC_FORMS == "DEBUG":
+        content_with_traceback = content | {"traceback": show_ex(exc)}
+        logger.debug("Form validation Response", result=content_with_traceback)
+        return content_with_traceback
+
+    return content

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/exceptions.py

@@ -37,6 +37,10 @@ class FormOverflowError(FormException):
     """Raised when more inputs are provided than the form can process."""
 
 
+class FormNotFoundError(FormException):
+    """Raised when the requested form key is not registered."""
+
+
 Loc = tuple[Union[int, str], ...]
 
 
@@ -138,12 +142,15 @@ def _display_error_type_and_ctx(error: "ErrorDict") -> str:
 def show_ex(ex: Exception, stacklimit: Union[int, None] = None) -> str:
     """Show an exception, including its class name, message and (limited) stacktrace.
 
-    >>> try:
-    ...     raise Exception("Something went wrong")
-    ... except Exception as e:
-    ...     print(show_ex(e))
-    Exception: Something went wrong
-    ...
+    Examples:
+    --------
+        >>> try:
+        ...     raise Exception("Something went wrong")
+        ... except Exception as e:
+        ...     print(show_ex(e))
+        Exception: Something went wrong
+        ...
+
     """
     tbfmt = "".join(traceback.format_tb(ex.__traceback__, stacklimit))
     return "{}: {}\n{}".format(type(ex).__name__, ex, tbfmt)

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/types.py

@@ -41,6 +41,30 @@ class SummaryData(TypedDict, total=False):
     columns: list[list[Union[str, int, bool, float]]]
 
 
+class ButtonConfig(TypedDict, total=False):
+    text: str
+    color: str
+
+
+class CustomButtons(TypedDict, total=False):
+    previous: ButtonConfig
+    next: ButtonConfig
+
+
+class FormMeta(TypedDict, total=False):
+    """Documented keys for ``FormPage.meta__``, not enforced at runtime; extra keys are allowed.
+
+    Attributes:
+        hasNext: Whether another page follows, so the frontend can label the submit button
+            accordingly.
+        customButtons: Per-button overrides (label, color) for "previous" and "next". Prefer a `ButtonsConfig`
+            field on the page, which sets this key; the two cannot be combined.
+    """
+
+    hasNext: bool
+    customButtons: CustomButtons
+
+
 InputForm = Type[BaseModel]
 AcceptData = list[Union[tuple[str, AcceptItemType], tuple[str, AcceptItemType, dict]]]
 

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/utils/json.py

@@ -74,6 +74,7 @@ decoding functions differently then `default` and `object_hook` is that they are
 :func:`json.dumps` and :func:`json.loads`.
 
 """
+
 import re
 from collections.abc import Callable
 from contextlib import suppress

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/__init__.py

@@ -1,4 +1,5 @@
 from pydantic_forms.validators.components.accept import Accept, AcceptValues
+from pydantic_forms.validators.components.buttons import Button, ButtonsConfig
 from pydantic_forms.validators.components.callout import Callout, callout
 from pydantic_forms.validators.components.choice import Choice
 from pydantic_forms.validators.components.choice_list import choice_list
@@ -21,6 +22,8 @@ from pydantic_forms.validators.components.unique_constrained_list import unique_
 __all__ = (
     "Accept",
     "AcceptValues",
+    "Button",
+    "ButtonsConfig",
     "Choice",
     "choice_list",
     "contact_person_list",

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/accept.py

@@ -19,11 +19,18 @@ from pydantic_forms.types import AcceptData, strEnum
 
 
 class AcceptValues(strEnum):
+
     ACCEPTED = "ACCEPTED"
     INCOMPLETE = "INCOMPLETE"
 
 
 class Accept(str):
+    """A checklist the user works through before the form can be submitted.
+
+    Validation fails while the value is still `"INCOMPLETE"`. Subclass it and set `data` to
+    describe the items to display.
+    """
+
     data: ClassVar[Optional[AcceptData]] = None
 
     _enum_adapter = TypeAdapter(AcceptValues)

pydantic_forms-2.7.0/pydantic_forms/validators/components/buttons.py

@@ -0,0 +1,83 @@
+# Copyright 2019-2026 SURF.
+# 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.
+from dataclasses import asdict, dataclass
+from typing import Any, Optional, cast
+
+from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler
+from pydantic.fields import FieldInfo
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import PydanticOmit, core_schema
+
+from pydantic_forms.types import ButtonConfig, CustomButtons, FormMeta
+
+
+@dataclass(frozen=True)
+class Button:
+    """Label and/or color for one button. Left as `None`, the frontend keeps its default."""
+
+    text: Optional[str] = None
+    color: Optional[str] = None
+
+    def to_meta(self) -> ButtonConfig:
+        return cast(ButtonConfig, {key: value for key, value in asdict(self).items() if value is not None})
+
+
+@dataclass(frozen=True)
+class ButtonsConfig:
+    """Overrides for the previous/next buttons, set as the default of a form field.
+
+    `custom_buttons: ButtonsConfig = ButtonsConfig(next=Button(text="Confirm"))` sends the overrides to the
+    frontend as `customButtons` in the page's meta. The field takes no input and stays out of the schema and
+    the validated result. It can't be combined with `customButtons` in the page's `meta__`.
+    """
+
+    previous: Optional[Button] = None
+    next: Optional[Button] = None
+
+    def to_meta(self) -> CustomButtons:
+        buttons = {"previous": self.previous, "next": self.next}
+        return cast(CustomButtons, {name: button.to_meta() for name, button in buttons.items() if button is not None})
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: Any, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
+        # Display-only: any input is dropped. The config is read from the field's default by `FormPage.form_meta()`.
+        return core_schema.no_info_plain_validator_function(lambda _: None)
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        raise PydanticOmit
+
+
+def merge_buttons_into_meta(
+    form_name: str, meta: Optional[FormMeta], fields: dict[str, FieldInfo]
+) -> Optional[FormMeta]:
+    """Return `meta` with the `ButtonsConfig` default among `fields` set as its `customButtons`.
+
+    `meta` itself is never modified, and is returned as-is when no field is a `ButtonsConfig`.
+    """
+    buttons_fields = {name: field for name, field in fields.items() if field.annotation is ButtonsConfig}
+    if not buttons_fields:
+        return meta
+    if missing := [name for name, field in buttons_fields.items() if not isinstance(field.default, ButtonsConfig)]:
+        raise TypeError(f"{form_name}.{missing[0]} needs a ButtonsConfig(...) default")
+    if len(buttons_fields) > 1:
+        raise TypeError(f"{form_name} has more than one ButtonsConfig field; declare all buttons in a single one")
+    if meta and "customButtons" in meta:
+        raise TypeError(
+            f"{form_name} declares its buttons both in meta__['customButtons'] and in a ButtonsConfig field"
+        )
+
+    (field,) = buttons_fields.values()
+    return {**(meta or {}), "customButtons": field.default.to_meta()}

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/callout.py

@@ -38,6 +38,7 @@ class _Callout(BaseModel):
 
 
 Callout = Annotated[_Callout, Field(frozen=True, default=None, validate_default=False)]
+"""A callout box. Use `callout()` to set its content and styling."""
 
 
 def create_callout_schema(data: CalloutData, schema: dict[str, Any]) -> None:
@@ -57,6 +58,11 @@ def callout(
     icon_type: Union[str, None] = "info",
     message_type: Union[CalloutMessageType, str] = CalloutMessageType.PRIMARY,
 ) -> type[Callout]:
+    """Create a callout box.
+
+    `message_type` selects the styling and accepts a `CalloutMessageType`: `primary`, `success`,
+    `warning`, `danger` or `accent`. `icon_type` names the icon to show, and defaults to `"info"`.
+    """
 
     data: CalloutData = {
         "header": header,

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/choice.py

@@ -19,7 +19,10 @@ from pydantic_forms.types import strEnum
 
 
 class Choice(strEnum):
-    """Let the user choose from an enum and submit the label.
+    """Let the user choose from an enum, showing a label that may differ from the stored value.
+
+    Each member is a `(value, label)` pair: the value is what the form submits, the label is what
+    the frontend displays. A member declared without a label uses its value for both.
 
     As of March 2023 mypy does not yet support functional API on Enum subclasses
     https://github.com/python/mypy/issues/6037
@@ -41,7 +44,7 @@ class Choice(strEnum):
     def __new__(cls, value: str, label: Optional[str] = None) -> "Choice":
         obj = str.__new__(cls, value)
         obj._value_ = value
-        obj.label = label or value  # type:ignore
+        obj.label = label or value  # type: ignore
         return obj
 
     @classmethod

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/choice_list.py

@@ -26,6 +26,7 @@ def choice_list(
     max_items: Optional[int] = None,
     unique_items: Optional[bool] = None,
 ) -> type[list[Choice]]:
+    """Create a multi-select list of `Choice` values."""
     if unique_items:
         from pydantic_forms.validators import unique_conlist
 
@@ -34,12 +35,12 @@ def choice_list(
     # Note: min_items always need to be there to remain backward compatible with frontend components
     if max_items:
         return Annotated[  # type: ignore[return-value]
-            list[item_type],  # type:ignore[valid-type]
+            list[item_type],  # type: ignore[valid-type]
             MinLen(min_items or 0),
             MaxLen(max_items),
         ]
 
     return Annotated[  # type: ignore[return-value]
-        list[item_type],  # type:ignore[valid-type]
+        list[item_type],  # type: ignore[valid-type]
         MinLen(min_items or 0),
     ]

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/contact_person.py

@@ -15,6 +15,7 @@ from typing import Annotated
 from pydantic import BaseModel, EmailStr, Field
 
 ContactPersonName = Annotated[str, Field(json_schema_extra={"format": "contactPersonName"})]
+"""A string tagged so the frontend renders it as a contact person name."""
 
 
 class ContactPerson(BaseModel):

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/contact_person_list.py

@@ -28,6 +28,11 @@ def contact_person_list(
     min_items: Optional[int] = None,
     max_items: Optional[int] = None,
 ) -> type[list[T]]:
+    """Create a list of `ContactPerson` entries.
+
+    Deprecated: use `orchestrator.forms.validators.customer_contact_list` instead.
+    """
+
     def json_schema_extra() -> Generator:
         if organisation:
             yield "organisationId", organisation

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/display_subscription.py

@@ -20,3 +20,7 @@ DisplaySubscription = Annotated[
     UUID,
     Field(frozen=True, json_schema_extra={"format": "subscription", "type": "string"}),
 ]
+"""Displays a subscription, identified by UUID. Display-only: it collects no input.
+
+Deprecated: use `orchestrator.forms.validators.DisplaySubscription` instead.
+"""

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/divider.py

@@ -15,3 +15,4 @@ from typing import Annotated, Optional
 from pydantic import Field
 
 Divider = Annotated[Optional[str], Field(None, frozen=True, json_schema_extra={"format": "divider", "type": "string"})]
+"""A horizontal separator line. Display-only: it collects no input."""

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/hidden.py

@@ -15,3 +15,4 @@ from typing import Annotated, Optional
 from pydantic import Field
 
 Hidden = Annotated[Optional[str], Field(None, frozen=True, json_schema_extra={"format": "hidden", "type": "string"})]
+"""A field that is not shown to the user. Display-only: it collects no input."""

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/label.py

@@ -15,3 +15,4 @@ from typing import Annotated, Optional
 from pydantic import Field
 
 Label = Annotated[Optional[str], Field(None, frozen=True, json_schema_extra={"format": "label", "type": "string"})]
+"""A plain string formatted as a label. Display-only: it collects no input."""

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/list_of_one.py

@@ -18,3 +18,4 @@ from pydantic import Field
 from pydantic_forms.validators.components.unique_constrained_list import T
 
 ListOfOne = Annotated[list[T], Field(min_length=1, max_length=1)]
+"""A list constrained to exactly one item."""

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/list_of_two.py

@@ -22,3 +22,4 @@ ListOfTwo = Annotated[
     AfterValidator(validate_unique_list),
     Field(min_length=2, max_length=2, json_schema_extra={"uniqueItems": True}),
 ]
+"""A list constrained to exactly two items, which must differ from each other."""

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/long_text.py

@@ -15,3 +15,4 @@ from typing import Annotated
 from pydantic import Field
 
 LongText = Annotated[str, Field(json_schema_extra={"format": "long"})]
+"""A multi-line text input."""

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/markdown.py

@@ -36,6 +36,7 @@ class _Markdown(BaseModel):
 
 
 Markdown = Annotated[_Markdown, Field(frozen=True, default=None, validate_default=False)]
+"""A block of rendered Markdown. Use `markdown()` to set its content."""
 
 
 def create_markdown_schema(data: MarkdownData, schema: dict[str, Any]) -> None:
@@ -53,6 +54,10 @@ def markdown(
     content: Union[str, None] = None,
     color: Union[MarkdownColor, str] = MarkdownColor.PRIMARY,
 ) -> type[Markdown]:
+    """Create a block of rendered Markdown.
+
+    `color` accepts a `MarkdownColor`: `primary`, `success`, `warning`, `danger` or `accent`.
+    """
 
     data: MarkdownData = {
         "content": content,

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/migration_summary.py

@@ -25,6 +25,7 @@ class _MigrationSummary(BaseModel):
 
 
 MigrationSummary = Annotated[_MigrationSummary, Field(frozen=True, default=None, validate_default=False)]
+"""A static summary table. Use `migration_summary()` to supply its data."""
 
 
 def create_json_extra_schema(data: SummaryData, schema: dict[str, Any]) -> None:
@@ -40,6 +41,7 @@ def create_json_extra_schema(data: SummaryData, schema: dict[str, Any]) -> None:
 
 
 def migration_summary(data: SummaryData) -> type[MigrationSummary]:
+    """Create a static table from a `{headers, labels, columns}` mapping."""
     namespace = {"data": data}
     klass: type[MigrationSummary] = new_class(
         "MigrationSummaryValue", (_MigrationSummary,), {}, lambda ns: ns.update(namespace)

{pydantic_forms-2.6.0 → pydantic_forms-2.7.0}/pydantic_forms/validators/components/organisation_id.py

@@ -19,3 +19,7 @@ OrganisationId = Annotated[
     str,
     Field(json_schema_extra={"format": "organisationId"}),
 ]
+"""A string tagged for organisation-ID rendering.
+
+Deprecated: use `orchestrator.forms.validators.CustomerId` instead.
+"""