Change the names for setting/property descriptors, add some docstrings

Author: julianstirling

src/labthings_fastapi/client/in_server.py

@@ -16,7 +16,7 @@
 from pydantic import BaseModel
 from labthings_fastapi.descriptors.action import ActionDescriptor
 
-from labthings_fastapi.descriptors.property import PropertyDescriptor
+from labthings_fastapi.descriptors.property import ThingProperty
 from labthings_fastapi.utilities import attributes
 from . import PropertyClientDescriptor
 from ..thing import Thing
@@ -123,15 +123,15 @@ def action_method(self, **kwargs):
 
 
 def add_property(
-    attrs: dict[str, Any], property_name: str, property: PropertyDescriptor
+    attrs: dict[str, Any], property_name: str, property: ThingProperty
 ) -> None:
     """Add a property to a DirectThingClient subclass"""
     attrs[property_name] = property_descriptor(
         property_name,
         property.model,
         description=property.description,
         writeable=not property.readonly,
-        readable=True,  # TODO: make this configurable in PropertyDescriptor
+        readable=True,  # TODO: make this configurable in ThingProperty
     )
 
 
@@ -163,7 +163,7 @@ def init_proxy(self, request: Request, **dependencies: Mapping[str, Any]):
     }
     dependencies: list[inspect.Parameter] = []
     for name, item in attributes(thing_class):
-        if isinstance(item, PropertyDescriptor):
+        if isinstance(item, ThingProperty):
             # TODO: What about properties that don't use descriptors? Fall back to http?
             add_property(client_attrs, name, item)
         elif isinstance(item, ActionDescriptor):

src/labthings_fastapi/decorators/__init__.py

@@ -36,8 +36,8 @@
 from typing import Optional, Callable
 from ..descriptors import (
     ActionDescriptor,
-    PropertyDescriptor,
-    SettingDescriptor,
+    ThingProperty,
+    ThingSetting,
     EndpointDescriptor,
     HTTPMethod,
 )
@@ -72,33 +72,42 @@ def thing_action(func: Optional[Callable] = None, **kwargs):
         return partial(mark_thing_action, **kwargs)
 
 
-def thing_property(func: Callable) -> PropertyDescriptor:
+def thing_property(func: Callable) -> ThingProperty:
     """Mark a method of a Thing as a Property
 
-    Replace the function with a `Descriptor` that's a
-    `PropertyDescriptor`
-
-    TODO: try https://stackoverflow.com/questions/54413434/type-hinting-with-descriptors
+    As properties are accessed over the HTTP API they need to be JSON serialisable
+    only return standard python types, or Pydantic BaseModels
     """
 
