Documentation on Thing, and added a link to the TD model.

Author: rwb27

NOTES.md

@@ -69,6 +69,14 @@ switched to using `pydoclint` directly, and configured it in `pyproject.toml`. I
   - `introspection`:
     - There's a confusing TODO about path parameters in `fastapi_dependency_params`
     - There's a ValueError that might want subclassing in `input_model_from_signature`.
+  - `exceptions` will need to hoover up more exceptions. Do we define them here? probably yes...
+* `notifications` is empty - need to consolidate code from property/action/websocket.
+* `thing`:
+  - consolidate settings into an object?
+  - default `thing_state` does cacheing but this isn't really documented. Remove?
+  - thing_description should consolidate `path` and `base_url`. In fact, if we set `base_url` to be the path
+    to the TD, we can make everything else static.
+* General: there are a lot of class attributes/annotations that should maybe be in `__init__`. We need to pick a convention and stick to it, I have often defined class attrs next to the function(s) that use them, but that might be bad style?
 
 
 

docs/source/lt_core_concepts.rst

@@ -1,3 +1,5 @@
+.. _labthings_cc
+
 LabThings Core Concepts
 =======================
 

docs/source/wot_core_concepts.rst

@@ -14,7 +14,7 @@ A `Thing` represents a piece of hardware or software. It could be a whole instru
 
 `labthings-fastapi` automatically generates a `Thing Description`_ to describe each `Thing`. Each function offered by the `Thing` is either a Property, Action, or Event. These are termed "interaction affordances" in WoT_ terminology.
 
-.. _wot_properties
+.. _wot_properties:
 
 Properties
 ----------
@@ -54,4 +54,11 @@ Thing Description documents are higher-level than OpenAPI_ and focus on the capa
 
 .. _WoT: https://www.w3.org/WoT/
 .. _Thing Description: https://www.w3.org/TR/wot-thing-description/
-.. _OpenAPI: https://www.openapis.org/
+.. _OpenAPI: https://www.openapis.org/
+
+.. _wot_affordances:
+
+Interaction Affordances
+-----------------------
+
+The Web of Things standard often talks about Affordances. This is the collective term for _wot_properties, _wot_actions, and _wot_events.

src/labthings_fastapi/exceptions.py

@@ -1,10 +1,10 @@
-"""A submodule for custom LabThings-FastAPI Exceptions"""
+"""A submodule for custom LabThings-FastAPI Exceptions."""
 
 from .dependencies.invocation import InvocationCancelledError
 
 
 class NotConnectedToServerError(RuntimeError):
-    """The Thing is not connected to a server
+    """The Thing is not connected to a server.
 
     This exception is called if a ThingAction is called or
     is a ThingProperty is updated on a Thing that is not

src/labthings_fastapi/notifications.py

@@ -1,5 +1,4 @@
-"""
-Handle notification of events, property, and action status changes
+"""Handle notification of events, property, and action status changes.
 
 There are several kinds of "event" in the WoT vocabulary, not all of which
 are called Event, which is why this module is called `notifications`.
@@ -20,4 +19,6 @@
 
 
 class Listener:
+    """A placeholder class for objects that listen for notifications."""
+
     pass

src/labthings_fastapi/thing.py

@@ -1,14 +1,12 @@
-"""
-The `Thing` class enables most of the functionality of this library,
-and is the way in to most of its features. In the future, we might
-support a stub version of the class in a separate package, so
-that instrument control libraries can be LabThings compatible
-without a hard dependency on LabThings. But that is something we
-will do in the future...
+"""A class to represent hardware or software Things.
+
+The `.Thing` class enables most of the functionality of this library,
+and is the way in to most of its features. See wot_cc_ and labthings_cc_
+for more.
 """
 
 from __future__ import annotations
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Any, Optional, Self
 from collections.abc import Mapping
 import logging
 import os
@@ -44,67 +42,85 @@ class Thing:
     a particular function - it will correspond to a path on the server, and a Thing
     Description document.
 
-    ## Subclassing Notes
+    Subclassing Notes
+    -----------------
 
-    * `__init__`: You should accept any arguments you need to configure the Thing
-      in `__init__`. Don't initialise any hardware at this time, as your Thing may
+    * ``__init__``: You should accept any arguments you need to configure the Thing
+      in ``__init__``. Don't initialise any hardware at this time, as your Thing may
       be instantiated quite early, or even at import time.
-    * `__enter__(self)` and `__exit__(self, exc_t, exc_v, exc_tb)` are where you
+    * ``__enter__(self)`` and ``__exit__(self, exc_t, exc_v, exc_tb)`` are where you
       should start and stop communications with the hardware. This is Python's standard
-      "context manager" protocol. The arguments of `__exit__` will be `None` unless
+      "context manager" protocol. The arguments of ``__exit__`` will be ``None`` unless
       an exception has occurred. You should be safe to ignore them, and just include
-      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 `ThingProperty` descriptor) does the same for
-      a property. See the documentation on those functions for more detail.
+      code that will close down your hardware. It's equivalent to a ``finally`:` block.
+    * Properties and Actions are defined using decorators: the :deco:`.thing_action`
+      decorator declares a method to be an action, which will run when it's triggered,
+      and the :deco:`.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.
 
-    There are various LabThings methods that you should avoid overriding unless you know
-    what you are doing: anything not mentioned above that's defined in `Thing` is
-    probably best left along. They may in time be collected together into a single
+    There are various LabThings methods that you should avoid overriding unless you
+    know what you are doing: anything not mentioned above that's defined in `Thing` is
+    probably best left alone. They may in time be collected together into a single
     object to avoid namespace clashes.
     """
 
     title: str
