Implement default and reset for properties

This works on DataProperty and raises a specific exception for FunctionalProperty.

It is not yet exposed over HTTP, but is tested in Python.

Author: rwb27

src/labthings_fastapi/exceptions.py

@@ -202,3 +202,14 @@ class NotBoundToInstanceError(RuntimeError):
     generated from a `.Thing` class. Usually, they should be accessed via a
     `.Thing` instance, in which case they will be bound.
     """
+
+
+class FeatureNotAvailable(NotImplementedError):
+    """A feature is not available.
+
+    There are some methods provided by base classes where implementation is optional.
+    These methods raise `FeatureNotAvailable` if they are not implemented.
+
+    Currently this is done for the default value of properties, and their reset
+    method.
+    """

src/labthings_fastapi/properties.py

@@ -83,6 +83,7 @@ class attribute. Documentation is in strings immediately following the
     FieldTypedBaseDescriptorInfo,
 )
 from .exceptions import (
+    FeatureNotAvailable,
     NotConnectedToServerError,
     ReadOnlyPropertyError,
     MissingTypeError,
@@ -393,6 +394,38 @@ def model(self) -> type[BaseModel]:
             )
         return self._model
 
+    def default(self, obj: Owner | None) -> Value:
+        """Return the default value of this property.
+
+        :param obj: the `.Thing` instance on which we are looking for the default.
+            or `None` if referring to the class. For now, this is ignored.
+
+        :return: the default value of this property.
+        :raises FeatureNotAvailable: as this must be overridden.
+        """
+        raise FeatureNotAvailable(
+            f"{obj.name if obj else self.__class__}.{self.name} cannot be reset, "
+            f"as it's not supported by {self.__class__}."
+        )
+
+    def reset(self, obj: Owner) -> None:
+        """Reset the property's value to a default state.
+
+        If there is a defined default value for the property, this method
+        should reset the property to that default.
+
+        Not every property is expected to implement ``reset`` so it is important
+        to handle `.FeatureNotAvailable` exceptions, which will be raised if this
+        method is not overridden.
+
+        :param thing: the `.Thing` instance we want to reset.
+        :raises FeatureNotAvailable: as only some subclasses implement resetting.
+        """
+        raise FeatureNotAvailable(
+            f"{obj.name}.{self.name} cannot be reset, as it's not supported by "
+            f"{self.__class__}."
+        )
+
     def add_to_fastapi(self, app: FastAPI, thing: Owner) -> None:
         """Add this action to a FastAPI app, bound to a particular Thing.
 
@@ -612,6 +645,23 @@ def __set__(
         if emit_changed_event:
             self.emit_changed_event(obj, value)
 
+    def default(self, obj: Owner | None) -> Value:
+        """Return the default value of this property.
+
+        Note that this implementation is independent of the `.Thing` instance,
+        as there's currently no way to specify a per-instance default.
+
+        :return: the default value of this property.
+        """
+        return self._default_factory()
+
+    def reset(self, obj: Owner) -> None:
+        r"""Reset the property to its default value.
+
+        This resets to the value returned by ``default`` for `.DataProperty`\ .
+        """
+        self.__set__(obj, self.default(obj))
+
     def _observers_set(self, obj: Thing) -> WeakSet:
         """Return the observers of this property.
 
@@ -863,6 +913,25 @@ def model_instance(self) -> BaseModel:  # noqa: DOC201
                 raise TypeError(msg)
             return cls(root=value)
 
+    @builtins.property
+    def default(self) -> Value:
+        """The default value of this property.
+
+        .. warning::
+            Note that this is an optional feature, so calling code must handle
+            `.FeatureNotAvailable` exceptions.
+        """
+        return self.get_descriptor().default(self.owning_object)
+
+    def reset(self) -> None:
+        """Reset the property to a default value.
+
+        .. warning::
+            Note that this is an optional feature, so calling code must handle
+            `.FeatureNotAvailable` exceptions.
+        """
+        return self.get_descriptor().reset(self.owning_object_or_error())
+
     def validate(self, value: Any) -> Value:
         """Use the validation logic in `self.model`.
 

tests/test_property.py

@@ -25,7 +25,12 @@
     default_factory_from_arguments,
 )
 from labthings_fastapi.base_descriptor import DescriptorAddedToClassTwiceError
-from labthings_fastapi.exceptions import MissingTypeError, NotConnectedToServerError
+from labthings_fastapi.exceptions import (
+    FeatureNotAvailable,
+    MissingTypeError,
+    NotBoundToInstanceError,
+    NotConnectedToServerError,
+)
 import labthings_fastapi as lt
 from labthings_fastapi.testing import create_thing_without_server
 from .utilities import raises_or_is_caused_by
@@ -456,3 +461,46 @@ def _set_funcprop(self, val: int) -> None:
         "ro_functional_property_with_setter",
     ]:
         assert td.properties[name].readOnly is True
+
+
+def test_default_and_reset():
+    """Test retrieving property defaults, and resetting to default."""
+
+    class Example(lt.Thing):
+        intprop: int = lt.property(default=42)
+        listprop: list[str] = lt.property(default_factory=lambda: ["a", "list"])
+
+        @lt.property
+        def strprop(self) -> str:
+            return "Hello World!"
+
+    example = create_thing_without_server(Example)
+
+    # Defaults should be available on classes and instances
+    for thing in [example, Example]:
+        # We shoulld get expected values for defaults
+        assert thing.properties["intprop"].default == 42
+        assert thing.properties["listprop"].default == ["a", "list"]
+        # Defaults are not available for FunctionalProperties
+        with pytest.raises(FeatureNotAvailable):
+            _ = thing.properties["strprop"].default
+
+    # Resetting to default isn't available on classes
+    for name in ["intprop", "listprop", "strprop"]:
+        with pytest.raises(NotBoundToInstanceError):
+            thing.properties[name].reset()
+
+    # Resetting should work for DataProperty
+    example.intprop = 43
+    assert example.intprop == 43
+    example.properties["intprop"].reset()
+    assert example.intprop == 42
+
+    example.listprop = []
+    assert example.listprop == []
+    example.properties["listprop"].reset()
+    assert example.listprop == ["a", "list"]
+
+    # Resetting won't work for FunctionalProperty
+    with pytest.raises(FeatureNotAvailable):
+        example.properties["strprop"].reset()