labthings_fastapi.client

Code to access 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

ThingClient

A client for a LabThings-FastAPI Thing.

Functions

poll_invocation(→ dict)

Poll a invocation until it finishes, and return the output.

Package Contents

labthings_fastapi.client.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.

Parameters:

• client – the httpx.Client to use for HTTP requests.

• invocation – the dictionary returned from the initial POST request.

• interval – sets how frequently we poll, in seconds.

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

Returns:

the completed invocation as a dictionary.

class labthings_fastapi.client.ThingClient(base_url: str, client: httpx.Client | None = 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.

Parameters:

• base_url – the base URL of the Thing. This should be the URL of the Thing Description document.

• client – an optional httpx.Client object to use for all HTTP requests. This may be a fastapi.TestClient object for testing purposes.

server

path

client

get_property(path: str) → Any

Make a GET request to retrieve the value of a property.

Parameters:

path – the URI of the getproperty endpoint, relative to the base_url.

Returns:

the property’s value, as deserialised from JSON.

Raises:

ClientPropertyError – is raised the property cannot be read.

set_property(path: str, value: Any) → None

Make a PUT request to set the value of a property.

Parameters:

• path – the URI of the getproperty endpoint, relative to the base_url.

• value – the property’s value. Currently this must be serialisable to JSON.

Raises:

ClientPropertyError – is raised the property cannot be set.

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.

Parameters:

• path – the URI of the invokeaction endpoint, relative to the base_url

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

Returns:

the output value of the action.

Raises:

• FailedToInvokeActionError – if the action fails to start.

• ServerActionError – is raised if the action does not complete successfully.

follow_link(response: dict, rel: str) → httpx.Response

Follow a link in a response object, by its rel attribute.

Parameters:

• response – is the dictionary returned by e.g. poll_invocation.

• rel – picks the link to follow by matching its rel item.

Returns:

the response to making a GET request to the link.

classmethod from_url(thing_url: str, client: httpx.Client | None = None) → Self

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.

Parameters:

• thing_url – The base URL of the Thing, which should also be the URL of its Thing Description.

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

Returns:

a ThingClient subclass with properties and methods that match the retrieved Thing Description (see Thing).

classmethod subclass_from_td(thing_description: dict) → type[Self]

Create a ThingClient subclass from a Thing Description.

Dynamically subclass ThingClient to add properties and methods for each property and action in the Thing Description.

Parameters:

thing_description – A Thing Description as a dictionary, which will be used to construct the class.

Returns:

a ThingClient subclass with the right properties and methods.