Docstring improvements in DirectThingClient

I've added an explicit reference for "using things from other things". This may
well want to be its own page in the future.

Author: rwb27

docs/source/using_things.rst

@@ -19,6 +19,8 @@ Dynamic class generation
 
 The object returned by :meth:`.ThingClient.from_url` is an instance of a dynamically-created subclass of :class:`.ThingClient`. Dynamically creating the class is needed because we don't know what the methods and properties should be until we have downloaded the Thing Description. However, this means most code autocompletion tools, type checkers, and linters will not work well with these classes. In the future, LabThings-FastAPI will generate custom client subclasses that can be shared in client modules, which should fix these problems (see below).
 
+.. _things_from_things:
+
 Using Things from other Things
 ------------------------------
 

src/labthings_fastapi/client/in_server.py

@@ -1,10 +1,15 @@
 """A mock client that uses a Thing directly.
 
-Currently this is not a subclass of ThingClient, that may need to change.
-It's a good idea to create a DirectThingClient at module level, so that type
-hints work.
+When `.Thing` objects interact on the server, it can be very useful to
+use an interface that is identical to the `.ThingClient` used to access
+the same `.Thing` remotely. This means that code can run either on the
+server or on a client, e.g. in a Jupyter notebook where it is much
+easier to debug. See things_from_things_ for more detail.
+
+Currently `.DirectThingClient` is not a subclass of `.ThingClient`,
+that may need to change. It's a good idea to create a
+`.DirectThingClient` at module level, so that type hints work.
 
-This module may get moved in the near future.
 
 """
 
@@ -24,17 +29,45 @@
 from fastapi import Request
 
 
+__all__ = ["DirectThingClient", "direct_thing_client_class"]
+
+
 class DirectThingClient:
+    """A wrapper for `.Thing` that is a work-a-like for `.ThingClient`.
+
+    This class is used to create a class that works like `.ThingClient`
+    but does not communicate over HTTP. Instead, it wraps a `.Thing` object
+    and calls its methods directly.
+
+    It is not yet 100% identical to `.ThingClient`, in particular `.ThingClient`
+    returns a lot of data directly as deserialised from JSON, while this class
+    generally returns `pydantic.BaseModel` instances, without serialisation.
+
+    `.DirectThingClient` is generally not used on its own, but is subclassed
+    (often dynamically) to add the actions and properties of a particular
+    `.Thing`.
+    """
+
     __globals__ = globals()  # "bake in" globals so dependency injection works
     thing_class: type[Thing]
+    """The class of the underlying `.Thing` we are wrapping."""
     thing_path: str
+    """The path to the Thing on the server. Relative to the server's base URL."""
 
     def __init__(self, request: Request, **dependencies: Mapping[str, Any]):
-        """Wrapper for a Thing that makes it work like a ThingClient
+        """Wrapper for a `.Thing` that makes it work like a `.ThingClient`.
+
+        This class is designed to be used as a FastAPI dependency, and will
+        retrieve a `.Thing` based on its ``thing_path`` attribute.
+        Finding the Thing by class may also be an option in the future.
 
