Update examples and test suite

Tests now all collect, though several are still failing and
the websocket test is hanging.

The DocstringToMessage mixin was not working, this is now fixed.

I now use ... as a default value for `default` in properties/settings, because None is a legitimate value.

Author: rwb27

docs/source/quickstart/counter.py

@@ -22,9 +22,8 @@ def slowly_increase_counter(self) -> None:
             time.sleep(1)
             self.increment_counter()
 
-    counter = lt.ThingProperty(
-        model=int, initial_value=0, readonly=True, description="A pointless counter"
-    )
+    counter: int = lt.property(0, readonly=True)
+    "A pointless counter"
 
 
 if __name__ == "__main__":

src/labthings_fastapi/example_things/__init__.py

@@ -7,8 +7,8 @@
 import time
 from typing import Any, Optional, Annotated
 from labthings_fastapi.thing import Thing
-from labthings_fastapi.decorators import thing_action, thing_property
-from labthings_fastapi.descriptors import ThingProperty
+from labthings_fastapi.decorators import thing_action
+from labthings_fastapi.thing_property import property as lt_property
 from pydantic import Field
 
 
@@ -94,15 +94,11 @@ def slowly_increase_counter(self, increments: int = 60, delay: float = 1):
             time.sleep(delay)
             self.increment_counter()
 
-    counter = ThingProperty(
-        model=int, initial_value=0, readonly=True, description="A pointless counter"
-    )
+    counter: int = lt_property(0, readonly=True)
+    "A pointless counter"
 
-    foo = ThingProperty(
-        model=str,
-        initial_value="Example",
-        description="A pointless string for demo purposes.",
-    )
+    foo: str = lt_property("Example")
+    "A pointless string for demo purposes."
 
     @thing_action
     def action_without_arguments(self) -> None:
@@ -129,7 +125,7 @@ def broken_action(self):
         """
         raise RuntimeError("This is a broken action")
 
-    @thing_property
+    @lt_property
     def broken_property(self):
         """Raise an exception when the property is accessed.
 

src/labthings_fastapi/exceptions.py

@@ -16,7 +16,7 @@ class DocstringToMessage:
 
     append_to_message: bool = True
 
-    def __init__(self, message: str | None):
+    def __init__(self, message: str | None = None):
         """Initialise an error with a message or its docstring.
 
         :param message: the optional message.

src/labthings_fastapi/thing_property.py

@@ -46,6 +46,7 @@ class attribute. Documentation is in strings immediately following the
 
 from __future__ import annotations
 import builtins
+from types import EllipsisType
 from typing import (
     Annotated,
     Callable,
@@ -135,7 +136,7 @@ def property(default_factory: ValueFactory, readonly: bool = False) -> Value: ..
 
 
 def property(
-    default: Value | ValueGetter | None = None,
+    default: Value | ValueGetter | EllipsisType = ...,
     *,
     default_factory: ValueFactory | None = None,
     readonly: bool = False,
@@ -195,6 +196,11 @@ def property(
     as ``mypy`` will check that the default is valid for the type of the
     field, and won't raise an error about assigning, for example, an
     instance of ``DataProperty[int]`` to a field annotated as ``int``.
+
+    Finally, the type of the ``default`` argument includes `.EllipsisType`
+    so that we can use ``...`` as its default value. This allows us to
+    distinguish between ``default`` not being set (``...``) and a desired
+    default value of ``None``.
     """
     if callable(default):
         # If the default is callable, we're being used as a decorator
