labthings_fastapi.server.cli

Command-line interface to the ThingServer.

This module provides a command-line interface that is provided as labthings-server. It exposes various functions that may be useful to projects based on LabThings, if they wish to expose their own CLI.

Note

In principle, LabThings may be run as an ASGI application wrapped by a more advanced HTTP server providing HTTPS or other features. This generally requires configuration via environment variables rather than command-line flags.

Environment variables are not yet supported, but may supplement or replace the command line interface in the future.

For examples of how to run the server from the command line, see the tutorial page Running LabThings-FastAPI.

Functions

`get_default_parser`(→ argparse.ArgumentParser)	Return the default CLI parser for LabThings.
`parse_args`(→ argparse.Namespace)	Process command line arguments for the server.
`config_from_args`(...)	Load the configuration from a supplied file or JSON string.
`serve_from_cli`(→ labthings_fastapi.server.ThingServer)	Start the server from the command line.

Module Contents

labthings_fastapi.server.cli.get_default_parser() → argparse.ArgumentParser

Return the default CLI parser for LabThings.

This can be used to add more arguments, for custom CLIs that make use of LabThings.

Returns:: an argparse.ArgumentParser set up with the options for labthings-server.

labthings_fastapi.server.cli.parse_args(argv: list[str] | None = None) → argparse.Namespace

Process command line arguments for the server.

The arguments are defined in get_default_parser.

Parameters:: argv – command line arguments (defaults to arguments supplied to the current command).
Returns:: a namespace with the extracted options.

labthings_fastapi.server.cli.config_from_args(args: argparse.Namespace) → labthings_fastapi.server.config_model.ThingServerConfig

Load the configuration from a supplied file or JSON string.

This function will first attempt to load a JSON file specified in the command line argument. It will then look for JSON configuration supplied as a string.

If both a file and a string are specified, the JSON string will be used to update the configuration loaded from file, i.e. it will overwrite keys in the file.

Parameters:

args – Parsed arguments from parse_args.

Returns:

the server configuration.

Raises:

FileNotFoundError – if the configuration file specified is missing.
RuntimeError – if neither a config file nor a string is provided.

labthings_fastapi.server.cli.serve_from_cli(argv: list[str] | None = None) → labthings_fastapi.server.ThingServer

Start the server from the command line.

This function will parse command line arguments, load configuration, set up a server, and start it. It calls parse_args, config_from_args and ThingServer to get a server, then serves on the specified host and port using uvicorn.

If the fallback argument is specified, errors that stop the LabThings server from starting will be handled by starting a simple HTTP server that shows an error page. This behaviour may be helpful if labthings-server is being run on a headless server, where an HTTP error page is more useful than no response.

If fallback is not specified, we will print the error and exit.

Parameters:: argv – command line arguments (defaults to arguments supplied to the current command).
Returns:: the ThingServer instance created. This is mostly useful for test code that mocks uvicorn.run to allow inspection of the server.
Raises:: BaseException – if the server cannot start, and the fallback option is not specified.