-        This class is designed to be used as a FastAPI dependency, and will retrieve a
-        Thing based on its `thing_path` attribute. Finding the Thing by class may also
-        be an option in the future.
+        :param request: This is a FastAPI dependency to access the
+            `fastapi.Request` object, allowing access to various resources.
+        :param **dependencies**: Further arguments will be added
+            dynamically by subclasses, by duplicating this method and
+            manipulating its signature. Adding arguments with annotated
+            type hints instructs FastAPI to inject dependency arguments,
+            such as access to other `.Things`.
         """
         server = find_thing_server(request.app)
         self._wrapped_thing = server.things[self.thing_path]
@@ -50,10 +83,28 @@ def property_descriptor(
     writeable: bool = True,
     property_path: Optional[str] = None,
 ) -> PropertyClientDescriptor:
-    """Create a correctly-typed descriptor that gets and/or sets a property
+    """Create a correctly-typed descriptor that gets and/or sets a property.
 
-    This is copy-pasted from labthings_fastapi.client.__init__.property_descriptor
-    TODO: refactor this into a shared function.
+    .. todo::
+        This is copy-pasted from labthings_fastapi.client.__init__.property_descriptor
+        TODO: refactor this into a shared function.
+
+    Create a descriptor object that wraps a property. This is for use on
+    a `.DirectThingClient` subclass.
+
+    :param property_name: should be the name of the property (i.e. the
+        name it takes in the thing description, and also the name it is
+        assigned to in the class).
+    :param model: the Python ``type`` or a ``pydantic.BaseModel`` that
+        represents the datatype of the property.
+    :param description: text to use for a docstring.
+    :param readable: whether the property may be read (i.e. has ``__get__``).
+    :param writeable: whether the property may be written to.
+    :param property_path: the URL of the ``getproperty`` and ``setproperty``
+        HTTP endpoints. Currently these must both be the same. These are
+        relative to the ``base_url``, i.e. the URL of the Thing Description.
+
+    :return: a descriptor allowing access to the specified property.
     """
 
     class P(PropertyClientDescriptor):
@@ -90,9 +141,24 @@ def add_action(
     name: str,
     action: ActionDescriptor,
 ) -> None:
-    """Generates an action method and adds it to an attrs dict
+    """Generate an action method and adds it to an attrs dict.
 
     FastAPI Dependencies are appended to the `dependencies` list.
+    This list should later be converted to type hints on the class
+    initialiser, so that FastAPI supplies the dependencies when
+    the `.DirectThingClient` is initialised.
+
+    :param attrs: the attributes of a soon-to-be-created `.DirectThingClient`
+        subclass. This will be passed to `type()` to create the subclass.
+        We will add the action method to this dictionary.
+    :param dependencies: lists the dependency parameters that will be
+        injected by FastAPI as arguments to the class ``__init__``.
+        Any dependency parameters of the supplied ``action`` should be
+        added to this list.
+    :param name: the name of the action. Should be the name of the
+        attribute, i.e. we will set ``attrs[name]``, and also match
+        the ``name`` in the supplied action descriptor.
+    :param action: an `.ActionDescriptor` to be wrapped.
     """
 
     @wraps(action.func)
@@ -125,7 +191,15 @@ def action_method(self, **kwargs):
 def add_property(
     attrs: dict[str, Any], property_name: str, property: ThingProperty
 ) -> None:
-    """Add a property to a DirectThingClient subclass"""
+    """Add a property to a DirectThingClient subclass.
+
+    :param attrs: the attributes of a soon-to-be-created `.DirectThingClient`
+        subclass. This will be passed to `type()` to create the subclass.
+        We will add the property to this dictionary.
+    :param name: the name of the property. Should be the name of the
+        attribute, i.e. we will set ``attrs[name]``.
+    :param property: a `.PropertyDescriptor` to be wrapped.
+    """
     attrs[property_name] = property_descriptor(
         property_name,
         property.model,
@@ -139,10 +213,23 @@ def direct_thing_client_class(
     thing_class: type[Thing],
     thing_path: str,
     actions: Optional[list[str]] = None,
-):
-    """Create a DirectThingClient from a Thing class and a path
+) -> type[DirectThingClient]:
+    """Create a DirectThingClient from a Thing class and a path.
 
     This is a class, not an instance: it's designed to be a FastAPI dependency.
+
+    :param thing_class: The `.Thing` subclass that will be wrapped.
+    :param thing_path: The path where the `.Thing` is found on the server.
+    :param actions: An optional list giving a subset of actions that will be
+        accessed. If this is specified, it may reduce the number of FastAPI
+        dependencies we need.
+
+    :return: a subclass of `DirectThingClient` with attributes that match the
+        properties and actions of ``thing_class``. The ``__init__` method
+        will have annotations that instruct FastAPI to supply all the
+        dependencies needed by its actions.
+
+        This class may be used as a FastAPI dependency: see things_from_things_.
     """
 
     def init_proxy(self, request: Request, **dependencies: Mapping[str, Any]):