@@ -231,7 +237,7 @@ class DataProperty(BaseProperty[Value], Generic[Value]):
 
     def __init__(
         self,
-        default: Value | None = None,
+        default: Value | EllipsisType = ...,
         *,
         default_factory: ValueFactory | None,
         readonly: bool = False,
@@ -256,7 +262,9 @@ def __init__(
         ``__init__``.
 
         :param default: the default value. This or ``default_factory`` must
-            be provided.
+            be provided. Note that, as ``None`` is a valid default value,
+            this uses ``...`` instead as a way of checking whether ``default``
+            has been set.
         :param default_factory: a function that returns the default value.
             This is appropriate for datatypes such as lists, where using
             a mutable default value can lead to odd behaviour.
@@ -268,13 +276,17 @@ def __init__(
             factory function are specified.
         :raises MissingDefaultError: if no default is provided.
         """
-        if default_factory is not None:
-            if default is not None:
-                raise OverspecifiedDefaultError()
-            self._default_value: Value = default_factory()
-        if default is None:
+        if default_factory is not None and default is not ...:
+            raise OverspecifiedDefaultError()
+        if default_factory is None and default is ...:
             raise MissingDefaultError()
-        self._default_value: Value = default
+        # The default value will come from whichever of `default` and `default_factory`
+        # is specified. The two checks above ensure that exactly one will exist.
+        self._default_value: Value
+        if default_factory:
+            self._default_value = default_factory
+        else:
+            self._default_value = default
         self.readonly = readonly
         self._type: type | None = None  # Will be set in __set_name__
 
@@ -498,7 +510,7 @@ def property_affordance(
 
 
 def setting(
-    default: Value | None = None,
+    default: Value | EllipsisType = ...,
     *,
     default_factory: ValueFactory | None = None,
     readonly: bool = False,

tests/test_action_cancel.py

@@ -10,16 +10,13 @@
 
 
 class CancellableCountingThing(lt.Thing):
-    counter = lt.ThingProperty(int, 0, observable=False)
-    check = lt.ThingProperty(
-        bool,
-        False,
-        observable=False,
-        description=(
-            "This variable is used to check that the action can detect a cancel event "
-            "and react by performing another task, in this case, setting this variable."
-        ),
-    )
+    counter: int = lt.property(0)
+    check: bool = lt.property(False)
+    """Whether the count has been cancelled.
+    
+    This variable is used to check that the action can detect a cancel event
+    and react by performing another task, in this case, setting this variable.
+    """
 
     @lt.thing_action
     def count_slowly(self, cancel: lt.deps.CancelHook, n: int = 10):

tests/test_action_manager.py

@@ -13,9 +13,8 @@ def increment_counter(self):
         """Increment the counter"""
         self.counter += 1
 
-    counter = lt.ThingProperty(
-        model=int, initial_value=0, readonly=True, description="A pointless counter"
-    )
+    counter: int = lt.property(0, readonly=True)
+    "A pointless counter"
 
 
 thing = TestThing()

tests/test_dependency_metadata.py

@@ -13,7 +13,7 @@ def __init__(self):
         lt.Thing.__init__(self)
         self._a = 0
 
-    @lt.thing_property
+    @lt.property
     def a(self):
         return self._a
 

tests/test_properties.py

@@ -9,18 +9,21 @@
 
 
 class TestThing(lt.Thing):
-    boolprop = lt.ThingProperty(bool, False, description="A boolean property")
-    stringprop = lt.ThingProperty(str, "foo", description="A string property")
+    boolprop: bool = lt.property(False)
+    "A boolean property"
+
+    stringprop: str = lt.property("foo")
+    "A string property"
 
     _undoc = None
 
-    @lt.thing_property
+    @lt.property
     def undoc(self):
         return self._undoc
 
     _float = 1.0
 
-    @lt.thing_property
+    @lt.property
     def floatprop(self) -> float:
         return self._float
 
@@ -45,12 +48,12 @@ def toggle_boolprop_from_thread(self):
 
 def test_instantiation_with_type():
     """
-    Check the internal model (data type) of the ThingSetting descriptor is a BaseModel
+    Check the internal model (data type) of the DataProperty descriptor is a BaseModel
 
     To send the data over HTTP LabThings-FastAPI uses Pydantic models to describe data
     types.
     """
-    prop = lt.ThingProperty(bool, False)
+    prop: bool = lt.property(False)
     assert issubclass(prop.model, BaseModel)
 
 
@@ -59,7 +62,7 @@ class MyModel(BaseModel):
         a: int = 1
         b: float = 2.0
 
-    prop = lt.ThingProperty(MyModel, MyModel())
+    prop: MyModel = lt.property(MyModel())
     assert prop.model is MyModel
 
 
@@ -71,7 +74,7 @@ def test_property_get_and_set():
         assert after_value.json() == test_str
 
 
-def test_ThingProperty():
+def test_boolprop():
     with TestClient(server.app) as client:
         r = client.get("/thing/boolprop")
         assert r.json() is False
@@ -123,7 +126,7 @@ def test_setting_from_thread():
 
 
 def test_setting_without_event_loop():
-    """Test that an exception is raised if updating a ThingProperty
+    """Test that an exception is raised if updating a DataProperty
     without connecting the Thing to a running server with an event loop.
     """
     # This test may need to change, if we change the intended behaviour

tests/test_settings.py

@@ -11,21 +11,17 @@
 
 
 class TestThing(lt.Thing):
-    boolsetting = lt.ThingSetting(bool, False, description="A boolean setting")
-    stringsetting = lt.ThingSetting(str, "foo", description="A string setting")
-    dictsetting = lt.ThingSetting(
-        dict, {"a": 1, "b": 2}, description="A dictionary setting"
-    )
+    boolsetting: bool = lt.setting(False)
+    "A boolean setting"
 
-    _float = 1.0
+    stringsetting: str = lt.setting("foo")
+    "A string setting"
 
-    @lt.thing_setting
-    def floatsetting(self) -> float:
-        return self._float
+    dictsetting: dict = lt.setting(default_factory=lambda: {"a": 1, "b": 2})
+    "A dictionary setting"
 
-    @floatsetting.setter
-    def floatsetting(self, value: float):
-        self._float = value
+    floatsetting: float = lt.setting(1.0)
+    "A float setting"
 
     @lt.thing_action
     def toggle_boolsetting(self):

tests/test_thing_lifecycle.py

@@ -3,7 +3,8 @@
 
 
 class TestThing(lt.Thing):
-    alive = lt.ThingProperty(bool, False, description="Is the thing alive?")
+    alive: bool = lt.property(False)
+    "Whether the thing is alive."
 
     def __enter__(self):
         print("setting up TestThing from __enter__")