-    return PropertyDescriptor(
+    # Replace the function with a `Descriptor` that's a `ThingProperty`
+
+    # TODO: try https://stackoverflow.com/questions/54413434/type-hinting-with-descriptors
+
+    return ThingProperty(
         return_type(func),
         readonly=True,
         observable=False,
         getter=func,
     )
 
 
-def thing_setting(func: Callable) -> SettingDescriptor:
+def thing_setting(func: Callable) -> ThingSetting:
     """Mark a method of a Thing as a Setting.
 
-    A setting is a property that persists between runs
+    When creating a Setting you must always create a setter as it is used to load
+    from disk.
 
-    Replace the function with a `Descriptor` that's a
-    `SettingDescriptor`
-    """
+    A setting is a property that persists between runs.
+
+    As settings are accessed over the HTTP API and saved to disk they need to be
+    JSON serialisable only return standard python types, or Pydantic BaseModels.
 
-    return SettingDescriptor(
+    If the type is a pydantic BaseModel, then the setter must also be able to accept
+    the dictionary representation of this BaseModel as this is what will be used to
+    set the Setting when loading from disk on starting the server.
+    """
+    # Replace the function with a `Descriptor` that's a `ThingSetting`
+    return ThingSetting(
         return_type(func),
         readonly=True,
         observable=False,

src/labthings_fastapi/descriptors/__init__.py

@@ -1,5 +1,5 @@
 from .action import ActionDescriptor as ActionDescriptor
-from .property import PropertyDescriptor as PropertyDescriptor
-from .property import SettingDescriptor as SettingDescriptor
+from .property import ThingProperty as ThingProperty
+from .property import ThingSetting as ThingSetting
 from .endpoint import EndpointDescriptor as EndpointDescriptor
 from .endpoint import HTTPMethod as HTTPMethod

src/labthings_fastapi/descriptors/property.py

@@ -18,10 +18,10 @@
     from ..thing import Thing
 
 
-class PropertyDescriptor:
+class ThingProperty:
     """A property that can be accessed via the HTTP API
 
-    By default, a PropertyDescriptor is "dumb", i.e. it acts just like
+    By default, a ThingProperty is "dumb", i.e. it acts just like
     a normal variable.
     """
 
@@ -53,7 +53,7 @@ def __init__(
         self._setter = setter or getattr(self, "_setter", None)
         self._getter = getter or getattr(self, "_getter", None)
         # Try to generate a DataSchema, so that we can raise an error that's easy to
-        # link to the offending PropertyDescriptor
+        # link to the offending ThingProperty
         type_to_dataschema(self.model)
 
     def __set_name__(self, owner, name: str):
@@ -214,7 +214,7 @@ def getter(self, func: Callable) -> Self:
     def setter(self, func: Callable) -> Self:
         """Decorator to set the property's value
 
-        PropertyDescriptors are variabes - so they will return the value they hold
+        ThingPropertys are variabes - so they will return the value they hold
         when they are accessed. However, they can run code when they are set: this
         decorator sets a function as that code.
         """
@@ -223,7 +223,15 @@ def setter(self, func: Callable) -> Self:
         return self
 
 
-class SettingDescriptor(PropertyDescriptor):
+class ThingSetting(ThingProperty):
+    """A setting can be accessed via the HTTP API and is persistent between sessions
+
+    A ThingSetting is a ThingProperty with extra functionality for triggering
+    a Thing to save its settings, and for setting a property without emitting an event so
+    that the setting can be set from disk before the server is fully started.
+
+    The setting otherwise acts just like a normal variable.
+    """
     @property
     def persistent(self):
         return True

src/labthings_fastapi/example_things/__init__.py

@@ -6,7 +6,7 @@
 from typing import Optional, Annotated
 from labthings_fastapi.thing import Thing
 from labthings_fastapi.decorators import thing_action, thing_property
-from labthings_fastapi.descriptors import PropertyDescriptor
+from labthings_fastapi.descriptors import ThingProperty
 from pydantic import Field
 
 
@@ -73,11 +73,11 @@ def slowly_increase_counter(self, increments: int = 60, delay: float = 1):
             time.sleep(delay)
             self.increment_counter()
 
-    counter = PropertyDescriptor(
+    counter = ThingProperty(
         model=int, initial_value=0, readonly=True, description="A pointless counter"
     )
 
-    foo = PropertyDescriptor(
+    foo = ThingProperty(
         model=str,
         initial_value="Example",
         description="A pointless string for demo purposes.",

src/labthings_fastapi/thing.py

@@ -22,7 +22,7 @@
 
 from pydantic import BaseModel
 
-from .descriptors import PropertyDescriptor, ActionDescriptor
+from .descriptors import ThingProperty, ThingSetting, ActionDescriptor
 from .thing_description.model import ThingDescription, NoSecurityScheme
 from .utilities import class_attributes
 from .thing_description import validation
@@ -56,7 +56,7 @@ class Thing:
       code that will close down your hardware. It's equivalent to a `finally:` block.
     * Properties and Actions are defined using decorators: the `@thing_action` decorator
       declares a method to be an action, which will run when it's triggered, and the
-      `@thing_property` decorator (or `PropertyDescriptor` descriptor) does the same for
+      `@thing_property` decorator (or `ThingProperty` descriptor) does the same for
       a property. See the documentation on those functions for more detail.
     * `title` will be used in various places as the human-readable name of your Thing,
       so it makes sense to set this in a subclass.
@@ -131,7 +131,7 @@ def settings(self):
 
         self._settings = {}
         for name, attr in class_attributes(self):
-            if hasattr(attr, "property_affordance") and hasattr(attr, "persistent"):
+            if isinstance(attr, ThingSetting):
                 self._settings[name] = attr
         return self._settings
 
@@ -264,7 +264,7 @@ def thing_description_dict(
     def observe_property(self, property_name: str, stream: ObjectSendStream):
         """Register a stream to receive property change notifications"""
         prop = getattr(self.__class__, property_name)
-        if not isinstance(prop, PropertyDescriptor):
+        if not isinstance(prop, ThingProperty):
             raise KeyError(f"{property_name} is not a LabThings Property")
         prop._observers_set(self).add(stream)