First pass at splitting up ThingProperty

This commit swaps ThingProperty for two descriptor classes, FunctionalProperty (using getters/setters) and
DataProperty (variable-like). This preserves the two
useful behaviours out of the six (!) possible behaviours
implemented by the old ThingProperty.

I've also added a `property` function that provides a single interface to both: it may be used either as a
decorator, or as a field specifier.

This does not yet pass tests/type checking.

Author: rwb27

pyproject.toml

@@ -76,14 +76,15 @@ target-version = "py310"
 docstring-code-format = true
 
 [tool.ruff.lint]
+external = ["DOC401", "F824"]  # used via flake8/pydoclint
 select = ["E4", "E7", "E9", "F", "D", "DOC"]
 ignore = [
     "D203",  # incompatible with D204
     "D213",  # incompatible with D212
-    "DOC402",  # doesn't work with sphinx-style docstrings, use pydoclint
-    "DOC201",  # doesn't work with sphinx-style docstrings, use pydoclint
-    "DOC501",  # doesn't work with sphinx-style docstrings, use pydoclint
-    "DOC502",  # doesn't work with sphinx-style docstrings, use pydoclint
+    "DOC402",  # doesn't work with sphinx-style docstrings, use flake8/pydoclint
+    "DOC201",  # doesn't work with sphinx-style docstrings, use flake8/pydoclint
+    "DOC501",  # doesn't work with sphinx-style docstrings, use flake8/pydoclint
+    "DOC502",  # doesn't work with sphinx-style docstrings, use flake8/pydoclint
 ]
 preview = true
 
