Documentation improvements

docs/source/blobs.rst

@@ -0,0 +1,135 @@
+Blob input/output
+=================
+
+:class:`.Blob` objects allow binary data to be returned by an Action. This binary data can be passed between Things, or between Things and client code. Using a :class:`.Blob` object allows binary data to be efficiently sent over HTTP if required, and allows the same code to run either on the server (without copying the data) or on a client (where data is transferred over HTTP).
+
+If interactions require only simple data types that can easily be represented in JSON, very little thought needs to be given to data types - strings and numbers will be converted to and from JSON automatically, and your Python code should only ever see native Python datatypes whether it's running on the server or a remote client. However, if you want to transfer larger data objects such as images, large arrays or other binary data, you will need to use a :class:`.Blob` object.
+
+:class:`.Blob` objects are not part of the Web of Things specification, which is most often used with fairly simple data structures in JSON. In LabThings-FastAPI, the :class:`.Blob` mechanism is intended to provide an efficient way to work with arbitrary binary data. If it's used to transfer data between two Things on the same server, the data should not be copied or otherwise iterated over - and when it must be transferred over the network it can be done using a binary transfer, rather than embedding in JSON with base64 encoding.
+
+A :class:`.Blob` consists of some data and a MIME type, which sets how the data should be interpreted. It is best to create a subclass of :class:`.Blob` with the content type set: this makes it clear what kind of data is in the :class:`.Blob`. In the future, it might be possible to add functionality to :class:`.Blob` subclasses, for example to make it simple to obtain an image object from a :class:`.Blob` containing JPEG data. However, this will not currently work across both client and server code.
+
+Creating and using :class:`.Blob` objects
+------------------------------------------------
+
+Blobs can be created from binary data that is in memory (a :class:`bytes` object), on disk (a file), or using a URL as a placeholder. The intention is that the code that uses a :class:`.Blob` should not need to know which of these is the case, and should be able to use the same code regardless of how the data is stored. 
+
+Blobs offer three ways to access their data:
+
+* A `bytes` object, obtained via the `data` property. For blobs created with a `bytes` object, this simply returns the original data object with no copying. If the data is stored in a file, the file is opened and read when the `data` property is accessed. If the :class:`.Blob` references a URL, it is retrieved and returned when `data` is accessed.
+* An `open()` method providing a file-like object. This returns a :class:`~io.BytesIO` wrapper if the :class:`.Blob` was created from a `bytes` object or the file if the data is stored on disk. URLs are retrieved, stored as `bytes` and returned wrapped in a :class:`~io.BytesIO` object. 
+* A `save` method will either save the data to a file, or copy the existing file on disk. This should be more efficient than loading `data` and writing to a file, if the :class:`.Blob` is pointing to a file rather than data in memory. 
+
+The intention here is that :class:`.Blob` objects may be used identically with data in memory or on disk or even at a remote URL, and the code that uses them should not need to know which is the case.
+
+Examples
+--------
+
+A camera might want to return an image as a :class:`.Blob` object. The code for the action might look like this:
+
+.. code-block:: python
+
+    from labthings_fastapi.blob import Blob
+    from labthings_fastapi.thing import Thing
+    from labthings_fastapi.decorators import thing_action
+
+    class JPEGBlob(Blob):
+        content_type = "image/jpeg"
+
+    class Camera(Thing):
+        @thing_action
+        def capture_image(self) -> JPEGBlob:
+            # Capture an image and return it as a Blob
+            image_data = self._capture_image()  # This returns a bytes object holding the JPEG data
+            return JPEGBlob.from_bytes(image_data)
+
+The corresponding client code might look like this:
+
+.. code-block:: python
+
+    from PIL import Image
+    from labthings_fastapi.client import ThingClient
+
+    camera = ThingClient.from_url("http://localhost:5000/camera/")
+    image_blob = camera.capture_image()
+    image_blob.save("captured_image.jpg")  # Save the image to a file
+
+    # We can also open the image directly with PIL
+    with image_blob.open() as f:
+        img = Image.open(f)
+    img.show()  # This will display the image in a window
+
+We could define a more sophisticated camera that can capture raw images and convert them to JPEG, using two actions:
+
+.. code-block:: python
+
+    from labthings_fastapi.blob import Blob
+    from labthings_fastapi.thing import Thing
+    from labthings_fastapi.decorators import thing_action
+
+    class JPEGBlob(Blob):
+        content_type = "image/jpeg"
+
+    class RAWBlob(Blob):
+        content_type = "image/x-raw"
+
+    class Camera(Thing):
+        @thing_action
+        def capture_raw_image(self) -> RAWBlob:
+            # Capture a raw image and return it as a Blob
+            raw_data = self._capture_raw_image()  # This returns a bytes object holding the raw data
+            return RAWBlob.from_bytes(raw_data)
+
+        @thing_action
+        def convert_raw_to_jpeg(self, raw_blob: RAWBlob) -> JPEGBlob:
+            # Convert a raw image Blob to a JPEG Blob
+            jpeg_data = self._convert_raw_to_jpeg(raw_blob.data)  # This returns a bytes object holding the JPEG data
+            return JPEGBlob.from_bytes(jpeg_data)
+
+        @thing_action
+        def capture_image(self) -> JPEGBlob:
+            # Capture an image and return it as a Blob
+            raw_blob = self.capture_raw_image()  # Capture the raw image
+            jpeg_blob = self.convert_raw_to_jpeg(raw_blob)  # Convert the raw image to JPEG
+            return jpeg_blob  # Return the JPEG Blob
+            # NB the `raw_blob` is not retained after this action completes, so it will be garbage collected
+
+On the client, we can use the `capture_image` action directly (as before), or we can capture a raw image and convert it to JPEG:
+
+.. code-block:: python
+
+    from PIL import Image
+    from labthings_fastapi.client import ThingClient
+
+    camera = ThingClient.from_url("http://localhost:5000/camera/")
+
+    # Capture a JPEG image directly
+    jpeg_blob = camera.capture_image()
+    jpeg_blob.save("captured_image.jpg")
+
+    # Alternatively, capture a raw image and convert it to JPEG
+    raw_blob = camera.capture_raw_image() # NB the raw image is not yet downloaded
+    jpeg_blob = camera.convert_raw_to_jpeg(raw_blob)
+    jpeg_blob.save("converted_image.jpg")
+
+    raw_blob.save("raw_image.raw")  # Download and save the raw image to a file
+
+
+Using :class:`.Blob` objects as inputs
+--------------------------------------
+
+:class:`.Blob` objects may be used as either the input or output of an action. There are relatively few good use cases for :class:`.Blob` inputs to actions, but a possible example would be image capture: one action could perform a quick capture of raw data, and another action could convert the raw data into a useful image. The output of the capture action would be a :class:`.Blob` representing the raw data, which could be passed to the conversion action. 
+
+Because :class:`.Blob` outputs are represented in JSON as links, they are downloaded with a separate HTTP request if needed. There is currently no way to create a :class:`.Blob` on the server via HTTP, which means remote clients can use :class:`.Blob` objects provided in the output of actions but they cannot yet upload data to be used as input. However, it is possible to pass the URL of a :class:`.Blob` that already exists on the server as input to a subsequent Action. This means, in the example above of raw image capture, a remote client over HTTP can pass the raw :class:`.Blob` to the conversion action, and the raw data need never be sent over the network.
+
+Memory management and retention
+-------------------------------
+
+Management of :class:`.Blob` objects is currently very basic: when a :class:`.Blob` object is returned in the output of an Action that has been called via the HTTP interface, a fixed 5 minute expiry is used. This should be improved in the future to avoid memory management issues. 
+
+The behaviour is different when actions are called from other actions. If `action_a` calls `action_b`, and `action_b` returns a :class:`.Blob`, that :class:`.Blob` will be subject to Python's usual garbage collection rules when `action_a` ends - i.e. it will not be retained unless it is included in the output of `action_a`.
+
+HTTP interface and serialization
+--------------------------------
+
+:class:`.Blob` objects are subclasses of `pydantic.BaseModel`, which means they can be serialized to JSON and deserialized from JSON. When this happens, the :class:`.Blob` is represented as a JSON object with two fields: `url` and `content_type`. The `url` field is a link to the data. The `content_type` field is a string representing the MIME type of the data. When a :class:`.Blob` is serialized, a URL is generated with a unique ID to allow it to be downloaded. However, only a weak reference is held to the :class:`.Blob`. Once an Action has finished running, the only strong reference to the :class:`.Blob` should be held by the output property of the action invocation. The :class:`.Blob` should be garbage collected once the output is no longer required, i.e. when the invocation is discarded - currently 5 minutes after the action completes, once the maximum number of invocations has been reached or when it is explicitly deleted by the client.

