Docs tidy after dropping dependencies

dev-requirements.txt

@@ -10,20 +10,31 @@ anyio==4.9.0
     #   httpx
     #   starlette
     #   watchfiles
+apeye==1.4.1
+    # via sphinx-toolbox
+apeye-core==1.1.5
+    # via apeye
 astroid==3.3.11
     # via sphinx-autoapi
 attrs==25.3.0
     # via
     #   jsonschema
     #   referencing
+autodocsumm==0.2.14
+    # via sphinx-toolbox
 babel==2.17.0
     # via sphinx
+beautifulsoup4==4.14.2
+    # via sphinx-toolbox
+cachecontrol==0.14.3
+    # via sphinx-toolbox
 certifi==2025.7.14
     # via
     #   httpcore
     #   httpx
     #   requests
     #   sentry-sdk
+    #   sphinx-prompt
 charset-normalizer==3.4.2
     # via requests
 click==8.2.1
@@ -42,6 +53,10 @@ colorama==0.4.6
     #   uvicorn
 coverage==7.9.2
     # via pytest-cov
+cssutils==2.11.1
+    # via dict2css
+dict2css==0.3.0.post1
+    # via sphinx-toolbox
 dnspython==2.7.0
     # via email-validator
 docstring-parser-fork==0.0.12
@@ -50,7 +65,16 @@ docutils==0.21.2
     # via
     #   restructuredtext-lint
     #   sphinx
+    #   sphinx-prompt
     #   sphinx-rtd-theme
+    #   sphinx-tabs
+    #   sphinx-toolbox
+domdf-python-tools==3.10.0
+    # via
+    #   apeye
+    #   apeye-core
+    #   dict2css
+    #   sphinx-toolbox
 email-validator==2.2.0
     # via
     #   fastapi
@@ -65,6 +89,10 @@ fastapi-cli==0.0.8
     # via fastapi
 fastapi-cloud-cli==0.1.4
     # via fastapi-cli
+filelock==3.20.0
+    # via
+    #   cachecontrol
+    #   sphinx-toolbox
 flake8==7.3.0
     # via
     #   labthings-fastapi (pyproject.toml)
@@ -82,6 +110,8 @@ h11==0.16.0
     # via
     #   httpcore
     #   uvicorn
+html5lib==1.1
+    # via sphinx-toolbox
 httpcore==1.0.9
     # via httpx
 httptools==0.6.4
@@ -94,9 +124,11 @@ httpx==0.28.1
 idna==3.10
     # via
     #   anyio
+    #   apeye-core
     #   email-validator
     #   httpx
     #   requests
+    #   sphinx-prompt
 ifaddr==0.2.0
     # via zeroconf
 imagesize==1.4.1
@@ -110,22 +142,31 @@ jinja2==3.1.6
     #   fastapi
     #   sphinx
     #   sphinx-autoapi
+    #   sphinx-jinja2-compat
 jsonschema==4.24.1
     # via labthings-fastapi (pyproject.toml)
 jsonschema-specifications==2025.4.1
     # via jsonschema
 markdown-it-py==3.0.0
     # via rich
 markupsafe==3.0.2
-    # via jinja2
+    # via
+    #   jinja2
+    #   sphinx-jinja2-compat
 mccabe==0.7.0
     # via flake8
 mdurl==0.1.2
     # via markdown-it-py
+more-itertools==10.8.0
+    # via cssutils
+msgpack==1.1.2
+    # via cachecontrol
 mypy==1.17.0
     # via labthings-fastapi (pyproject.toml)
 mypy-extensions==1.1.0
     # via mypy
+natsort==8.4.0
+    # via domdf-python-tools
 numpy==2.2.6
     # via labthings-fastapi (pyproject.toml)
 orjson==3.11.0
@@ -138,6 +179,8 @@ pathspec==0.12.1
     # via mypy
 pillow==11.3.0
     # via labthings-fastapi (pyproject.toml)
+platformdirs==4.5.0
+    # via apeye
 pluggy==1.6.0
     # via
     #   pytest
@@ -167,6 +210,8 @@ pygments==2.19.2
     #   pytest
     #   rich
     #   sphinx
+    #   sphinx-prompt
+    #   sphinx-tabs
 pytest==8.4.1
     # via
     #   labthings-fastapi (pyproject.toml)
@@ -193,7 +238,10 @@ referencing==0.36.2
     #   jsonschema-specifications
     #   types-jsonschema
 requests==2.32.4
-    # via sphinx
+    # via
+    #   apeye
+    #   cachecontrol
+    #   sphinx
 restructuredtext-lint==1.4.0
     # via flake8-rst-docstrings
 rich==14.0.0
@@ -210,26 +258,49 @@ rpds-py==0.26.0
     # via
     #   jsonschema
     #   referencing
+ruamel-yaml==0.18.16
+    # via sphinx-toolbox
+ruamel-yaml-clib==0.2.14
+    # via ruamel-yaml
 ruff==0.12.3
     # via labthings-fastapi (pyproject.toml)
 sentry-sdk==2.33.0
     # via fastapi-cloud-cli
 shellingham==1.5.4
     # via typer
