Add .Thing.actions

This is added, largely for completeness so it's consistent between actions, properties and settings.

Author: rwb27

src/labthings_fastapi/actions.py

@@ -39,7 +39,11 @@
 from fastapi import FastAPI, HTTPException, Request, Body, BackgroundTasks
 from pydantic import BaseModel, create_model
 
-from .base_descriptor import BaseDescriptor
+from .base_descriptor import (
+    BaseDescriptor,
+    BaseDescriptorInfo,
+    DescriptorInfoCollection,
+)
 from .logs import add_thing_log_destination
 from .utilities import model_to_dict, wrap_plain_types_in_rootmodel
 from .invocations import InvocationModel, InvocationStatus, LogRecordModel
@@ -622,6 +626,54 @@ def delete_invocation(id: uuid.UUID) -> None:
 OwnerT = TypeVar("OwnerT", bound="Thing")
 
 
+class ActionInfo(
+    BaseDescriptorInfo[
+        "ActionDescriptor", OwnerT, Callable[ActionParams, ActionReturn]
+    ],
+    Generic[OwnerT, ActionParams, ActionReturn],
+):
+    """Convenient access to the metadata of an action."""
+
+    @property
+    def response_timeout(self) -> float:
+        """The time to wait before replying to the HTTP request initiating an action."""
+        return self.get_descriptor().response_timeout
+
+    @property
+    def retention_time(self) -> float:
+        """How long to retain the action's output for, in seconds."""
+        return self.get_descriptor().retention_time
+
+    @property
+    def input_model(self) -> type[BaseModel]:
+        """A Pydantic model for the input parameters of an Action."""
+        return self.get_descriptor().input_model
+
+    @property
+    def output_model(self) -> type[BaseModel]:
+        """A Pydantic model for the output parameters of an Action."""
+        return self.get_descriptor().output_model
+
+    @property
+    def invocation_model(self) -> type[BaseModel]:
+        """A Pydantic model for an invocation of this action."""
+        return self.get_descriptor().invocation_model
+
+    @property
+    def func(self) -> Callable[Concatenate[OwnerT, ActionParams], ActionReturn]:
+        """The function that runs the action."""
+        return self.get_descriptor().func
+
+
+class ActionCollection(
+    DescriptorInfoCollection[OwnerT, ActionInfo],
+    Generic[OwnerT],
+):
+    """Access to the metadata of each Action."""
+
+    _descriptorinfo_class = ActionInfo
+
+
 class ActionDescriptor(
     BaseDescriptor[OwnerT, Callable[ActionParams, ActionReturn]],
     Generic[ActionParams, ActionReturn, OwnerT],
@@ -914,6 +966,15 @@ def action_affordance(
             output=type_to_dataschema(self.output_model, title=f"{self.name}_output"),
         )
 
+    def descriptor_info(self, owner: OwnerT | None = None) -> ActionInfo:
+        """Return an `.ActionInfo` object describing this action.
+
+        The returned object will either refer to the class, or be bound to a particular
+        instance. If it is bound, more properties will be available - e.g. we will be
+        able to get the bound function.
+        """
+        return self._descriptor_info(ActionInfo, owner)
+
 
 @overload
 def action(

src/labthings_fastapi/thing.py

@@ -27,7 +27,7 @@
     PropertyCollection,
     SettingCollection,
 )
-from .actions import ActionDescriptor
+from .actions import ActionCollection, ActionDescriptor
 from .thing_description._model import ThingDescription, NoSecurityScheme
 from .utilities import class_attributes
 from .thing_description import validation
@@ -258,6 +258,15 @@ def save_settings(self) -> None:
     convenient access to metadata of the settings of this `.Thing`\ .
     """
 
+    actions: OptionallyBoundDescriptor["Thing", ActionCollection] = (
+        OptionallyBoundDescriptor(ActionCollection)
+    )
+    r"""Access to metadata for the actions of this `.Thing`\ .
+
+    `.Thing.actions` is a mapping of names to `.ActionInfo` objects that allows
+    convenient access to metadata of each action.
+    """
+
     _labthings_thing_state: Optional[dict] = None
 
     @property

tests/test_actions.py

@@ -1,14 +1,32 @@
 import uuid
 from fastapi.testclient import TestClient
+from pydantic import BaseModel
 import pytest
 import functools
 
+from labthings_fastapi.actions import ActionInfo
 from labthings_fastapi.testing import create_thing_without_server
 from .temp_client import poll_task, get_link
 from labthings_fastapi.example_things import MyThing
 import labthings_fastapi as lt
 
 
+class ActionMan(lt.Thing):
+    """A Thing with some actions"""
+
+    _direction: str = "centred"
+
+    @lt.action(response_timeout=0, retention_time=0)
+    def move_eyes(self, direction: str) -> None:
+        """Take one input and no outputs"""
+        self._direction = direction
+
+    @lt.action
+    def say_hello(self) -> str:
+        """Return a string."""
+        return "Hello World."
+
+
 @pytest.fixture
 def client():
     """Yield a client connected to a ThingServer"""
@@ -27,6 +45,38 @@ def run(payload=None):
     return run
 
 
+def test_action_info():
+    """Test the .actions descriptor works as expected."""
+    actions = ActionMan.actions
+    assert len(actions) == 2
+    assert set(actions) == {"move_eyes", "say_hello"}
+    assert actions.is_bound is False
+
+    move_eyes = ActionMan.actions["move_eyes"]
+    assert isinstance(move_eyes, ActionInfo)
+    assert move_eyes.name == "move_eyes"
+    assert move_eyes.description == "Take one input and no outputs"
+    assert set(move_eyes.input_model.model_fields) == {"direction"}
+    assert set(move_eyes.output_model.model_fields) == {"root"}  # rootmodel for None
+    assert issubclass(move_eyes.invocation_model, BaseModel)
+    assert move_eyes.response_timeout == 0
+    assert move_eyes.retention_time == 0
+    assert move_eyes.is_bound is False
+    assert callable(move_eyes.func)
+
+    # Try again with a bound one
+    action_man = create_thing_without_server(ActionMan)
+    assert len(action_man.actions) == 2
+    assert set(action_man.actions) == {"move_eyes", "say_hello"}
+    assert action_man.actions.is_bound is True
+
+    move_eyes = action_man.actions["move_eyes"]
+    assert isinstance(move_eyes, ActionInfo)
+    assert move_eyes.name == "move_eyes"
+    assert move_eyes.description == "Take one input and no outputs"
+    assert move_eyes.is_bound is True
+
+
 def test_get_action_invocations(client):
     """Test that running "get" on an action returns a list of invocations."""
     # When we start the action has no invocations