docs/source/client_code.rst

@@ -0,0 +1,18 @@
+Client code
+===========
+
+The interface to a `Thing` is defined by its actions, properties and events. Usually, Python code interacts with a `Thing` through a `ThingClient` subclass, where each action is a method and each property is a property of the class. The intention is to provide a simple, pythonic interface that plays nicely with IDEs and autocompletion. `ThingClient` subclasses can be generated dynamicall from a URL. Currently, this creates an object with the right methods and properties, but type hints are usually missing and autocompletion does not work well. In the future, `labthings-fastapi` will generate custom client subclasses that include type hints and autocompletion.
+
+An additional goal is to provide an interface that is consistent between the server and client code: a `DirectThingClient` class is used by the `labthings-fastapi` server to call actions and properties of other `Thing`s, which means code for an action may be developed as an HTTP client, for example in a Jupyter notebook, and then moved to the server with minimal changes. Currently, there are a few differences in behaviour between local and remote `Thing`s, most notably the return types (which are usually Pydantic models on the server, and currently dictionaries generated from JSON on the client). This should be improved in the future.
+
+Client code generation
+----------------------
+
+Currently, most clients are created using the class method `ThingClient.from_url`. This returns an instance of a dynamically-created subclass, rather than a `ThingClient` instance directly. The subclass is required in order to add methods and properties corresponding to the Thing Description sent by the server. While this is a solution that should work immediately, it does not work well with code completion or static analysis, and client objects must be introspected on-the-fly.
+
+In the future, `labthings_fastapi` will generate custom client subclasses. These will have the methods and properties defined in a Python module, including type annotations. This will allow static analysis (e.g. with MyPy) and IDE autocompletion to work. Most packages that provide a `Thing` subclass will want to release a client package that is generated automatically in this way. The intention is to make it possible to add custom Python code to this client, for example to handle specialised return types more gracefully or add convenience methods.
+
+
+
+
+