+six==1.17.0
+    # via html5lib
 sniffio==1.3.1
     # via anyio
 snowballstemmer==3.0.1
     # via sphinx
+soupsieve==2.8
+    # via beautifulsoup4
 sphinx==8.1.3
     # via
     #   labthings-fastapi (pyproject.toml)
+    #   autodocsumm
     #   sphinx-autoapi
+    #   sphinx-autodoc-typehints
+    #   sphinx-prompt
     #   sphinx-rtd-theme
+    #   sphinx-tabs
+    #   sphinx-toolbox
     #   sphinxcontrib-jquery
 sphinx-autoapi==3.6.0
     # via labthings-fastapi (pyproject.toml)
+sphinx-autodoc-typehints==3.0.1
+    # via sphinx-toolbox
+sphinx-jinja2-compat==0.4.1
+    # via sphinx-toolbox
+sphinx-prompt==1.9.0
+    # via sphinx-toolbox
 sphinx-rtd-theme==3.0.2
     # via labthings-fastapi (pyproject.toml)
+sphinx-tabs==3.4.5
+    # via sphinx-toolbox
+sphinx-toolbox==4.0.0
+    # via labthings-fastapi (pyproject.toml)
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0
@@ -246,6 +317,8 @@ sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 starlette==0.47.1
     # via fastapi
+tabulate==0.9.0
+    # via sphinx-toolbox
 tomli==2.2.1
     # via
     #   coverage
@@ -265,6 +338,8 @@ typing-extensions==4.14.1
     #   labthings-fastapi (pyproject.toml)
     #   anyio
     #   astroid
+    #   beautifulsoup4
+    #   domdf-python-tools
     #   exceptiongroup
     #   fastapi
     #   mypy
@@ -274,6 +349,7 @@ typing-extensions==4.14.1
     #   referencing
     #   rich
     #   rich-toolkit
+    #   sphinx-toolbox
     #   starlette
     #   typer
     #   typing-inspection
@@ -286,13 +362,16 @@ urllib3==2.5.0
     # via
     #   requests
     #   sentry-sdk
+    #   sphinx-prompt
 uvicorn==0.35.0
     # via
     #   fastapi
     #   fastapi-cli
     #   fastapi-cloud-cli
 watchfiles==1.1.0
     # via uvicorn
+webencodings==0.5.1
+    # via html5lib
 websockets==15.0.1
     # via uvicorn
 zeroconf==0.147.0

docs/source/actions.rst

@@ -5,10 +5,10 @@ Actions
 
 Actions are the way `.Thing` objects are instructed to do things. In Python
 terms, any method of a `.Thing` that we want to be able to call over HTTP
-should be decorated as an Action, using :deco:`.thing_action`.
+should be decorated as an Action, using `.thing_action`.
 
 This page gives an overview of how actions are implemented in LabThings-FastAPI.
-:ref:`wot_cc` includes a section on :ref:`wot_actions` that introduces the general concept.
+Our implementation should align with :ref:`wot_actions` as defined by the Web of Things standard.
 
 Running actions via HTTP
 ------------------------
@@ -58,6 +58,54 @@ The first is ``self`` (the first positional argument), which is always the
 supply resources needed by the action. Most often, this is a way of accessing
 other `.Things` on the same server.
 
+.. _action_logging:
+
+Logging from actions
+--------------------
+Action code should use `.Thing.logger` to log messages. This will be configured
+to handle messages on a per-invocation basis and make them available when the action
+is queried over HTTP.
+
+This may be used to display status updates to the user when an action takes
+a long time to run, or it may simply be a helpful debugging aid. 
+
+See :mod:`.logs` for details of how this is implemented.
+
+.. _action_cancellation:
+
+Cancelling actions
+------------------
+If an action could run for a long time, it is useful to be able to cancel it
+cleanly. LabThings makes provision for this by allowing actions to be cancelled
+using a ``DELETE`` HTTP request. In order to allow an action to be cancelled,
+you must give LabThings opportunities to interrupt it. This is most often done
+by replacing a `time.sleep()` statement with `.cancellable_sleep()` which
+is equivalent,  but will raise an exception if the action is cancelled.
+
+For more advanced options, see `.invocation_contexts` for detail.
+
+.. _invocation_context:
+
+Invocation contexts
+-------------------
+Cancelling actions and capturing their logs requires action code to use a
+specific logger and check for cancel events. This is done using `contextvars`
+such that the action code can use module-level symbols rather than needing
+to explicitly pass the logger and cancel hook as arguments to the action
+method.
+
+Usually, you don't need to consider this mechanism: simply use `.Thing.logger`
+or `.cancellable_sleep` as explained above. However, if you want to run actions
+outside of the server (for example, for testing purposes) or if you want to
+call one action from another action, but not share the cancellation signal
+or log, functions are provided in `.invocation_contexts` to manage this.
+
+If you start a new thread from an action, code running in that thread will
+not have an invocation ID set in a context variable. A subclass of
+`threading.Thread` is provided to do this, `.ThreadWithInvocationID`\ .
+This may be useful for test code, or if you wish to run actions in the
+background, with the option of cancelling them.
+
 Raising exceptions
 ------------------
 If an action raises an unhandled exception, the action will terminate with an Error

