Documentation for LabThings-FastAPI

Contents:

• Contributing to labthings-fastapi
  • Seeking Support
  • Reporting Issues or Bugs
  • Contributing Code or Documentation
• Quick start
• LabThings-FastAPI tutorial
  • Installing LabThings-FastAPI
  • Running LabThings-FastAPI
  • Writing a Thing
• LabThings structure
  • Server
  • Things
  • Client Code
  • Data types
• Actions
  • Running actions via HTTP
  • Running actions from other actions
  • Action inputs and outputs
  • Logging from actions
  • Collecting metadata
  • Cancelling actions
  • Invocation contexts
  • Raising exceptions
• Properties
  • Data properties
  • Functional properties
  • Property constraints
  • Property metadata
  • HTTP interface
  • Observable properties
  • Settings
• Generated documentation
  • OpenAPI
  • Thing Description
  • Comparison of Thing Description and OpenAPI
• Thing Slots
  • Configuring Thing Slots
• Blob input/output
  • Creating and using Blob objects
  • Examples
  • Using Blob objects as inputs
  • HTTP interface and serialisation
  • Memory management and retention
• Concurrency in LabThings-FastAPI
  • Calling Things from other Things
  • Invocations and concurrency
  • Global locking
• Using Things
  • Using Things from other Things
  • Using Things from other languages
  • Dynamic class generation
  • Planned future development: static code generation
• Optional Features and updates
• See Also
• Examples
• Testing labthings-fastapi
  • Continuous Integration (CI) Pipeline
  • Running Core Tests Locally
  • Downstream Integration Testing Locally
• Web of Things Core Concepts
  • Thing
  • Properties
  • Actions
  • Events
  • Thing Description
  • Interaction Affordances
• Removed Features
  • Dependencies
• Public API Documentation
  • Thing
  • property()
  • setting()
  • action()
  • thing_slot()
  • endpoint()
  • ThingServer
  • ThingServerInterface
  • ThingClassSettings
  • ThingConfig
  • ThingServerConfig
  • ThingClient
  • cancellable_sleep()
  • raise_if_cancelled()
  • ThreadWithInvocationID
  • DataProperty
  • DataSetting
  • outputs
  • blob
  • cli
• Internal API Reference
  • labthings_fastapi
• Developer Notes
  • Descriptors

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 OpenAPI and Thing Description formats. It is the underlying framework for v3 of the OpenFlexure Microscope software. 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.

• 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.

• 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 standard (see Web of Things Core Concepts)

Previous version

This is a ground-up rewrite of python-labthings, replacing Flask 1 and Marshmallow with FastAPI and Pydantic. Compared to python-labthings, this framework updates dependencies, shrinks the codebase, and simplifies the API (see LabThings structure). * 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

labthings-fastapi supports Python 3.10, 3.11, 3.12, and 3.13. The upper limit is strictly capped at 3.13 due to current pydantic-core dependencies.

Note

Windows Installations on devices with ARM Processors

Installing on Windows devices with ARM processors requires Visual Studio with the “Desktop development with C++” workload enabled. This is necessary because pydantic relies on Rust, which in turn requires C++ build tools to compile.

If you are using a centrally managed machine, you will need administrator privileges to install these system-level dependencies.

Indices and tables

• Index

• Module Index

• Search Page