docs/source/concurrency.rst

@@ -0,0 +1,15 @@
+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 `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 `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.
+
+Many of the functions that handle HTTP requests are asynchronous, running in an `anyio` event loop. This enables many HTTP connections to be handled at once with good efficiency. The interface between async and threaded code is provided by a "Blocking Portal" created when the LabThings server is started. A FastAPI Dependency allows the blocking portal to be obtained: while it's very unlikely more than one LabThings server will exist in one Python instance, we avoid referring to the blocking portal globally in an effort to avoid concurrency issues.
+
+If threaded code needs to call code in the `anyio` event loop, the blocking portal dependency should be used. 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.
+
+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.
+

docs/source/index.rst

@@ -1,45 +1,50 @@
-.. labthings-fastapi documentation master file, created by
-   sphinx-quickstart on Wed May 15 16:34:51 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to labthings-fastapi's documentation!
+Documentation for LabThings-FastAPI
 =============================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   core_concepts.rst
    quickstart/quickstart.rst
+   wot_core_concepts.rst
+   lt_core_concepts.rst
+   tutorial/index.rst
    dependencies/dependencies.rst
+   blobs.rst
+   concurrency.rst
+   client_code.rst
 
    apidocs/index
 
 `labthings-fastapi` implements a Web of Things interface for laboratory hardware using Python. This is a ground-up rewrite of python-labthings_, replacing Flask 1 and Marshmallow with FastAPI and Pydantic. It is the underlying framework for v3 of the `OpenFlexure Microscope software <https://gitlab.com/openflexure/openflexure-microscope-server/>`_.
 