+    """A human-readable description of the Thing"""
     _labthings_blocking_portal: Optional[BlockingPortal] = None
+    """See concurrency_ for why blocking portal is needed."""
     path: Optional[str]
+    """The path at which the `.Thing` is exposed over HTTP."""
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> Self:
         """Context management is used to set up/close the thing.
 
         As things (currently) do everything with threaded code, we define
-        async __aenter__ and __aexit__ wrappers to call the synchronous
+        async ``__aenter__`` and ``__aexit__`` wrappers to call the synchronous
         code, if it exists.
+
+        :return: this object.
         """
         if hasattr(self, "__enter__"):
             return await run_sync(self.__enter__)
         else:
             return self
 
-    async def __aexit__(self, exc_t, exc_v, exc_tb):
+    async def __aexit__(
+        self, exc_t: type[Exception] | None, exc_v: Exception | None, exc_tb: Any
+    ) -> None:
         """Wrap context management functions, if they exist.
 
-        See __aenter__ docs for more details.
+        See ``__aenter__`` for more details.
+
+        :param exc_t: The type of the exception, or ``None``.
+        :param exc_v: The exception that occurred, or ``None``.
+        :param exc_tb: The traceback for the exception, or ``None``.
         """
         if hasattr(self, "__exit__"):
-            return await run_sync(self.__exit__, exc_t, exc_v, exc_tb)
+            await run_sync(self.__exit__, exc_t, exc_v, exc_tb)
 
     def attach_to_server(
         self, server: ThingServer, path: str, setting_storage_path: str
-    ):
-        """Attatch this thing to the server.
+    ) -> None:
+        """Attach this thing to the server.
 
         Things need to be attached to a server before use to function correctly.
 
-        :param server: The server to attach this Thing to
-        :param settings_storage_path: The path on disk to save the any Thing Settings
+        :param server: The server to attach this Thing to.
+        :param path: The root URL for the Thing.
+        :param setting_storage_path: The path on disk to save the any Thing Settings
         to. This should be the path to a json file. If it does not exist it will be
         created.
 
