labthings_fastapi.decorators

Actions

You can add an Action to a Thing by declaring a method, decorated with @thing_action. Parameters are not usually needed, but can be supplied to set various options.

Properties

As with Actions, Properties can be declared by decorating either a function, or an attribute, with @thing_property. You can use the decorator either on a function (in which case that function acts as the “getter” just like with Python’s @property decorator).

Events

Events are created by decorating attributes with @thing_event. Functions are not supported at this time.

The decorators in this module mark the Interaction Affordances of a Thing.

LabThings generates a “Thing Description” to allow actions, properties, and events to be used by client code. The descriptions of each “interaction affordance” rely on docstrings and Python type hints to provide a full description of the parameters, so it’s important that you use these effectively.

If you have a complex datatype, it’s recommended to use a pydantic model to describe it - this is often the case for complicated properties or events. For actions, a model is created automatically based on the function’s signature: if you want to add descriptions or validators to individual arguments, you may use pydantic.Field to do this.

Package Contents

Functions

mark_thing_action	Mark a method of a Thing as an Action
thing_action
thing_property	Mark a method of a Thing as a LabThings Property
thing_setting	Mark a method of a Thing as a LabThings Setting.
fastapi_endpoint	Add a function to FastAPI as an endpoint

API

labthings_fastapi.decorators.mark_thing_action(func: Callable, **kwargs) → labthings_fastapi.descriptors.ActionDescriptor

Mark a method of a Thing as an Action

We replace the function with a Descriptor that’s a subclass of ActionDescriptor

labthings_fastapi.decorators.thing_action(func: Optional[Callable] = None, **kwargs)

labthings_fastapi.decorators.thing_property(func: Callable) → labthings_fastapi.descriptors.ThingProperty

Mark a method of a Thing as a LabThings Property

This should be used as a decorator with a getter and a setter just like a standard python property decorator. If extra functionality is not required in the decorator, then using the ThingProperty class directly may allow for clearer code

As properties are accessed over the HTTP API they need to be JSON serialisable only return standard python types, or Pydantic BaseModels

labthings_fastapi.decorators.thing_setting(func: Callable) → labthings_fastapi.descriptors.ThingSetting

Mark a method of a Thing as a LabThings Setting.

A setting is a property that persists between runs.

This should be used as a decorator with a getter and a setter just like a standard python property decorator. If extra functionality is not required in the decorator, then using the ThingSetting class directly may allow for clearer code where the property works like a normal variable.

When creating a Setting using this decorator you must always create a setter as it is used to load the value from disk.

As settings are accessed over the HTTP API and saved to disk they need to be JSON serialisable only return standard python types, or Pydantic BaseModels.

If the type is a pydantic BaseModel, then the setter must also be able to accept the dictionary representation of this BaseModel as this is what will be used to set the Setting when loading from disk on starting the server.

Note: If a setting is mutated rather than set, this will not trigger saving. For example: if a Thing has a setting called dictsetting holding the dictionary {"a": 1, "b": 2} then self.dictsetting = {"a": 2, "b": 2} would trigger saving but self.dictsetting[a] = 2 would not, as the setter for dictsetting is never called.

labthings_fastapi.decorators.fastapi_endpoint(method: labthings_fastapi.descriptors.HTTPMethod, path: Optional[str] = None, **kwargs)

Add a function to FastAPI as an endpoint