@@ -98,6 +99,8 @@ plugins = ["pydantic.mypy", "numpy.typing.mypy_plugin"]
 extend-ignore = [
   "DOC301",  # allow class + __init__ docstrings
   "D202",  # conflicts with ruff format
+  "F401",  # already implemented by ruff, which respects "import x as x"
+  "E501",  # leave this to ruff (line length), #noqa may exceed max line length.
 ]
 max-line-length = 88
 rst-roles = [

src/labthings_fastapi/__init__.py

@@ -20,7 +20,7 @@
 """
 
 from .thing import Thing
-from .descriptors import ThingProperty, ThingSetting
+from .thing_property import property, ThingSetting
 from .decorators import (
     thing_property,
     thing_setting,
@@ -42,7 +42,7 @@
 # re-export style, we may switch in the future.
 __all__ = [
     "Thing",
-    "ThingProperty",
+    "property",
     "ThingSetting",
     "thing_property",
     "thing_setting",

src/labthings_fastapi/base_descriptor.py

@@ -0,0 +1,173 @@
+"""A base class for descriptors in LabThings.
+
+:ref:`descriptors` are used to describe :ref:`wot_affordances` in LabThings-FastAPI.
+There is some behaviour common to most of these, and `.BaseDescriptor` centralises
+the code that implements it.
+"""
+
+from typing import overload, Generic, Self, TypeVar, TYPE_CHECKING
+
+from .utilities.introspection import get_summary
+
+if TYPE_CHECKING:
+    from .thing import Thing
+
+Value = TypeVar("Value")
+"""The value returned by the descriptor, when called on an instance."""
+
+
+class NameNotSetError(AttributeError):
+    """Descriptor name is not yet available.
+
+    This error is raised if the name of an affordance is accessed
+    before ``__set_name__`` has been called on the descriptor.
+    """
+
+
+class BaseDescriptor(Generic[Value]):
+    r"""A base class for descriptors in LabThings-FastAPI.
+
+    This class implements several behaviours common to descriptors in LabThings:
+
+    * The descriptor remembers the name it's assigned to in ``name``, for use in
+        :ref:`gen_docs`\ .
+    * When called as a class attribute, the descriptor returns itself, as done by
+        e.g. `property`.
+    """
+
+    def __init__(self):
+        """Initialise a BaseDescriptor."""
+        self._name: str | None = None
+        self._title: str | None = None
+        self._description: str | None = None
+        # We set the instance __doc__ to None so the descriptor class docstring
+        # doesn't get picked up by OpenAPI/Thing Description.
+        self.__doc__ = None
+
+    def __set_name__(self, owner: type[Thing], name: str) -> None:
+        r"""Take note of the name to which the descriptor is assigned.
+
+        This is called when the descriptor is assigned to an attribute of a class.
+        This function just remembers the name, so it can be used in
+        :ref:`gen_docs`\ .
+
+        :param owner: the `.Thing` subclass to which we are being attached.
+        :param name: the name to which we have been assigned.
+        """
+        # Remember the name to which we're assigned. Accessed by the read only
+        # property ``name``.
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        """The name of this descriptor.
+
+        When the descriptor is assigned to an attribute of a class, we
+        remember the name of the attribute. There will be some time in
+        between the descriptor being instantiated and the name being set.
+        If this is accessed before we know the name, we will raise an exception.
+
+        The ``name`` of :ref:`wot_affordances` is used in their URL and in
+        the :ref:`gen_docs` served by LabThings.
+
+        :raises NameNotSetError: if it is accessed before the descriptor
+            has been notified of its name.
+        """
+        if self._name is None:
+            raise NameNotSetError
+        return self._name
+
+    @property
+    def title(self) -> str:
+        """A human-readable title for the descriptor.
+
+        The :ref:`wot_td` requires a human-readable title for all
+        :ref:`wot_affordances` described. This property will generate a
+        suitable string from either the name or the docstring.
+
+        The title is either the first line of the docstring, or the name
+        of the descriptor. Note that, if there's no summary line in the
+        descriptor's instance docstring, or if ``__set__name__`` has not
+        yet been called (i.e. if this attribute is accessed before the
+        class on which the descriptor is defined has been fully set up),
+        the `.NameNotSetError` from ``self.name`` will propagate, i.e.
+        this property will either return a string or fail with an
+        exception.
+
+        Note also that, if the docstring for this descriptor is defined
+        on the class rather than passed in (via a getter function or
+        action function's docstring), it will also not be available until
+        after ``__set_name__`` has been called.
+        """
+        if not self._title:
+            # First, try to retrieve the first line of the docstring.
+            # This is the preferred option for the title.
+            self._title = get_summary(self)
+        if not self._title:
+            # If there's no docstring, or it doesn't have a summary line,
+            # use the name of the descriptor instead.
+            # Note that this will either succeed or raise an exception.
+            self._title = self.name
+        return self._title
+
+    @property
+    def description(self) -> str | None:
+        """A description of the descriptor for use in documentation.
+
+        This property will return the docstring describing the descriptor.
+        As the first line of the docstring (if present) is used as the
+        ``title`` in :ref:`gen_docs` it will be removed from this property.
+        """
+
+    # I have ignored D105 (missing docstrings) on the overloads - these should not
+    # exist on @overload definitions.
+    @overload
+    def __get__(self, obj: Thing, type: type | None = None) -> Value: ...  # noqa: D105
+
+    @overload
+    def __get__(self, type: type) -> Self: ...  # noqa: D105
+
+    def __get__(self, obj: Thing | None, type: type | None = None) -> Value | Self:
+        """Return the value or the descriptor, as per `property`.
+
+        If ``obj`` is ``None`` (i.e. the descriptor is accessed as a class attribute),
+        we return the descriptor, i.e. ``self``.
+
+        If ``obj`` is not ``None``, we return a value. To remove the need for this
+        boilerplate in every subclass, we will call ``__instance_get__`` to get the
+        value.
+
+        :param obj: the `.Thing` instance to which we are attached.
+        :param type: the `.Thing` subclass on which we are defined.
+
+        :return: the value of the descriptor returned from ``__instance_get__`` when
+            accessed on an instance, or the descriptor object if accessed on a class.
+        """
+        if obj is not None:
+            return self.instance_get(obj, type)
+        return self
+
+    def instance_get(self, obj: Thing) -> Value:
+        """Return the value of the descriptor.
+
+        This method is called from ``__get__`` if the descriptor is accessed as an
+        instance attribute. This means that ``obj`` is guaranteed to be present.
+
+        ``__get__`` may be called on either an instance or a class, and if it is
+        called on the class, the convention is that we should return the descriptor
+        object (i.e. ``self``), as done by `builtins.property`.
+
+        `.BaseDescriptor.__get__` takes care of this logic, so we need only consider
+        the case where we are called as an instance attribute. This simplifies type
+        annotations and removes the need for overload definitions in every subclass.
+
+        :param obj: is the `.Thing` instance on which this descriptor is being
+            accessed.
+        :return: the value of the descriptor (i.e. property value, or bound method).
+
+        :raises NotImplementedError: if it is not overridden.
+        """
+        raise NotImplementedError(
+            "__instance_get__ must be defined on BaseDescriptor subclasses. \n\n"
+            "See BaseDescriptor.__instance_get__ for details."
+        )