-        Wc3 Web Of Things explanation:
-        This will add HTTP handlers to an app for all Interaction Affordances
+        Attaching the `.Thing` to a `.ThingServer` allows the `.Thing` to start
+        actions, load its settings from the correct place, and create HTTP endpoints
+        to allow it to be accessed from the HTTP API.
+
+        We create HTTP endpoints for all wot_affordances_ on the `.Thing`, as well
+        as any `.EndpointDescriptor` descriptors.
         """
         self.path = path
         self.action_manager: ActionManager = server.action_manager
@@ -139,7 +155,7 @@ async def websocket(ws: WebSocket):
 
     @property
     def _settings(self) -> Optional[dict[str, ThingSetting]]:
-        """A private property that returns a dict of all settings for this Thing
+        """A private property that returns a dict of all settings for this Thing.
 
         Each dict key is the name of the setting, the corresponding value is the
         ThingSetting class (a descriptor). This can be used to directly get the
@@ -159,11 +175,31 @@ def _settings(self) -> Optional[dict[str, ThingSetting]]:
 
     @property
     def setting_storage_path(self) -> Optional[str]:
-        """The storage path for settings. This is set as the Thing is added to a server"""
+        """The storage path for settings.
+
+        .. note::
+
+            This is set in `.Thing.attach_to_server`. It is ``None`` during the
+            ``__init__`` method, so it is best to avoid using settings until the
+            `.Thing` is set up in ``__enter__``.
+        """
         return self._setting_storage_path
 
-    def load_settings(self, setting_storage_path):
-        """Load settings from json. This is run when the Thing is added to a server"""
+    def load_settings(self, setting_storage_path: str) -> None:
+        """Load settings from json.
+
+        Read the JSON file and use it to populate settings.
+
+        .. note::
+            Settings are loaded when the Thing is added to a server, so they will
+            not be available while the ``__init__`` method is run.
+
+            Note that no notifications will be triggered when the settings are set,
+            so if action is needed (e.g. updating hardware with the loaded settings)
+            it should be taken in ``__enter__``.
+
+        :param setting_storage_path: The path where the settings should be stored.
+        """
         # Ensure that the settings path isn't set during loading or saving will be triggered
         self._setting_storage_path = None
         thing_name = type(self).__name__
@@ -185,7 +221,11 @@ def load_settings(self, setting_storage_path):
         self._setting_storage_path = setting_storage_path
 
     def save_settings(self):
-        """Save settings to JSON. This is called whenever a setting is updated"""
+        """Save settings to JSON.
+
+        This is called whenever a setting is updated. All settings are written to
+        the settings file every time.
+        """
         if self._settings is not None:
             setting_dict = {}
             for name in self._settings.keys():
@@ -202,7 +242,7 @@ def save_settings(self):
 
     @property
     def thing_state(self) -> Mapping:
-        """Return a dictionary summarising our current state
+        """Return a dictionary summarising our current state.
 
         This is intended to be an easy way to collect metadata from a Thing that
         summarises its state. It might be used, for example, to record metadata
@@ -219,8 +259,8 @@ def thing_state(self) -> Mapping:
             self._labthings_thing_state = {}
         return self._labthings_thing_state
 
-    def validate_thing_description(self):
-        """Raise an exception if the thing description is not valid"""
+    def validate_thing_description(self) -> None:
+        """Raise an exception if the thing description is not valid."""
         td = self.thing_description_dict()
         return validation.validate_thing_description(td)
 
@@ -231,12 +271,17 @@ def validate_thing_description(self):
     def thing_description(
         self, path: Optional[str] = None, base: Optional[str] = None
     ) -> ThingDescription:
-        """A w3c Thing Description representing this thing
+        """Generate a w3c Thing Description representing this thing.
 
         The w3c Web of Things working group defined a standard representation
         of a Thing, which provides a high-level description of the actions,
         properties, and events that it exposes. This endpoint delivers a JSON
-        representation of the Thing Description for this Thing.
+        representation of the wot_td_ for this Thing.
+
+        :param path: the URL pointing to this Thing.
+        :param base: the base URL for all URLs in the thing description.
+
+        :return: a Thing Description.
         """
         path = path or getattr(self, "path", "{base_uri}")
         if (
@@ -270,26 +315,41 @@ def thing_description_dict(
         path: Optional[str] = None,
         base: Optional[str] = None,
     ) -> dict:
-        """A w3c Thing Description representing this thing, as a simple dict
+        r"""Describe this Thing with a Thing Description as a simple dict.
 
-        The w3c Web of Things working group defined a standard representation
-        of a Thing, which provides a high-level description of the actions,
-        properties, and events that it exposes. This endpoint delivers a JSON
-        representation of the Thing Description for this Thing.
+        See `.Thing.thing_description`\ . This function converts the
+        return value of that function into a simple dictionary.
+
+        :param path: the URL pointing to this Thing.
+        :param base: the base URL for all URLs in the thing description.
+
+        :return: a Thing Description.
         """
         td: ThingDescription = self.thing_description(path=path, base=base)
         td_dict: dict = td.model_dump(exclude_none=True, by_alias=True)
         return jsonable_encoder(td_dict)
 
-    def observe_property(self, property_name: str, stream: ObjectSendStream):
-        """Register a stream to receive property change notifications"""
+    def observe_property(self, property_name: str, stream: ObjectSendStream) -> None:
+        """Register a stream to receive property change notifications.
+
+        :param property_name: the property to register for.
+        :param stream: the stream used to send events.
+
+        :raises KeyError: if the requested name is not defined on this Thing.
+        """
         prop = getattr(self.__class__, property_name)
         if not isinstance(prop, ThingProperty):
             raise KeyError(f"{property_name} is not a LabThings Property")
         prop._observers_set(self).add(stream)
 
     def observe_action(self, action_name: str, stream: ObjectSendStream):
-        """Register a stream to receive action status change notifications"""
+        """Register a stream to receive action status change notifications.
+
+        :param action_name: the action to register for.
+        :param stream: the stream used to send events.
+
+        :raises KeyError: if the requested name is not defined on this Thing.
+        """
         action = getattr(self.__class__, action_name)
         if not isinstance(action, ActionDescriptor):
             raise KeyError(f"{action_name} is not an LabThings Action")

src/labthings_fastapi/thing_description/_model.py

@@ -2,8 +2,10 @@
 
 wot_td_ defines a schema for describing Things, using JSONSchema-like syntax
 for data types. This file contains pydantic models that describe that
-schema. For the meaning of the various objects, please refer to the schema
-definition within the W3C standard.
+schema. For the meaning of the various objects, please refer to the
+td_schema_definition_ within the W3C standard.
+
+.. _td_schema_definition: https://www.w3.org/TR/wot-thing-description11/
 
 This file was automatically generated, but has been customised to improve the
 types and simplify/combine objects.

src/labthings_fastapi/thing_description/validation.py

@@ -4,6 +4,8 @@
 validation applied every time one is created. However, this module allows
 the generated JSON document to be formally validated against the schema
 in the W3C specification, as an additional check.
+
+See wot_td_ for a link to the specification in human-readable format.
 """
 
 from importlib.resources import files