Documentation for LabThings-FastAPI
=============================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   quickstart/quickstart.rst
   wot_core_concepts.rst
   lt_core_concepts.rst
   tutorial/index.rst
   dependencies/dependencies.rst
   blobs.rst
   concurrency.rst
   using_things.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/>`_.

`labthings-fastapi` aims to simplify the process of making laboratory instruments available via an HTTP API. Key features and design aims are below:

* 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
    - 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)
    - 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``

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. _python-labthings: https://github.com/labthings/python-labthings/
.. _FastAPI: https://fastapi.tiangolo.com/
.. _pydantic: https://pydantic-docs.helpmanual.io/