App, LabThing, and Server

Python LabThings works as a Flask extension, and so we introduce two key objects: the flask.Flask app, and the labthings.LabThing object. The labthings.LabThing object is our main entrypoint for the Flask application, and all LabThings functionality is added via this object.

In order to enable threaded actions the app should be served using the labthings.Server class. Other production servers such as Gevent can be used, however this will require monkey-patching and has not been comprehensively tested.

Create app

The labthings.create_app() function automatically creates a Flask app object, enables up cross-origin resource sharing, and initialises a labthings.LabThing instance on the app. The function returns both in a tuple.

labthings.create_app(import_name, prefix: str = '', title: str = '', description: str = '', types: Optional[list] = None, version: str = '0.0.0', external_links: bool = True, handle_errors: bool = True, handle_cors: bool = True, flask_kwargs: Optional[dict] = None)

Quick-create a LabThings-enabled Flask app

Parameters

  • import_name – Flask import name. Usually __name__.

  • prefix (str) – URL prefix for all LabThings views. Defaults to “/api”.

  • title (str) – Title/name of the LabThings Thing.

  • description (str) – Brief description of the LabThings Thing.

  • version (str) – Version number/code of the Thing. Defaults to “0.0.0”.

  • handle_errors (bool) – Use the LabThings error handler, to JSON format internal exceptions. Defaults to True.

  • handle_cors (bool) – Automatically enable CORS on all LabThings views. Defaults to True.

  • flask_kwargs (dict) – Keyword arguments to pass to the Flask instance.

  • prefix – str: (Default value = “”)

  • title – str: (Default value = “”)

  • description – str: (Default value = “”)

  • types – list: (Default value = None)

  • version – str: (Default value = “0.0.0”)

  • external_links – bool: Use external links in Thing Description where possible

  • handle_errors – bool: (Default value = True)

  • handle_cors – bool: (Default value = True)

  • flask_kwargs – dict: (Default value = None)

Returns

(Flask app object, LabThings object)

ALternatively, the app and labthings.LabThing objects can be initialised and attached separately, for example:

from flask import Flask
from labthings import LabThing

app = Flask(__name__)
labthing = LabThing(app)

LabThing

The LabThing object is our main entrypoint, and handles creating API views, managing background actions, tracking logs, and generating API documentation.

class labthings.LabThing(app: Optional[flask.app.Flask] = None, id_: Optional[str] = None, prefix: str = '', title: str = '', description: str = '', version: str = '0.0.0', types: Optional[List[str]] = None, format_flask_exceptions: bool = True, external_links: bool = True, json_encoder=<class 'labthings.json.encoder.LabThingsJSONEncoder'>)

The main entry point for the application. You need to initialize it with a Flask Application:

>>> app = Flask(__name__)
>>> labthing = labthings.LabThing(app)

Alternatively, you can use init_app() to set the Flask application after it has been constructed.

Parameters

  • app (flask.Flask) – the Flask application object

  • prefix (str) – Prefix all routes with a value, eg v1 or 2010-04-01

  • title (str) – Human-readable title of the Thing

  • description (str) – Human-readable description of the Thing

  • version (str) – Version number of the Thing

  • types (list of str) – List of Thing types, used by clients to filter discovered Things

  • format_flask_exceptions (bool) – JSON format all exception responses

  • external_links (bool) – Use external links in Thing Description where possible

  • json_encoder – JSON encoder class for the app

Views

Thing interaction affordances are created using Views. Two main View types correspond to properties and actions.

class labthings.PropertyView(*args, **kwargs)
class labthings.ActionView(*args, **kwargs)

Server

The integrated server actually handles 3 distinct server functions: WSGI HTTP requests, and registering mDNS records for automatic Thing discovery. It is therefore strongly suggested you use the builtin server.

Important notes:

The integrated server will spawn a new native thread per-connection. This will only function well in situations where few (<50) simultaneous connections are expected, such as local Web of Things devices. Do not use this server in any public web app where many connections are expected. It is designed exclusively with low-traffic LAN access in mind.

class labthings.Server(app, host='0.0.0.0', port=7485, debug=False, zeroconf=True)

Combined WSGI+mDNS server.

Parameters

  • host (string) – Host IP address. Defaults to 0.0.0.0.

  • port (int) – Host port. Defaults to 7485.

  • debug (bool) – Enable server debug mode. Defaults to False.

  • zeroconf (bool) – Enable the zeroconf (mDNS) server. Defaults to True.

run(host=None, port=None, debug=None, zeroconf=None)

Starts the server allowing for runtime parameters. Designed to immitate the old Flask app.run style of starting an app

Parameters

  • host (string) – Host IP address. Defaults to 0.0.0.0.

  • port (int) – Host port. Defaults to 7485.

  • debug (bool) – Enable server debug mode. Defaults to False.

  • zeroconf (bool) – Enable the zeroconf (mDNS) server. Defaults to True.

start()

Start the server and register mDNS records