labthings-fastapi 0.0.14__tar.gz → 0.0.16__tar.gz

{labthings_fastapi-0.0.14 → labthings_fastapi-0.0.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labthings-fastapi
-Version: 0.0.14
+Version: 0.0.16
 Summary: An implementation of LabThings using FastAPI
 Project-URL: Homepage, https://github.com/labthings/labthings-fastapi
 Project-URL: Bug Tracker, https://github.com/labthings/labthings-fastapi/issues
@@ -35,6 +35,7 @@ Requires-Dist: sphinx-autoapi; extra == 'dev'
 Requires-Dist: sphinx-rtd-theme; extra == 'dev'
 Requires-Dist: sphinx-toolbox; extra == 'dev'
 Requires-Dist: sphinx>=7.2; extra == 'dev'
+Requires-Dist: tomli; (python_version < '3.11') and extra == 'dev'
 Requires-Dist: types-jsonschema; extra == 'dev'
 Description-Content-Type: text/markdown
 

{labthings_fastapi-0.0.14 → labthings_fastapi-0.0.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "labthings-fastapi"
-version = "0.0.14"
+version = "0.0.16"
 authors = [
   { name="Richard Bowman", email="richard.bowman@cantab.net" },
 ]
@@ -41,6 +41,7 @@ dev = [
   "sphinx>=7.2",
   "sphinx-autoapi",
   "sphinx-toolbox",
+  "tomli; python_version < '3.11'",
   "codespell",
 ]
 
@@ -171,5 +172,8 @@ check-return-types = false
 check-class-attributes = false  # prefer docstrings on the attributes
 check-yield-types = false  # use type annotations instead
 
+[tool.codespell]
+ignore-words-list = ["ser"]
+
 [project.scripts]
 labthings-server = "labthings_fastapi.server.cli:serve_from_cli"

{labthings_fastapi-0.0.14 → labthings_fastapi-0.0.16}/src/labthings_fastapi/actions.py

@@ -39,18 +39,21 @@ import weakref
 from fastapi import FastAPI, HTTPException, Request, Body, BackgroundTasks
 from pydantic import BaseModel, create_model
 
-from .base_descriptor import BaseDescriptor
+from .middleware.url_for import URLFor
+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
+from .invocations import InvocationModel, InvocationStatus
 from .dependencies.invocation import NonWarningInvocationID
 from .exceptions import (
     InvocationCancelledError,
     InvocationError,
-    NoBlobManagerError,
     NotConnectedToServerError,
 )
-from .outputs.blob import BlobIOContextDep, blobdata_to_url_ctx
 from . import invocation_contexts
 from .utilities.introspection import (
     EmptyInput,
@@ -149,28 +152,12 @@ class Invocation(Thread):
 
     @property
     def output(self) -> Any:
-        """Return value of the Action. If the Action is still running, returns None.
-
-        :raise NoBlobManagerError: If this is called in a context where the blob
-            manager context variables are not available. This stops errors being raised
-            later once the blob is returned and tries to serialise. If the errors
-            happen during serialisation the stack-trace will not clearly identify
-            the route with the missing dependency.
-        """
-        try:
-            blobdata_to_url_ctx.get()
-        except LookupError as e:
-            raise NoBlobManagerError(
-                "An invocation output has been requested from a api route that "
-                "doesn't have a BlobIOContextDep dependency. This dependency is needed "
-                " for blobs to identify their url."
-            ) from e
-
+        """Return value of the Action. If the Action is still running, returns None."""
         with self._status_lock:
             return self._return_value
 
     @property
-    def log(self) -> list[LogRecordModel]:
+    def log(self) -> list[logging.LogRecord]:
         """A list of log items generated by the Action."""
         with self._status_lock:
             return list(self._log)
@@ -225,33 +212,28 @@ class Invocation(Thread):
         """
         self.cancel_hook.set()
 
-    def response(self, request: Optional[Request] = None) -> InvocationModel:
+    def response(self) -> InvocationModel:
         """Generate a representation of the invocation suitable for HTTP.
 
         When an invocation is polled, we return a JSON object that includes
         its status, any log entries, a return value (if completed), and a link
         to poll for updates.
 
-        :param request: is used to generate the ``href`` in the response, which
-            should retrieve an updated version of this response.
-
         :return: an `.InvocationModel` representing this `.Invocation`.
         """
-        if request:
-            href = str(request.url_for("action_invocation", id=self.id))
-        else:
-            href = f"{ACTION_INVOCATIONS_PATH}/{self.id}"
         links = [
-            LinkElement(rel="self", href=href),
-            LinkElement(rel="output", href=href + "/output"),
+            LinkElement(rel="self", href=URLFor("action_invocation", id=self.id)),
+            LinkElement(
+                rel="output", href=URLFor("action_invocation_output", id=self.id)
+            ),
         ]
         # The line below confuses MyPy because self.action **evaluates to** a Descriptor
         # object (i.e. we don't call __get__ on the descriptor).
-        return self.action.invocation_model(  # type: ignore[call-overload]
+        return self.action.invocation_model(  # type: ignore[attr-defined]
             status=self.status,
             id=self.id,
-            action=self.thing.path + self.action.name,  # type: ignore[call-overload]
-            href=href,
+            action=self.thing.path + self.action.name,  # type: ignore[attr-defined]
+            href=URLFor("action_invocation", id=self.id),
             timeStarted=self._start_time,
             timeCompleted=self._end_time,
             timeRequested=self._request_time,
@@ -290,7 +272,7 @@ class Invocation(Thread):
         """
         # self.action evaluates to an ActionDescriptor. This confuses mypy,
         # which thinks we are calling ActionDescriptor.__get__.
-        action: ActionDescriptor = self.action  # type: ignore[call-overload]
+        action: ActionDescriptor = self.action  # type: ignore[assignment]
         logger = self.thing.logger
         # The line below saves records matching our ID to ``self._log``
         add_thing_log_destination(self.id, self._log)
@@ -442,13 +424,10 @@ class ActionManager:
         :return: A list of invocations, optionally filtered by Thing and/or Action.
         """
         return [
-            i.response(request=request)
+            i.response()
             for i in self.invocations
             if thing is None or i.thing == thing
-            if action is None or i.action == action  # type: ignore[call-overload]
-            # i.action evaluates to an ActionDescriptor, which confuses mypy - it
-            # thinks we are calling ActionDescriptor.__get__ but this isn't ever
-            # called.
+            if action is None or i.action == action
         ]
 
     def expire_invocations(self) -> None:
@@ -470,25 +449,19 @@ class ActionManager:
         """
 
         @app.get(ACTION_INVOCATIONS_PATH, response_model=list[InvocationModel])
-        def list_all_invocations(
-            request: Request, _blob_manager: BlobIOContextDep
-        ) -> list[InvocationModel]:
+        def list_all_invocations(request: Request) -> list[InvocationModel]:
             return self.list_invocations(request=request)
 
         @app.get(
             ACTION_INVOCATIONS_PATH + "/{id}",
             responses={404: {"description": "Invocation ID not found"}},
         )
-        def action_invocation(
-            id: uuid.UUID, request: Request, _blob_manager: BlobIOContextDep
-        ) -> InvocationModel:
+        def action_invocation(id: uuid.UUID, request: Request) -> InvocationModel:
             """Return a description of a specific action.
 
             :param id: The action's ID (from the path).
             :param request: FastAPI dependency for the request object, used to
                 find URLs via ``url_for``.
-            :param _blob_manager: FastAPI dependency that enables `.Blob` objects
-                to be serialised.
 
             :return: Details of the invocation.
 
@@ -497,7 +470,7 @@ class ActionManager:
             """
             try:
                 with self._invocations_lock:
-                    return self._invocations[id].response(request=request)
+                    return self._invocations[id].response()
             except KeyError as e:
                 raise HTTPException(
                     status_code=404,
@@ -518,17 +491,13 @@ class ActionManager:
                 503: {"description": "No result is available for this invocation"},
             },
         )
-        def action_invocation_output(
-            id: uuid.UUID, _blob_manager: BlobIOContextDep
-        ) -> Any:
+        def action_invocation_output(id: uuid.UUID) -> Any:
             """Get the output of an action invocation.
 
             This returns just the "output" component of the action invocation. If the
             output is a file, it will return the file.
 
             :param id: The action's ID (from the path).
-            :param _blob_manager: FastAPI dependency that enables `.Blob` objects
-                to be serialised.
 
             :return: The output of the invocation, as a `pydantic.BaseModel`
                 instance. If this is a `.Blob`, it may be returned directly.
@@ -625,8 +594,56 @@ ActionReturn = TypeVar("ActionReturn")
 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[Callable[ActionParams, ActionReturn]],
+    BaseDescriptor[OwnerT, Callable[ActionParams, ActionReturn]],
     Generic[ActionParams, ActionReturn, OwnerT],
 ):
     """Wrap actions to enable them to be run over HTTP.
@@ -691,7 +708,7 @@ class ActionDescriptor(
         )
         self.invocation_model.__name__ = f"{name}_invocation"
 
-    def __set_name__(self, owner: type[Thing], name: str) -> None:
+    def __set_name__(self, owner: type[OwnerT], name: str) -> None:
         """Ensure the action name matches the function name.
 
         It's assumed in a few places that the function name and the
@@ -709,7 +726,7 @@ class ActionDescriptor(
                 f"'{self.func.__name__}'",
             )
 
-    def instance_get(self, obj: Thing) -> Callable[ActionParams, ActionReturn]:
+    def instance_get(self, obj: OwnerT) -> Callable[ActionParams, ActionReturn]:
         """Return the function, bound to an object as for a normal method.
 
         This currently doesn't validate the arguments, though it may do so
@@ -721,10 +738,7 @@ class ActionDescriptor(
             descriptor.
         :return: the action function, bound to ``obj``.
         """
-        # `obj` should be of type `OwnerT`, but `BaseDescriptor` currently
-        # isn't generic in the type of the owning Thing, so we can't express
-        # that here.
-        return partial(self.func, obj)  # type: ignore[arg-type]
+        return partial(self.func, obj)
 
     def _observers_set(self, obj: Thing) -> WeakSet:
         """Return a set used to notify changes.
@@ -806,8 +820,6 @@ class ActionDescriptor(
         # The solution below is to manually add the annotation, before passing
         # the function to the decorator.
         def start_action(
-            _blob_manager: BlobIOContextDep,
-            request: Request,
             body: Any,  # This annotation will be overwritten below.
             id: NonWarningInvocationID,
             background_tasks: BackgroundTasks,
@@ -822,7 +834,7 @@ class ActionDescriptor(
                 id=id,
             )
             background_tasks.add_task(action_manager.expire_invocations)
-            return action.response(request=request)
+            return action.response()
 
         if issubclass(self.input_model, EmptyInput):
             annotation = Body(default_factory=StrictEmptyInput)
@@ -884,7 +896,7 @@ class ActionDescriptor(
             ),
             summary=f"All invocations of {self.name}.",
         )
-        def list_invocations(_blob_manager: BlobIOContextDep) -> list[InvocationModel]:
+        def list_invocations() -> list[InvocationModel]:
             action_manager = thing._thing_server_interface._action_manager
             return action_manager.list_invocations(self, thing)
 
@@ -920,6 +932,18 @@ class ActionDescriptor(
             output=type_to_dataschema(self.output_model, title=f"{self.name}_output"),
         )
 
+    def descriptor_info(self, owner: OwnerT | None = None) -> ActionInfo:
+        r"""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.
+
+        :param owner: The owning object, or `None` to return an unbound `.ActionInfo`\ .
+        :return: An `.ActionInfo` object describing this Action.
+        """
+        return self._descriptor_info(ActionInfo, owner)
+
 
 @overload
 def action(