-Features include:
+`labthings-fastapi` aims to simplify the process of making laboratory instruments available via an HTTP API. Key features and design aims are below:
 
-* Alignment with the `W3C Web of Things <https://www.w3.org/WoT/>`_ standard (see :doc:`core_concepts`)
+* Functionality together in `Thing` subclasses, which represent units of hardware or software (see :doc:`wot_core_concepts`)
+* Methods and properties of `Thing` subclasses may be added to the HTTP API and Thing Description using decorators
+* Vocabulary and concepts are aligned with the `W3C Web of Things <https://www.w3.org/WoT/>`_ standard (see :doc:`wot_core_concepts`)
     - Things are classes, with properties and actions defined exactly once
-    - Various improvements to TD generation and validation with `pydantic`
-* Cleaner API
+    - Thing Descriptions are automatically generated, and validated with `pydantic`
+    - OpenAPI documentation is automatically generated by FastAPI
+* We follow FastAPI_'s lead and try to use standard Python features to minimise unnecessary code
     - Datatypes of action input/outputs and properties are defined with Python type hints
     - Actions are defined exactly once, as a method of a `Thing` class
     - Properties and actions are declared using decorators (or descriptors if that's preferred)
-    - Dependency injection is used to manage relationships between Things and dependency on the server
-* Async HTTP handling
-    - Starlette (used by FastAPI) can handle requests asynchronously - potential for websockets/events (not used much yet)
-    - `Thing` code is still, for now, threaded. I intend to make it possible to write async things in the future, but don't intend it to become mandatory
-* Smaller codebase
-    - FastAPI more or less completely eliminates OpenAPI generation code from our codebase
-    - Thing Description generation is very much simplified by the new structure (multiple Things instead of one massive Thing with many extensions)
+    - FastAPI_ "Dependency injection" is used to manage relationships between Things and dependency on the server
+* Lifecycle and concurrency are appropriate for hardware: `Thing` code is always run in a thread, and each `Thing` is instantiated and shut down only once.
+    - Starlette (used by FastAPI) can handle requests asynchronously - this improves performance and enables websockets and other long-lived connections.
+    - `Thing` code is still, for now, threaded. In the future it may become possible to us other concurrency models in `Thing` code.
+
+Compared to `python-labthings`_, this framework updates dependencies, shrinks the codebase, and simplifies the API  (see :doc:`lt_core_concepts`).
+* FastAPI more or less completely eliminates OpenAPI generation code from our codebase
+* Marshmallow schemas and endpoint classes are replaced with Python type hints, eliminating double- or triple-definition of actions and their inputs/outputs.
+* Thing Description generation is very much simplified by the new structure (multiple Things instead of one massive Thing with many extensions)
 
 
 Installation
 ------------
 
-``pip install labthings-fastapi``
+``pip install labthings-fastapi[server]``
 
 Indices and tables
 ==================
@@ -48,4 +53,6 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-.. _python-labthings: https://github.com/labthings/python-labthings/
+.. _python-labthings: https://github.com/labthings/python-labthings/
+.. _FastAPI: https://fastapi.tiangolo.com/
+.. _pydantic: https://pydantic-docs.helpmanual.io/