feat(FormModel): allow scalars where collections are expected

Makes it easier on the LMS-side, since it needn't know which fields can produce multiple values.

See: questionpy-org/moodle-qtype_questionpy#149 (comment)

Author: MHajoha

questionpy/form/_dsl.py

@@ -1,8 +1,10 @@
 #  This file is part of the QuestionPy SDK. (https://questionpy.org)
 #  The QuestionPy SDK is free software released under terms of the MIT license. See LICENSE.md.
 #  (c) Technische Universität Berlin, innoCampus <[email protected]>
+from collections.abc import Collection
 from typing import Any, Literal, Optional, TypeAlias, TypeVar, cast, overload
 
+from pydantic import BeforeValidator
 from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefined
 
@@ -27,20 +29,34 @@
 # TODO: - Add support for numeric inputs (and maybe others?)
 #       - Make labels optional
 
+
 _S = TypeVar("_S", bound=str)
 _F = TypeVar("_F", bound=FormModel)
 _E = TypeVar("_E", bound=OptionEnum)
 
 _OneOrMoreConditions: TypeAlias = Condition | list[Condition]
 _ZeroOrMoreConditions: TypeAlias = _OneOrMoreConditions | None
 
+_T = TypeVar("_T")
+
+
+@overload
+def _wrap_in(coll_type: type[set], value: _T | Collection[_T] | None) -> set[_T]: ...
+
+
+@overload
+def _wrap_in(coll_type: type[list], value: _T | Collection[_T] | None) -> list[_T]: ...
+
 
-def _listify(value: _ZeroOrMoreConditions) -> list[Condition]:
+def _wrap_in(coll_type: type[set] | type[list], value: _T | Collection[_T] | None) -> Collection[_T]:
     if value is None:
-        return []
-    if isinstance(value, list):
-        return value
-    return [value]
+        return coll_type()
+    if isinstance(value, coll_type):
+        return cast(Collection[_T], value)
+    if isinstance(value, Collection) and not isinstance(value, str):  # (str is a subclass of Collection)
+        return coll_type(value)
+
+    return coll_type((cast(_T, value),))  # MyPy gets confused here without the cast.
 
 
 @overload
@@ -132,8 +148,8 @@ def text_input(
             default=default,
             placeholder=placeholder,
             help=help,
-            disable_if=_listify(disable_if),
-            hide_if=_listify(hide_if),
+            disable_if=_wrap_in(list, disable_if),
+            hide_if=_wrap_in(list, hide_if),
         ),
         pydantic_field_info=FieldInfo(
             default=None if not required or disable_if or hide_if else PydanticUndefined,
@@ -231,8 +247,8 @@ def text_area(
             default=default,
             placeholder=placeholder,
             help=help,
-            disable_if=_listify(disable_if),
-            hide_if=_listify(hide_if),
+            disable_if=_wrap_in(list, disable_if),
+            hide_if=_wrap_in(list, hide_if),
         ),
         pydantic_field_info=FieldInfo(
             default=None if not required or disable_if or hide_if else PydanticUndefined,
@@ -265,7 +281,12 @@ def static_text(
         StaticTextElement,
         _StaticElementInfo(
             lambda name: StaticTextElement(
-                name=name, label=label, text=text, help=help, disable_if=_listify(disable_if), hide_if=_listify(hide_if)
+                name=name,
+                label=label,
+                text=text,
+                help=help,
+                disable_if=_wrap_in(list, disable_if),
+                hide_if=_wrap_in(list, hide_if),
             )
         ),
     )
@@ -360,8 +381,8 @@ def checkbox(
             required=required,
             help=help,
             selected=selected,
-            disable_if=_listify(disable_if),
-            hide_if=_listify(hide_if),
+            disable_if=_wrap_in(list, disable_if),
+            hide_if=_wrap_in(list, hide_if),
         ),
         pydantic_field_info=FieldInfo(default=False if not required or disable_if or hide_if else PydanticUndefined),
     )
@@ -451,8 +472,8 @@ def radio_group(
             options=options,
             required=required,
             help=help,
-            disable_if=_listify(disable_if),
-            hide_if=_listify(hide_if),
+            disable_if=_wrap_in(list, disable_if),
+            hide_if=_wrap_in(list, hide_if),
         ),
         pydantic_field_info=FieldInfo(default=None if not required or disable_if or hide_if else PydanticUndefined),
     )
