Use a typeddict for stricter validation and helpful autocompletion

The `constraints` property is now a typed dictionary. Assigning dictionary literals to it still ought to work, but it should flag type errors if the keys are incorrect.

The method `BaseProperty._validate_constraints` is provided to convert untyped dictionaries with appropriate validation. This now uses `pydantic` to validate the typeddict. It is stricter than what I did before, as it also checks the type of the keys, not just their names.

Pydantic was less ugly than coming up with my own logic to coerce an untyped dictionary into a typeddict. I've added a unit test on validation to check it does what I expect.

It would be lovely to deduplicate the typeddict and the constant with key names in it - but this is hard to do neatly.

Author: rwb27

src/labthings_fastapi/properties.py

@@ -55,14 +55,23 @@ class attribute. Documentation is in strings immediately following the
     Callable,
     Generic,
     TypeVar,
+    TypedDict,
     overload,
     TYPE_CHECKING,
 )
 from typing_extensions import Self
 from weakref import WeakSet
 
 from fastapi import Body, FastAPI
-from pydantic import BaseModel, ConfigDict, RootModel, ValidationError, create_model
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    RootModel,
+    TypeAdapter,
+    ValidationError,
+    create_model,
+    with_config,
+)
 
 from .thing_description import type_to_dataschema
 from .thing_description._model import (
@@ -122,6 +131,21 @@ class attribute. Documentation is in strings immediately following the
 """The set of supported constraint arguments for properties."""
 
 
+@with_config(ConfigDict(extra="forbid"))
+class FieldConstraints(TypedDict, total=False):
+    r"""Constraints that may be applied to a `.property`\ ."""
+
+    gt: int | float
+    ge: int | float
+    lt: int | float
+    le: int | float
+    multiple_of: int | float
+    allow_inf_nan: bool
+    min_length: int
+    max_length: int
+    pattern: str
+
+
 # The following exceptions are raised only when creating/setting up properties.
 class OverspecifiedDefaultError(ValueError):
     """The default value has been specified more than once.
@@ -350,14 +374,33 @@ def __init__(self, constraints: Mapping[str, Any] | None = None) -> None:
         super().__init__()
         self._model: type[BaseModel] | None = None
         self.readonly: bool = False
-        self._constraints = {}
+        self._constraints: FieldConstraints = {}
         try:
-            self.constraints = constraints or {}
+            self.constraints = self._validate_constraints(constraints or {})
         except UnsupportedConstraintError:
             raise
 
+    @staticmethod
+    def _validate_constraints(constraints: Mapping[str, Any]) -> FieldConstraints:
+        """Validate an untyped dictionary of constraints.
+
+        :param constraints: A mapping that will be validated against the
+            `.FieldConstraints` typed dictionary.
+        :return: A `.FieldConstraints` instance.
+        :raises UnsupportedConstraintError: if the input is not valid.
+        """
+        validator = TypeAdapter(FieldConstraints)
+        try:
+            return validator.validate_python(constraints)
+        except ValidationError as e:
+            raise UnsupportedConstraintError(
+                f"Bad constraint arguments were supplied ({constraints}). \n"
+                f"Supported arguments are: {', '.join(CONSTRAINT_ARGS)}.\n"
+                f"Validation error details are below: \n\n{e}"
+            ) from e
+
     @builtins.property
-    def constraints(self) -> Mapping[str, Any]:  # noqa[DOC201]
+    def constraints(self) -> FieldConstraints:  # noqa[DOC201]
         """Validation constraints applied to this property.
 
         This mapping contains keyword arguments that will be passed to
@@ -373,20 +416,17 @@ def constraints(self) -> Mapping[str, Any]:  # noqa[DOC201]
         return self._constraints
 
     @constraints.setter
-    def constraints(self, new_constraints: Mapping[str, Any]) -> None:
+    def constraints(self, new_constraints: FieldConstraints) -> None:
         r"""Set the constraints added to the model.
 
         :param new_constraints: the new value of ``constraints``\ .
 
         :raises UnsupportedConstraintError: if invalid dictionary keys are present.
         """
-        for key in new_constraints:
-            if key not in CONSTRAINT_ARGS:
-                raise UnsupportedConstraintError(
-                    f"Unknown constraint argument: {key}. \n"
-                    f"Supported arguments are: {', '.join(CONSTRAINT_ARGS)}."
-                )
-        self._constraints = new_constraints
+        try:
+            self._constraints = self._validate_constraints(new_constraints)
+        except UnsupportedConstraintError:
+            raise
 
     @builtins.property
     def model(self) -> type[BaseModel]:

tests/test_properties.py

@@ -467,6 +467,44 @@ def functional_bad_prop(self) -> str:
             functional_bad_prop.constraints = {"bad_constraint": 2}
 
 
+GOOD_CONSTRAINTS = []
+# Single numeric constraints (test float and int)
+GOOD_CONSTRAINTS += [
+    {k: v} for k in ["ge", "gt", "le", "lt", "multiple_of"] for v in [3, 3.4]
+]
+# Max/min length
+GOOD_CONSTRAINTS += [{k: 10} for k in ["max_length", "min_length"]]
+# Allow_inf_nan
+GOOD_CONSTRAINTS += [{"allow_inf_nan": v} for v in [True, False]]
+# Pattern
+GOOD_CONSTRAINTS += [{"pattern": v} for v in ["test", r"[0-9]+"]]
+
+
+BAD_CONSTRAINTS = []
+# These should be numerics
+BAD_CONSTRAINTS += [
+    {k: "str"}
+    for k in ["ge", "gt", "le", "lt", "multiple_of", "max_length", "min_length"]
+]
+# pattern must be a string
+BAD_CONSTRAINTS += [{"pattern": 152}]
+# other keys should not be allowed
+BAD_CONSTRAINTS += [{"invalid": None}]
+
+
+@pytest.mark.parametrize("constraints", GOOD_CONSTRAINTS)
+def test_successful_constraint_validation(constraints):
+    """Check valid constraints values are passed through."""
+    assert BaseProperty._validate_constraints(constraints) == constraints
+
+
+@pytest.mark.parametrize("constraints", BAD_CONSTRAINTS)
+def test_unsuccessful_constraint_validation(constraints):
+    """Check invalid constraints values are flagged."""
+    with pytest.raises(UnsupportedConstraintError):
+        BaseProperty._validate_constraints(constraints)
+
+
 def test_propertyinfo():
     """Check the PropertyInfo class is generated correctly."""
 

typing_tests/thing_properties.py

@@ -288,3 +288,27 @@ def strprop(self, val: str) -> None:
 assert_type(test_functional_property.intprop3, int)
 assert_type(test_functional_property.fprop, int)
 # ``strprop`` will be ``Any`` because of the ``[no-redef]`` error.
+
+
+class TestConstrainedProperties(lt.Thing):
+    """A class with some correctly and incorrectly-defined constraints."""
+
+    # Constraints can be passed as kwargs to `lt.property` but currently
+    # aren't explicit, so don't get checked by mypy.
+    # The line below is valid
+    positiveint: int = lt.property(default=0, ge=0)
+
+    # The line below is not valid but doesn't bother mypy.
+    # This would get picked up at runtime, as we validate the kwargs.
+    negativeint: int = lt.property(default=0, sign="negative")
+
+    @lt.property
+    def positivefloat(self) -> float:
+        """A functional property."""
+        return 42
+
+    positivefloat.constraints = {"gt": 0.0}  # This is OK
+
+    # The typed dict checks the name and type of constraints, so the line
+    # below should be flagged. This is also validated at runtime by pydantic
+    positivefloat.constraints = {"gt": "zero"}  # type:ignore[typeddict-item]