Fix links and RST formatting

There was a bad indent in the properties module level docstring, and a few imports that confused Sphinx when making cross-references.

I've moved an exception and tweaked the way Thing._thing_server_interface is declared to improve the docs: this should not change any code.

Author: rwb27

src/labthings_fastapi/actions/__init__.py

@@ -35,29 +35,22 @@
 from ..exceptions import (
     InvocationCancelledError,
     InvocationError,
+    NoBlobManagerError,
 )
 from ..outputs.blob import BlobIOContextDep, blobdata_to_url_ctx
-from ..invocation_contexts import (
-    CancelEvent,
-    get_cancel_event,
-    set_invocation_id,
-)
+from .. import invocation_contexts
 
 if TYPE_CHECKING:
     # We only need these imports for type hints, so this avoids circular imports.
     from ..descriptors import ActionDescriptor
     from ..thing import Thing
 
-ACTION_INVOCATIONS_PATH = "/action_invocations"
-"""The API route used to list `.Invocation` objects."""
 
+__all__ = ["ACTION_INVOCATIONS_PATH", "Invocation", "ActionManager"]
 
-class NoBlobManagerError(RuntimeError):
-    """Raised if an API route accesses Invocation outputs without a BlobIOContextDep.
 
-    Any access to an invocation output must have BlobIOContextDep as a dependency, as
-    the output may be a blob, and the blob needs this context to resolve its URL.
-    """
+ACTION_INVOCATIONS_PATH = "/action_invocations"
+"""The API route used to list `.Invocation` objects."""
 
 
 class Invocation(Thread):
@@ -197,9 +190,9 @@ def thing(self) -> Thing:
         return thing
 
     @property
-    def cancel_hook(self) -> CancelEvent:
+    def cancel_hook(self) -> invocation_contexts.CancelEvent:
         """The cancel event associated with this Invocation."""
-        return get_cancel_event(self.id)
+        return invocation_contexts.get_cancel_event(self.id)
 
     def cancel(self) -> None:
         """Cancel the task by requesting the code to stop.
@@ -278,7 +271,7 @@ def run(self) -> None:
         logger = self.thing.logger
         # The line below saves records matching our ID to ``self._log``
         add_thing_log_destination(self.id, self._log)
-        with set_invocation_id(self.id):
+        with invocation_contexts.set_invocation_id(self.id):
             try:
                 action.emit_changed_event(self.thing, self._status.value)
 

src/labthings_fastapi/decorators/__init__.py

@@ -25,9 +25,9 @@
 ----------
 
 As with Actions, Properties can be declared by decorating either a function, or
-an attribute, with :deco:`.thing_property`. You can use the decorator either on
+an attribute, with :deco:`.property`. You can use the decorator either on
 a function (in which case that
-function acts as the "getter" just like with Python's :deco`property` decorator).
+function acts as the "getter" just like with Python's :deco:`property` decorator).
 
 Events
 ------

src/labthings_fastapi/exceptions.py

@@ -137,3 +137,11 @@ class LogConfigurationError(RuntimeError):
     certain handlers and filters to be set up. This exception is raised if they
     cannot be added, or if they are not present when they are needed.
     """
+
+
+class NoBlobManagerError(RuntimeError):
+    """Raised if an API route accesses Invocation outputs without a BlobIOContextDep.
+
+    Any access to an invocation output must have BlobIOContextDep as a dependency, as
+    the output may be a blob, and the blob needs this context to resolve its URL.
+    """

src/labthings_fastapi/properties.py

@@ -11,6 +11,7 @@
 
     import labthings_fastapi as lt
 
+
     class Counter(lt.Thing):
         "A counter that knows what's remaining."
 
@@ -29,19 +30,19 @@ def remaining(self) -> int:
         def remaining(self, value: int) -> None:
             self.target = self.count + value
 
-    The first two properties are simple variables: they may be read and assigned
-    to, and will behave just like a regular variable. Their syntax is similar to
-    `dataclasses` or `pydantic` in that `.property` is used as a "field specifier"
-    to set options like the default value, and the type annotation is on the
-    class attribute. Documentation is in strings immediately following the
-    properties, which is understood by most automatic documentation tools.
+The first two properties are simple variables: they may be read and assigned
+to, and will behave just like a regular variable. Their syntax is similar to
+`dataclasses` or `pydantic` in that `.property` is used as a "field specifier"
+to set options like the default value, and the type annotation is on the
+class attribute. Documentation is in strings immediately following the
+properties, which is understood by most automatic documentation tools.
 
-    ``remaining`` is defined using a "getter" function, meaning this code will
-    be run each time ``counter.remaining`` is accessed. Its type will be the
-    return type of the function, and its docstring will come from the function
-    too. Setters with only a getter are read-only.
+``remaining`` is defined using a "getter" function, meaning this code will
+be run each time ``counter.remaining`` is accessed. Its type will be the
+return type of the function, and its docstring will come from the function
+too. Setters with only a getter are read-only.
 
-    Adding a "setter" to properties is optional, and makes them read-write.
+Adding a "setter" to properties is optional, and makes them read-write.
 """
 
 from __future__ import annotations
@@ -217,7 +218,7 @@ def property(
 
     This function may be used to define :ref:`wot_properties` in
     two ways, as either a decorator or a field specifier. See the
-    examples in the :mod:`.thing_property` documentation.
+    examples in the :mod:`.property` documentation.
 
     Properties should always have a type annotation. This type annotation
     will be used in automatic documentation and also to serialise the value

src/labthings_fastapi/server/__init__.py

@@ -36,6 +36,8 @@
 # `_thing_servers` is used as a global from `ThingServer.__init__`
 from ..outputs.blob import BlobDataManager
 
+__all__ = ["ThingServer"]
+
 
 ThingSubclass = TypeVar("ThingSubclass", bound=Thing)
 

src/labthings_fastapi/thing.py

@@ -79,6 +79,9 @@ class Thing:
     title: str
     """A human-readable description of the Thing"""
 
+    _thing_server_interface: ThingServerInterface
+    """Provide access to features of the server that this `.Thing` is attached to."""
+
     def __init__(self, thing_server_interface: ThingServerInterface) -> None:
         """Initialise a Thing.