labthings_fastapi.client ======================== .. py:module:: labthings_fastapi.client .. autoapi-nested-parse:: Code to access `~lt.Thing` features over HTTP. This module defines a base class for controlling LabThings-FastAPI over HTTP. It is based on `httpx`, and attempts to create a simple wrapper such that each Action becomes a method and each Property becomes an attribute. Classes ------- .. autoapisummary:: labthings_fastapi.client.ThingClient Functions --------- .. autoapisummary:: labthings_fastapi.client.poll_invocation Package Contents ---------------- .. py:function:: poll_invocation(client: httpx.Client, invocation: dict, interval: float = 0.5, first_interval: float = 0.05) -> dict Poll a invocation until it finishes, and return the output. When actions are invoked in a LabThings-FastAPI server, the initial POST request returns immediately. The returned invocation includes a link that may be polled to find out when the action has completed, whether it was successful, and retrieve its output. :param client: the `httpx.Client` to use for HTTP requests. :param invocation: the dictionary returned from the initial POST request. :param interval: sets how frequently we poll, in seconds. :param first_interval: sets how long we wait before the first polling request. Often, it makes sense for this to be a short interval, in case the action fails (or returns) immediately. :raises ServerActionError: if an HTTP error is found during polling. :return: the completed invocation as a dictionary. .. py:class:: ThingClient(base_url: str, client: Optional[httpx.Client] = None) A client for a LabThings-FastAPI Thing. .. note:: ThingClient must be subclassed to add actions/properties, so this class will be minimally useful on its own. The best way to get a client for a particular Thing is currently `.ThingClient.from_url`, which dynamically creates a subclass with the right attributes. Create a ThingClient connected to a remote Thing. :param base_url: the base URL of the Thing. This should be the URL of the Thing Description document. :param client: an optional `httpx.Client` object to use for all HTTP requests. This may be a `fastapi.TestClient` object for testing purposes. .. py:attribute:: server .. py:attribute:: path .. py:attribute:: client .. py:method:: get_property(path: str) -> Any Make a GET request to retrieve the value of a property. :param path: the URI of the ``getproperty`` endpoint, relative to the ``base_url``. :return: the property's value, as deserialised from JSON. :raise ClientPropertyError: is raised the property cannot be read. .. py:method:: set_property(path: str, value: Any) -> None Make a PUT request to set the value of a property. :param path: the URI of the ``getproperty`` endpoint, relative to the ``base_url``. :param value: the property's value. Currently this must be serialisable to JSON. :raise ClientPropertyError: is raised the property cannot be set. .. py:method:: invoke_action(path: str, **kwargs: Any) -> Any Invoke an action on the Thing. This method will make the initial POST request to invoke an action, then poll the resulting invocation until it completes. If successful, the action's output will be returned directly. While the action is running, log messages will be re-logged locally. If you have enabled logging to the console, these should be visible. :param path: the URI of the ``invokeaction`` endpoint, relative to the ``base_url`` :param \**kwargs: Additional arguments will be combined into the JSON body of the ``POST`` request and sent as input to the action. These will be validated on the server. :return: the output value of the action. :raise FailedToInvokeActionError: if the action fails to start. :raise ServerActionError: is raised if the action does not complete successfully. .. py:method:: follow_link(response: dict, rel: str) -> httpx.Response Follow a link in a response object, by its `rel` attribute. :param response: is the dictionary returned by e.g. `.poll_invocation`. :param rel: picks the link to follow by matching its ``rel`` item. :return: the response to making a ``GET`` request to the link. .. py:method:: from_url(thing_url: str, client: Optional[httpx.Client] = None) -> Self :classmethod: Create a ThingClient from a URL. This will dynamically create a subclass with properties and actions, and return an instance of that subclass pointing at the Thing URL. :param thing_url: The base URL of the Thing, which should also be the URL of its Thing Description. :param client: is an optional `httpx.Client` object. If not present, one will be created. This is particularly useful if you need to set HTTP options, or if you want to work with a local server object for testing purposes (see `fastapi.TestClient`). :return: a `~lt.ThingClient` subclass with properties and methods that match the retrieved Thing Description (see :ref:`wot_thing`). .. py:method:: subclass_from_td(thing_description: dict) -> type[Self] :classmethod: Create a ThingClient subclass from a Thing Description. Dynamically subclass `~lt.ThingClient` to add properties and methods for each property and action in the Thing Description. :param thing_description: A :ref:`wot_td` as a dictionary, which will be used to construct the class. :return: a `~lt.ThingClient` subclass with the right properties and methods.