Create a top-level summary for the API docs, referenced as lt.* in the rest of the documentation.

Author: rwb27

docs/source/actions.rst

@@ -3,9 +3,9 @@
 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 `.action`.
+Actions are the way `~lt.Thing` objects are instructed to do things. In Python
+terms, any method of a `~lt.Thing` that we want to be able to call over HTTP
+should be decorated as an Action, using `lt.action`.
 
 This page gives an overview of how actions are implemented in LabThings-FastAPI.
 Our implementation should align with :ref:`wot_actions` as defined by the Web of Things standard.
@@ -19,7 +19,7 @@ invokes an action will return almost immediately with a ``201`` code, and a
 JSON payload that describes the invocation as an `.InvocationModel`. This includes
 a link ``href`` that can be polled to check the status of the invocation.
 
-The HTTP implementation of `.ThingClient` first makes a ``POST`` request to
+The HTTP implementation of `~lt.ThingClient` first makes a ``POST`` request to
 invoke the action, then polls the invocation using the ``href`` supplied.
 Once the action has finished (i.e. its status is ``completed``, ``error``, or
 ``cancelled``), its output (the return value) is retrieved and used as the
@@ -38,14 +38,14 @@ where Invocation-related HTTP endpoints are handled, including listing all the
 Running actions from other actions
 ----------------------------------
 
-If code running in a `.Thing` runs methods belonging either to that `.Thing`
-or to another `.Thing` on the same server, no new thread is created: the
+If code running in a `~lt.Thing` runs methods belonging either to that `~lt.Thing`
+or to another `~lt.Thing` on the same server, no new thread is created: the
 called action runs in the same thread as the calling action, just like any
 other Python code.
 
 Action inputs and outputs
 -------------------------
-The code that implements an action is a method of a `.Thing`, meaning it is
+The code that implements an action is a method of a `~lt.Thing`, meaning it is
 a function. The input parameters are the function's arguments, and the output
 parameter is the function's return value. Type hints on both arguments and
 return value are used to document the action in the OpenAPI description and
@@ -58,7 +58,7 @@ Python construct giving access to the object on which the action is defined.
 
 Logging from actions
 --------------------