@@ -556,9 +577,11 @@ def select(
 
     expected_type: type
     default: object
+    annotate_with: tuple[object, ...] = ()
     if multiple:
         expected_type = set[enum]  # type: ignore[valid-type]
         default = set() if not required or disable_if or hide_if else PydanticUndefined
+        annotate_with = (BeforeValidator(lambda value: _wrap_in(set, value)),)
     elif not required or disable_if or hide_if:
         expected_type = enum | None  # type: ignore[assignment]
         default = None
@@ -575,10 +598,11 @@ def select(
             required=required,
             options=options,
             help=help,
-            disable_if=_listify(disable_if),
-            hide_if=_listify(hide_if),
+            disable_if=_wrap_in(list, disable_if),
+            hide_if=_wrap_in(list, hide_if),
         ),
         pydantic_field_info=FieldInfo(default=default),
+        annotate_with=annotate_with,
     )
 
 
@@ -635,7 +659,7 @@ def hidden(value: _S, *, disable_if: _ZeroOrMoreConditions = None, hide_if: _Zer
         _FieldInfo(
             type=Optional[Literal[value]] if disable_if or hide_if else Literal[value],  # noqa: UP007
             build=lambda name: HiddenElement(
-                name=name, value=value, disable_if=_listify(disable_if), hide_if=_listify(hide_if)
+                name=name, value=value, disable_if=_wrap_in(list, disable_if), hide_if=_wrap_in(list, hide_if)
             ),
             pydantic_field_info=FieldInfo(default=None if disable_if or hide_if else PydanticUndefined),
         ),
@@ -715,8 +739,8 @@ def group(
                 label=label,
                 elements=model.qpy_form.general,
                 help=help,
-                disable_if=_listify(disable_if),
-                hide_if=_listify(hide_if),
+                disable_if=_wrap_in(list, disable_if),
+                hide_if=_wrap_in(list, hide_if),
             ),
             # When the group dict is not provided at all in the form data, we want Pydantic to use the default values
             # for all grouped fields and raise if there are any required ones. Creating the nested model in a
@@ -778,6 +802,7 @@ def repeat(
                 button_label=button_label,
                 elements=model.qpy_form.general,
             ),
+            annotate_with=(BeforeValidator(lambda value: _wrap_in(list, value)),),
         ),
     )
 

questionpy/form/_model.py

@@ -5,8 +5,9 @@
 from dataclasses import dataclass
 from enum import Enum
 from itertools import starmap
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, get_args, get_origin
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Literal, get_args, get_origin
 
+from mypyc.ir.ops import Sequence
 from pydantic import BaseModel, Field
 from pydantic._internal._model_construction import ModelMetaclass  # noqa: PLC2701
 from pydantic.fields import FieldInfo
@@ -75,6 +76,8 @@ class _FieldInfo:
     functions are called. So they provide a callable instead that takes the name and returns the complete form element.
     """
     pydantic_field_info: FieldInfo | None = None
+    annotate_with: Sequence[object] = ()
+    """Annotations as in [typing.Annotated][] to add to the field type. Useful for [pydantic.BeforeValidator][]."""
 
 
 @dataclass
@@ -130,11 +133,14 @@ def __new__(mcs, name: str, bases: tuple[type, ...], namespace: dict, **kwargs:
         form = OptionsFormDefinition()
 
         for key, value in namespace.items():
+            annotate_with: list[object] = []
             if isinstance(value, _FieldInfo):
                 expected_type = value.type
                 form.general.append(value.build(key))
                 if value.pydantic_field_info is not None:
                     new_namespace[key] = value.pydantic_field_info
+                if value.annotate_with:
+                    annotate_with.extend(value.annotate_with)
             elif isinstance(value, _SectionInfo):
                 form.sections.append(FormSection(name=key, header=value.header, elements=value.model.qpy_form.general))
                 expected_type = value.model
@@ -162,6 +168,10 @@ def __new__(mcs, name: str, bases: tuple[type, ...], namespace: dict, **kwargs:
                 # this won't help type checkers or code completion, but will allow pydantic to validate inputs
                 annotations[key] = expected_type
 
+            if annotate_with:
+                # If the field type has been annotated by the user, this will add our annotations to theirs.
+                annotations[key] = Annotated[annotations[key], *annotate_with]
+
         new_namespace["qpy_form"] = form
         new_namespace["__annotations__"] = annotations
         return super().__new__(mcs, name, bases, new_namespace, **kwargs)