docs/source/concurrency.rst

@@ -11,7 +11,7 @@ In the case of properties, the HTTP response is only returned once the `.Thing`
 
 Many of the functions that handle HTTP requests are asynchronous, running in an :mod:`anyio` event loop. This enables many HTTP connections to be handled at once with good efficiency. The `anyio documentation`_ describes the functions that link between async and threaded code. When the LabThings server is started, we create an :class:`anyio.from_thread.BlockingPortal`, which allows threaded code to run code asynchronously in the event loop.
 
-An action can obtain the blocking portal using the `~labthings_fastapi.dependencies.blocking_portal.BlockingPortal` dependency, i.e. by declaring an argument of that type. This avoids referring to the blocking portal through a global variable, which could lead to confusion if there are multiple event loops, e.g. during testing.
+An action can run async code using its server interface. See `.ThingServerInterface.start_async_task_soon` for details.
 
 There are relatively few occasions when `.Thing` code will need to consider this explicitly: more usually the blocking portal will be obtained by a LabThings function, for example the `.MJPEGStream` class.
 
@@ -22,3 +22,11 @@ Calling Things from other Things
 
 When one `Thing` calls the actions or properties of another `.Thing`, either directly or via a `.DirectThingClient`, no new threads are spawned: the action or property is run in the same thread as the caller. This mirrors the behaviour of the `.ThingClient`, which blocks until the action or property is complete. See :doc:`using_things` for more details on how to call actions and properties of other Things.
 
+Invocations and concurrency
+---------------------------
+
+Each time an action is run ("invoked" in :ref:`wot_cc`), we create a new thread to run it. This thread has a context variable set, such that ``lt.cancellable_sleep`` and ``lt.get_invocation_logger`` are aware of which invocation is currently running. If an action spawns a new thread (e.g. using `threading.Thread`\ ), this new thread will not have an invocation ID, and consequently the two invocation-specific functions mentioned will not work.
+
+Usually, the best solution to this problem is to generate a new invocation ID for the thread. This means only the original action thread will receive cancellation events, and only the original action thread will log to the invocation logger. If the action is cancelled, you must cancel the background thread. This is the behaviour of `.ThreadWithInvocationID`\ .
+
+It is also possible to copy the current invocation ID to a new thread. This is often a bad idea, as it's ill-defined whether the exception will arise in the original thread or the new one if the invocation is cancelled. Logs from the two threads will also be interleaved. If it's desirable to log from the background thread, the invocation logger may safely be passed as an argument, rather than accessed via ``lt.get_invocation_logger``\ .

docs/source/conf.py

@@ -1,5 +1,6 @@
 import logging
 import labthings_fastapi
+import importlib.metadata
 
 # Configuration file for the Sphinx documentation builder.
 #
@@ -12,7 +13,7 @@
 project = "labthings-fastapi"
 copyright = "2024, Richard Bowman"
 author = "Richard Bowman"
-release = "0.0.10"
+release = importlib.metadata.version("labthings-fastapi")
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -23,6 +24,7 @@
     # "autodoc2",
     "autoapi.extension",
     "sphinx_rtd_theme",
+    "sphinx_toolbox.decorators",
 ]
 
 templates_path = ["_templates"]

docs/source/dependencies/dependencies.rst

@@ -3,11 +3,19 @@
 Dependencies
 ============
 
+.. warning::
+
+    The use of dependencies is now deprecated. See :ref:`thing_slots` and `.ThingServerInterface` for a more intuitive way to access that functionality.
+
 LabThings makes use of the powerful "dependency injection" mechanism in FastAPI. You can see the `FastAPI documentation`_ for more information. In brief, FastAPI dependencies are annotated types that instruct FastAPI to supply certain function arguments automatically. This removes the need to set up resources at the start of a function, and ensures everything the function needs is declared and typed clearly. The most common use for dependencies in LabThings is where an action needs to make use of another `.Thing` on the same `.ThingServer`.
 
 Inter-Thing dependencies
 ------------------------
 
+.. warning::
+
+    These dependencies are deprecated - see :ref:`thing_slots` instead.
+
 Simple actions depend only on their input parameters and the `.Thing` on which they are defined. However, it's quite common to need something else, for example accessing another `.Thing` instance on the same LabThings server. There are two important principles to bear in mind here:
 
 * Other `.Thing` instances should be accessed using a `.DirectThingClient` subclass if possible. This creates a wrapper object that should work like a `.ThingClient`, meaning your code should work either on the server or in a client script. This makes the code much easier to debug.