-Action code should use `.Thing.logger` to log messages. This will be configured
+Action code should use `~lt.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.
 
@@ -75,7 +75,7 @@ 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
+by replacing a `time.sleep()` statement with `lt.cancellable_sleep()` which
 is equivalent,  but will raise an exception if the action is cancelled.
 
 For more advanced options, see `.invocation_contexts` for detail.
@@ -90,15 +90,15 @@ 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
+Usually, you don't need to consider this mechanism: simply use `~lt.Thing.logger`
+or `~lt.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`\ .
+`threading.Thread` is provided to do this, `~lt.ThreadWithInvocationID`\ .
 This may be useful for test code, or if you wish to run actions in the
 background, with the option of cancelling them.
 

docs/source/concurrency.rst

@@ -5,28 +5,28 @@ Concurrency in LabThings-FastAPI
 
 One of the major challenges when controlling hardware, particularly from web frameworks, is concurrency. Most web frameworks assume resources (database connections, object storage, etc.) may be instantiated multiple times, and often initialise or destroy objects as required. In contrast, hardware can usually only be controlled from one process, and usually is initialised and shut down only once.
 
-LabThings-FastAPI instantiates each :class:`.Thing` only once, and runs all code in a thread. More specifically, each time an action is invoked via HTTP, a new thread is created to run the action. Similarly, each time a property is read or written, a new thread is created to run the property method. This means that :class:`.Thing` code should protect important variables or resources using locks from the `threading` module, and need not worry about writing asynchronous code.
+LabThings-FastAPI instantiates each :class:`~lt.Thing` only once, and runs all code in a thread. More specifically, each time an action is invoked via HTTP, a new thread is created to run the action. Similarly, each time a property is read or written, a new thread is created to run the property method. This means that :class:`~lt.Thing` code should protect important variables or resources using locks from the `threading` module, and need not worry about writing asynchronous code.
 
-In the case of properties, the HTTP response is only returned once the `.Thing` code is complete. Actions currently return a response immediately, and must be polled to determine when they have completed. This behaviour may change in the future, most likely with the introduction of a timeout to allow the client to choose between waiting for a response or polling.
+In the case of properties, the HTTP response is only returned once the `~lt.Thing` code is complete. Actions currently return a response immediately, and must be polled to determine when they have completed. This behaviour may change in the future, most likely with the introduction of a timeout to allow the client to choose between waiting for a response or polling.
 
 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 run async code using its server interface. See `.ThingServerInterface.start_async_task_soon` for details.
+An action can run async code using its server interface. See `~lt.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.
+There are relatively few occasions when `~lt.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.
 
 .. _`anyio documentation`: https://anyio.readthedocs.io/en/stable/threads.html
 
 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.
+When one `Thing` calls the actions or properties of another `~lt.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 `~lt.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`\ .
+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 `~lt.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 inspect
 import logging
-import labthings_fastapi
+import labthings_fastapi as lt
 import importlib.metadata
 
 # Configuration file for the Sphinx documentation builder.
@@ -20,6 +21,7 @@
 
 extensions = [
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autodoc",
     # "sphinx.ext.napoleon",
     # "autodoc2",
     "autoapi.extension",
@@ -66,10 +68,7 @@
 skipper_log.addHandler(logging.FileHandler("./skipper.log", mode="w"))
 skipper_log.setLevel(logging.DEBUG)
 
-convenience_modules = {
-    "labthings_fastapi": labthings_fastapi.__all__,
-}
-canonical_fq_names = [
+canonical_fq_names = {
     "labthings_fastapi.descriptors.action.ActionDescriptor",
     "labthings_fastapi.outputs.blob.BlobDataManager",
     "labthings_fastapi.invocations.InvocationModel",
@@ -79,7 +78,16 @@
     "labthings_fastapi.actions.ActionManager",
     "labthings_fastapi.descriptors.endpoint.EndpointDescriptor",
     "labthings_fastapi.utilities.introspection.EmptyObject",
-]
+}
+
+# Everything in `labthings_fastapi` is documented elsewhere, so we
+# add all of those fq names to the list.
+top_level_objects = [getattr(lt, name) for name in lt.__all__]
+canonical_fq_names.update(
+    f"{obj.__module__}.{obj.__qualname__}"
+    for obj in top_level_objects
+    if not inspect.ismodule(obj)
+)
 
 
 def unqual(name):
@@ -90,8 +98,6 @@ def unqual(name):
 
 canonical_names = {unqual(n): n for n in canonical_fq_names}
 
-skipper_log.info("Convenience modules: %s.", convenience_modules)
-
 
 def skip_public_api(app, what, name: str, obj, skip, options):
     """Skip documenting members that are re-exported from the public API."""
@@ -100,10 +106,6 @@ def skip_public_api(app, what, name: str, obj, skip, options):
     if unqual in canonical_names and name != canonical_names[unqual]:
         skip = True
         return skip
-    for conv, all in convenience_modules.items():
-        if unqual in all and name != f"{conv}.{unqual}":
-            skipper_log.warning(f"skipping {name}")
-            skip = True
     return skip
 
 

docs/source/developer_notes/descriptors.rst

@@ -3,11 +3,11 @@
 Descriptors
 ===========
 
-Descriptors are a way to intercept attribute access on an object, and they are used extensively by LabThings to add functionality to `.Thing` instances, while continuing to look like normal Python objects.
+Descriptors are a way to intercept attribute access on an object, and they are used extensively by LabThings to add functionality to `~lt.Thing` instances, while continuing to look like normal Python objects.
 
 By default, attributes of an object are just variables - so an object called ``foo`` might have an attribute called ``bar``, and you may read its value with ``foo.bar``, write its value with ``foo.bar = "baz"``, and delete the attribute with ``del foo.bar``. If ``foo`` is a descriptor, Python will call the ``__get__`` method of that descriptor when it's read and the ``__set__`` method when it's written to. You have quite probably used a descriptor already, because the built-in `~builtins.property` creates a descriptor object: that's what runs your getter method when the property is accessed. The descriptor protocol is described with plenty of examples in the `Descriptor Guide`_ in the Python documentation.
 
-In LabThings-FastAPI, descriptors are used to implement :ref:`actions` and :ref:`properties` on `.Thing` subclasses. The intention is that these will function like standard Python methods and properties, but will also be available over HTTP, along with :ref:`gen_docs`.
+In LabThings-FastAPI, descriptors are used to implement :ref:`actions` and :ref:`properties` on `~lt.Thing` subclasses. The intention is that these will function like standard Python methods and properties, but will also be available over HTTP, along with :ref:`gen_docs`.
 
 .. _field_typing:
 
@@ -22,7 +22,7 @@ Field typing
         my_property: int = lt.property(default=0)
         """An integer property."""
 
-This makes it clear to anyone using ``MyThing`` that ``my_property`` is an integer, and should be picked up by most type checking/autocompletion tools. However, because the annotation is attached to the *class* and not passed to the underlying `.DataProperty` descriptor, we need to use the descriptor protocol to figure it out.
+This makes it clear to anyone using ``MyThing`` that ``my_property`` is an integer, and should be picked up by most type checking/autocompletion tools. However, because the annotation is attached to the *class* and not passed to the underlying `~lt.DataProperty` descriptor, we need to use the descriptor protocol to figure it out.
 
 Field typing in LabThings is implemented by `.FieldTypedBaseDescriptor` and there are docstrings on all of the relevant "magic" methods explaining what each one does. Below, there is a brief overview of how these fit together.
 
@@ -39,7 +39,7 @@ Descriptor implementation
 There are a few useful notes that relate to many of the descriptors in LabThings-FastAPI:
 
 * Descriptor objects **may have more than one owner**. As a rule, a descriptor object
-    (e.g. an instance of `.DataProperty`) is assigned to an attribute of one `.Thing` subclass. There may, however, be multiple *instances* of that class, so it is not safe to assume that the descriptor object corresponds to only one `.Thing`. This is why the `.Thing` is passed to the ``__get__`` method: we should ensure that any values being remembered are keyed to the owning `.Thing` and are not simply stored in the descriptor. Usually, this is done using `.WeakKeyDictionary` objects, which allow us to look up values based on the `.Thing`, without interfering with garbage collection.
+    (e.g. an instance of `~lt.DataProperty`) is assigned to an attribute of one `~lt.Thing` subclass. There may, however, be multiple *instances* of that class, so it is not safe to assume that the descriptor object corresponds to only one `~lt.Thing`. This is why the `~lt.Thing` is passed to the ``__get__`` method: we should ensure that any values being remembered are keyed to the owning `~lt.Thing` and are not simply stored in the descriptor. Usually, this is done using `.WeakKeyDictionary` objects, which allow us to look up values based on the `~lt.Thing`, without interfering with garbage collection.
 
     The example below shows how this can go wrong.
 

docs/source/examples.rst

@@ -1,9 +1,9 @@
 Examples
 ========
 
-For a simple example `.Thing` and instructions on how to serve it, see the :ref:`tutorial`\ .
+For a simple example `~lt.Thing` and instructions on how to serve it, see the :ref:`tutorial`\ .
 
-For more complex examples, there is a useful collection of `.Thing` subclasses implemented as part of the `OpenFlexure Microscope`_ in the `things`_ submodule. This includes control of a camera and a translation stage, as well as various software `.Thing`\ s that integrate the two.
+For more complex examples, there is a useful collection of `~lt.Thing` subclasses implemented as part of the `OpenFlexure Microscope`_ in the `things`_ submodule. This includes control of a camera and a translation stage, as well as various software `~lt.Thing`\ s that integrate the two.
 
 .. _`OpenFlexure Microscope`: https://gitlab.com/openflexure/openflexure-microscope-server/
 .. _`things`: https://gitlab.com/openflexure/openflexure-microscope-server/-/tree/v3/src/openflexure_microscope_server/things/

docs/source/index.rst

@@ -20,15 +20,16 @@ Documentation for LabThings-FastAPI
    wot_core_concepts.rst
    removed_features.rst
 
+   quick_reference.rst
    autoapi/index
    developer_notes/index.rst
 
 `labthings-fastapi` is a Python library to simplify the process of making laboratory instruments available via a HTTP. It aims to create an API that is usable from any modern programming language, with API documentation in both :ref:`openapi` and :ref:`gen_td` formats. It is the underlying framework for v3 of the `OpenFlexure Microscope software <https://gitlab.com/openflexure/openflexure-microscope-server/>`_. Key features and design aims are:
 
-* The functionality of a unit of hardware or software is described using `.Thing` subclasses.
-* Methods and properties of `.Thing` subclasses may be added to the HTTP API and associated documentation using decorators.
+* The functionality of a unit of hardware or software is described using `~lt.Thing` subclasses.
+* Methods and properties of `~lt.Thing` subclasses may be added to the HTTP API and associated documentation using decorators.
 * Datatypes of action input/outputs and properties are defined with Python type hints.
-* Actions are decorated methods of a `.Thing` class. There is no need for separate schemas or endpoint definitions.
+* Actions are decorated methods of a `~lt.Thing` class. There is no need for separate schemas or endpoint definitions.
 * Properties are defined either as typed attributes (similar to `pydantic` or `dataclasses`) or with a `property`\ -like decorator.
 * Lifecycle and concurrency are appropriate for hardware: `Thing` code is always run in a thread, and each `Thing` is instantiated, started up, and shut down only once.
 * Vocabulary and concepts are aligned with the `W3C Web of Things <https://www.w3.org/WoT/>`_ standard (see :ref:`wot_cc`)