labthings_fastapi.descriptors.endpoint

Add a FastAPI endpoint without making it an action.

The EndpointDescriptor wraps a function and marks it to be added to the HTTP API at the same time as the properties and actions of the host Thing. This is intended to allow flexibility to implement endpoints that cannot be described in a Thing Description as actions or properties.

It may use any fastapi responses or arguments, as it passes keyword arguments through to the relevant fastapi decorator.

This will most usually be applied as a decorator with arguments, available as :deco:`.fastapi_endpoint`. See the documentation for that function for more detail.

Attributes

HTTPMethod

Valid HTTP verbs to use with fastapi_endpoint or EndpointDescriptor.

Classes

EndpointDescriptor

A descriptor to allow Things to easily add other endpoints.

Module Contents

labthings_fastapi.descriptors.endpoint.HTTPMethod

Valid HTTP verbs to use with fastapi_endpoint or EndpointDescriptor.

class labthings_fastapi.descriptors.endpoint.EndpointDescriptor(func: Callable, http_method: HTTPMethod = 'get', path: str | None = None, **kwargs: Mapping)

A descriptor to allow Things to easily add other endpoints.

Initialise an EndpointDescriptor.

See fastapi_endpoint, which is the usual way of instantiating this class.

Parameters:

  • func – is the method (defined on a Thing) wrapped by this descriptor.

  • http_method – the HTTP verb we are responding to. This selects the FastAPI decorator: "get" corresponds to @app.get.

  • path – the URL, relative to the host Thing, for the endpoint.

  • **kwargs – additional keyword arguments are passed to the FastAPI decorator, allowing you to specify responses, OpenAPI parameters, etc.

func
http_method = 'get'
_path = None
kwargs
__get__(obj: Literal[None], type=None) → typing_extensions.Self
__get__(obj: labthings_fastapi.thing.Thing, type=None) → Callable

Bind the method to the host Thing and return it.

When called on a Thing, this descriptor returns the wrapped function, with the Thing bound as its first argument. This is the usual behaviour for Python methods.

If obj is None, the descriptor is returned, so we can get the descriptor conveniently as an attribute of the class.

Parameters:

  • obj – The Thing on which the descriptor is defined, or None.

  • type – The class on which the descriptor is defined.

Returns:

The wrapped function, bound to the Thing (when called as an instance attribute), or the descriptor itself (when called as a class attribute).

property name

The name of the wrapped function.

property path

The path of the endpoint (relative to the Thing).

property title

A human-readable title.

property description

A description of the endpoint.

add_to_fastapi(app: fastapi.FastAPI, thing: labthings_fastapi.thing.Thing)

Add an endpoint for this function to a FastAPI app.

We will add an endpoint to the app, bound to a particular Thing. The URL will be prefixed with the Thing path, i.e. the specified URL (which defaults to the name of this descriptor) is relative to the host Thing.

Parameters: