labthings_fastapi.server.cli
============================

.. py:module:: labthings_fastapi.server.cli

.. autoapi-nested-parse::

   Command-line interface to the `~lt.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 :ref:`tutorial_running`.



Functions
---------

.. autoapisummary::

   labthings_fastapi.server.cli.get_default_parser
   labthings_fastapi.server.cli.parse_args
   labthings_fastapi.server.cli.config_from_args
   labthings_fastapi.server.cli.serve_from_cli


Module Contents
---------------

.. py:function:: 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.

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


.. py:function:: parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace

   Process command line arguments for the server.

   The arguments are defined in `.get_default_parser`\ .

   :param argv: command line arguments (defaults to arguments supplied
       to the current command).

   :return: a namespace with the extracted options.


.. py:function:: 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.

   :param args: Parsed arguments from `.parse_args`.

   :return: the server configuration.

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


.. py:function:: serve_from_cli(argv: Optional[list[str]] = 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 `~lt.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.

   :param argv: command line arguments (defaults to arguments supplied
       to the current command).

   :return: the `~lt.ThingServer` instance created. This is mostly useful
       for test code that mocks `uvicorn.run` to allow inspection of the
       server.

   :raise BaseException: if the server cannot start, and the ``fallback``
       option is not specified.