labthings-fastapi 0.1.0__tar.gz → 0.2.0__tar.gz

{labthings_fastapi-0.1.0 → labthings_fastapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labthings-fastapi
-Version: 0.1.0
+Version: 0.2.0
 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
@@ -15,7 +15,7 @@ Requires-Dist: fastapi[all]~=0.135.0
 Requires-Dist: httpx
 Requires-Dist: jsonschema
 Requires-Dist: numpy>=1.20
-Requires-Dist: pydantic~=2.12
+Requires-Dist: pydantic~=2.13
 Requires-Dist: typing-extensions
 Requires-Dist: zeroconf>=0.28.0
 Provides-Extra: dev
@@ -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: sphobjinv; 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.1.0 → labthings_fastapi-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "labthings-fastapi"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
   { name="Richard Bowman", email="richard.bowman@cantab.net" },
 ]
@@ -13,7 +13,7 @@ classifiers = [
   "Operating System :: OS Independent",
 ]
 dependencies = [
-  "pydantic ~= 2.12",
+  "pydantic ~= 2.13",
   "numpy>=1.20",
   "jsonschema",
   "typing_extensions",
@@ -41,6 +41,7 @@ dev = [
   "sphinx>=7.2",
   "sphinx-autoapi",
   "sphinx-toolbox",
+  "sphobjinv",
   "tomli; python_version < '3.11'",
   "codespell",
 ]
@@ -73,6 +74,18 @@ addopts = [
 markers = [
     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
 ]
+filterwarnings = [
+    # This deliberately doesn't filter by class, because doing so confuses
+    # coverage - it results in labthings_fastapi being imported before
+    # the coverage plugin.
+    # Instead, we simply filter by message.
+    #
+    # There are many, many small Thing definitions in the test suite.
+    # These don't all opt in to new features for reasons of brevity: the
+    # DeprecationWarnings this would generate are unhelpful, so we suppress them
+    # with the line below.
+    "ignore:.get_validate_properties_on_set. will become .True. by default:DeprecationWarning",
+]
 
 [tool.ruff]
 target-version = "py310"

{labthings_fastapi-0.1.0 → labthings_fastapi-0.2.0}/src/labthings_fastapi/__init__.py

@@ -13,15 +13,21 @@ imports and is intended to be imported using:
 
     import labthings_fastapi as lt
 
+
+The most important symbols are described in `lt` with links to the full API
+documentation as appropriate.
+
 The example code elsewhere in the documentation generally follows this
 convention. Symbols in the top-level module mostly exist elsewhere in
 the package, but should be imported from here as a preference, to ensure
 code does not break if modules are rearranged.
+
 """
 
 from .thing import Thing
 from .thing_slots import thing_slot
 from .thing_server_interface import ThingServerInterface
+from .thing_class_settings import ThingClassSettings
 from .properties import property, setting, DataProperty, DataSetting
 from .actions import action
 from .endpoints import endpoint
@@ -45,6 +51,7 @@ from .invocation_contexts import (
 __all__ = [
     "Thing",
     "ThingServerInterface",
+    "ThingClassSettings",
     "property",
     "setting",
     "DataProperty",

{labthings_fastapi-0.1.0 → labthings_fastapi-0.2.0}/src/labthings_fastapi/actions.py

@@ -1,6 +1,6 @@
 """Actions module.
 
-:ref:`actions` are represented by methods, decorated with the `.action`
+:ref:`actions` are represented by methods, decorated with the `lt.action`
 decorator.
 
 See the :ref:`actions` documentation for a top-level overview of actions in
@@ -9,16 +9,18 @@ LabThings-FastAPI.
 Developer notes
 ---------------
 
-Currently much of the code related to Actions is in `.action` and the
+Currently much of the code related to Actions is in `lt.action` and the
 underlying `.ActionDescriptor`. This is likely to be refactored in the near
 future.
 """
 
 from __future__ import annotations
+from collections.abc import Iterator
+from contextlib import contextmanager
 import datetime
 import logging
 from collections import deque
-from functools import partial
+from functools import partial, wraps
 import inspect
 from threading import Thread, Lock
 import uuid
@@ -29,6 +31,7 @@ from typing import (
     Callable,
     Concatenate,
     Generic,
+    Literal,
     Optional,
     ParamSpec,
     TypeVar,
@@ -36,9 +39,10 @@ from typing import (
 )
 from weakref import WeakSet
 import weakref
-from fastapi import FastAPI, HTTPException, Request, Body, BackgroundTasks
+from fastapi import APIRouter, FastAPI, HTTPException, Request, Body, BackgroundTasks
 from pydantic import BaseModel, create_model
 
+
 from .middleware.url_for import URLFor
 from .base_descriptor import (
     BaseDescriptor,
@@ -49,6 +53,7 @@ from .logs import add_thing_log_destination
 from .utilities import model_to_dict, wrap_plain_types_in_rootmodel
 from .invocations import InvocationModel, InvocationStatus
 from .exceptions import (
+    GlobalLockBusyError,
     InvocationCancelledError,
     InvocationError,
     NotConnectedToServerError,
@@ -71,7 +76,7 @@ if TYPE_CHECKING:
     from .thing import Thing
 
 
-__all__ = ["ACTION_INVOCATIONS_PATH", "Invocation", "ActionManager"]
+__all__ = ["Invocation", "ActionManager"]
 
 
 ACTION_INVOCATIONS_PATH = "/action_invocations"
@@ -84,7 +89,7 @@ class Invocation(Thread):
     `.Invocation` threads add several bits of functionality compared to the base
     `threading.Thread`.
 
-    * They are instantiated with an `.ActionDescriptor` and a `.Thing`
+    * They are instantiated with an `.ActionDescriptor` and a `~lt.Thing`
       rather than a target function (see ``__init__``).
     * Each invocation is assigned a unique ``ID`` to allow it to be polled
       over HTTP.
@@ -105,7 +110,7 @@ class Invocation(Thread):
 
         :param action: provides the function that we run, as well as metadata
             and type information. The descriptor is not bound to an object, so we
-            supply the `.Thing` it's bound to when the function is run.
+            supply the `~lt.Thing` it's bound to when the function is run.
         :param thing: is the object on which we are running the ``action``, i.e.
             it is supplied to the function wrapped by ``action`` as the ``self``
             argument.
@@ -187,7 +192,7 @@ class Invocation(Thread):
 
     @property
     def thing(self) -> Thing:
-        """The `.Thing` to which the action is bound, i.e. this is ``self``.
+        """The `~lt.Thing` to which the action is bound, i.e. this is ``self``.
 
         :raises RuntimeError: if the Thing no longer exists.
         """
@@ -250,7 +255,7 @@ class Invocation(Thread):
 
         The code to be run is the function wrapped in the `.ActionDescriptor`
         that is passed in as ``action``. Its arguments are the associated
-        `.Thing` (the first argument, i.e. ``self``), the ``input`` model
+        `~lt.Thing` (the first argument, i.e. ``self``), the ``input`` model
         (split into keyword arguments for each field), and any ``dependencies``
         (also as keyword arguments).
 
@@ -287,19 +292,22 @@ class Invocation(Thread):
                     # occur.
                     raise RuntimeError("Cannot start an invocation without a Thing.")
 
-                with self._status_lock:
-                    self._status = InvocationStatus.RUNNING
-                    self._start_time = datetime.datetime.now()
-                    action.emit_changed_event(self.thing, self._status.value)
+                # The action's `context_for_func` context manager will acquire the
+                # global lock if needed.
+                with action.context_for_func(thing):
+                    with self._status_lock:
+                        self._status = InvocationStatus.RUNNING
+                        self._start_time = datetime.datetime.now()
+                        action.emit_changed_event(self.thing, self._status.value)
 
-                bound_method = action.__get__(thing)
-                # Actually run the action
-                ret = bound_method(**kwargs, **self.dependencies)
+                    # Actually run the action
+                    ret = action.func(thing, **kwargs, **self.dependencies)
+
+                    with self._status_lock:
+                        self._return_value = ret
+                        self._status = InvocationStatus.COMPLETED
+                        action.emit_changed_event(self.thing, self._status.value)
 
-                with self._status_lock:
-                    self._return_value = ret
-                    self._status = InvocationStatus.COMPLETED
-                    action.emit_changed_event(self.thing, self._status.value)
             except InvocationCancelledError:
                 logger.info(f"Invocation {self.id} was cancelled.")
                 with self._status_lock:
@@ -308,9 +316,17 @@ class Invocation(Thread):
             except Exception as e:  # skipcq: PYL-W0703
                 # First log
                 if isinstance(e, InvocationError):
-                    # Log without traceback
+                    # Log without traceback for anticipated errors
                     logger.error(e)
+                elif (
+                    isinstance(e, GlobalLockBusyError)
+                    and self._status == InvocationStatus.PENDING
+                ):
+                    # The global lock timed out before the function started.
+                    # In this case, don't print a traceback.
+                    logger.warning(f"Global lock was busy: didn't run {action.name}.")
                 else:
+                    # Other exceptions show up in the log with a traceback
                     logger.exception(e)
                 # Then set status
                 with self._status_lock:
@@ -360,7 +376,7 @@ class ActionManager:
 
         :param action: provides the function that we run, as well as metadata
             and type information. The descriptor is not bound to an object, so we
-            supply the `.Thing` it's bound to when the function is run.
+            supply the `~lt.Thing` it's bound to when the function is run.
         :param thing: is the object on which we are running the ``action``, i.e.
             it is supplied to the function wrapped by ``action`` as the ``self``
             argument.
@@ -407,8 +423,8 @@ class ActionManager:
         :param action: filters out only the invocations of a particular
             `.ActionDescriptor`. Note that if there are two Things
             of the same subclass, filtering by action will return invocations
-            on either `.Thing`.
-        :param thing: returns only invocations of actions on a particular `.Thing`.
+            on either `~lt.Thing`.
+        :param thing: returns only invocations of actions on a particular `~lt.Thing`.
             This will often be combined with filtering by ``action`` to give the
             list of invocations returned by a GET request on an action endpoint.
         :param request: is used to pass a `fastapi.Request` object to the
@@ -438,17 +454,18 @@ class ActionManager:
             for k in to_delete:
                 del self._invocations[k]
 
-    def attach_to_app(self, app: FastAPI) -> None:
-        """Add /action_invocations and /action_invocation/{id} endpoints to FastAPI.
+    def router(self) -> APIRouter:
+        """Create a FastAPI Router with action-related endpoints.
 
-        :param app: The `fastapi.FastAPI` application to which we add the endpoints.
+        :return: a Router with all action-related endpoints.
         """
+        router = APIRouter()
 
-        @app.get(ACTION_INVOCATIONS_PATH, response_model=list[InvocationModel])
+        @router.get(ACTION_INVOCATIONS_PATH, response_model=list[InvocationModel])
         def list_all_invocations(request: Request) -> list[InvocationModel]:
             return self.list_invocations(request=request)
 
-        @app.get(
+        @router.get(
             ACTION_INVOCATIONS_PATH + "/{id}",
             responses={404: {"description": "Invocation ID not found"}},
         )
@@ -473,7 +490,7 @@ class ActionManager:
                     detail="No action invocation found with ID {id}",
                 ) from e
 
-        @app.get(
+        @router.get(
             ACTION_INVOCATIONS_PATH + "/{id}/output",
             response_model=Any,
             responses={
@@ -521,7 +538,7 @@ class ActionManager:
                     return invocation.output.response()
                 return invocation.output
 
-        @app.delete(
+        @router.delete(
             ACTION_INVOCATIONS_PATH + "/{id}",
             response_model=None,
             responses={
@@ -561,6 +578,8 @@ class ActionManager:
                     )
                 invocation.cancel()
 
+        return router
+
 
 ACTION_POST_NOTICE = """
 ## Important note
@@ -651,9 +670,9 @@ class ActionDescriptor(
     .. note::
         Descriptors are instantiated once per class. This means that we cannot
         assume there is only one action corresponding to this descriptor: there
-        may be multiple `.Thing` instances with the same descriptor. That is
-        why the host `.Thing` must be passed to many functions as an argument,
-        and why observers, for example, must be keyed by the `.Thing` rather
+        may be multiple `~lt.Thing` instances with the same descriptor. That is
+        why the host `~lt.Thing` must be passed to many functions as an argument,
+        and why observers, for example, must be keyed by the `~lt.Thing` rather
         than kept as a property of ``self``.
     """
 
@@ -662,10 +681,11 @@ class ActionDescriptor(
         func: Callable[Concatenate[OwnerT, ActionParams], ActionReturn],
         response_timeout: float = 1,
         retention_time: float = 300,
+        use_global_lock: Literal[False] | None = None,
     ) -> None:
-        """Create a new action descriptor.
+        r"""Create a new action descriptor.
 
-        The action descriptor wraps a method of a `.Thing`. It may still be
+        The action descriptor wraps a method of a `~lt.Thing`. It may still be
         called from Python in the same way, but it will also be added to the
         HTTP API and automatic documentation.
 
@@ -680,6 +700,16 @@ class ActionDescriptor(
             of the action.
         :param retention_time: how long, in seconds, the action should be kept
             for after it has completed.
+        :param use_global_lock: If the global lock is enabled,
+            this parameter may be used to opt out. See :ref:`global_locking`
+            for details of how the global lock is implemented.
+
+            If this parameter is `False` then the lock will not be acquired, even
+            if global locking is enabled. That is appropriate if the action does
+            not have side effects that would cause problems for other actions, or
+            if more nuanced locking behaviour is required meaning the lock is
+            acquired directly in the action code, for example using
+            `~lt.ThingServerInterface.hold_global_lock`\ .
         """
         super().__init__()
         self.func = func
@@ -689,6 +719,7 @@ class ActionDescriptor(
         name = func.__name__  # this is checked in __set_name__
         self.response_timeout = response_timeout
         self.retention_time = retention_time
+        self.use_global_lock = use_global_lock
         self.dependency_params = fastapi_dependency_params(func)
         self.input_model = input_model_from_signature(
             func,
@@ -722,28 +753,78 @@ class ActionDescriptor(
                 f"'{self.func.__name__}'",
             )
 
+    @contextmanager
+    def context_for_func(self, obj: OwnerT) -> Iterator[None]:
+        """Create the context in which ``func`` runs.
+
+        Currently, if global locking is enabled and this action hasn't opted out,
+        this context manager will hold the global lock for the duration of the
+        action.
+
+        This method is intended to create a hook for pre-run set-up and post-run
+        clean-up code that may be customised by `Thing` implementations in the future,
+        such as acquiring locks or other resources.
+
+        When an action is run from Python code as ``thing.action()`` this context
+        manager is entered before executing `func` bound to the `Thing` instance.
+
+        When an action is run from HTTP, this context manager is entered while the
+        action's status is ``pending`` and the status changes to ``running`` just
+        before `func` (the function decorated by `~lt.action`) runs. This allows
+        some slightly nicer error handling, for example not cluttering the log with
+        stack traces if an action can't start because the global lock is in use.
+
+        :param obj: The object on which the method is being called.
+        :return: the function, wrapped if necessary.
+        """
+        with obj._thing_server_interface._optionally_hold_global_lock(
+            self.use_global_lock
+        ):
+            yield
+
     def instance_get(self, obj: OwnerT) -> Callable[ActionParams, ActionReturn]:
-        """Return the function, bound to an object as for a normal method.
+        """Return the function, bound to an object and wrapped in a context manager.
+
+        Accessing a regular Python method returns the method bound to the instance,
+        i.e. the `self` argument is supplied.
 
-        This currently doesn't validate the arguments, though it may do so
-        in future. In its present form, this is equivalent to a regular
-        Python method, i.e. all we do is supply the first argument, `self`.
+        LabThings Actions work the same way, but they also wrap the function in a
+        context manager. Currently, this context manager will handle acquiring the
+        global lock if required.
 
-        :param obj: the `.Thing` to which we are attached. This will be
+        If locking is disabled, the context manager does nothing.
+        If locking is enabled, we return a wrapped function that holds the
+        global lock while the action runs.
+
+        .. note::
+
+            The returned function will hold a reference to both `obj` and `self`
+            (this descriptor). Given that accessing ``instance.method`` returns
+            a function that's already bound to the instance, this shouldn't cause
+            any problems.
+
+        :param obj: the `~lt.Thing` to which we are attached. This will be
             the first argument supplied to the function wrapped by this
             descriptor.
         :return: the action function, bound to ``obj``.
         """
-        return partial(self.func, obj)
+
+        @wraps(self.func)
+        def wrapped(*args: Any, **kwargs: Any) -> Any:  # noqa: DOC
+            """Acquire the lock then run `func` with supplied arguments."""
+            with self.context_for_func(obj):
+                return self.func(*args, **kwargs)
+
+        return partial(wrapped, obj)
 
     def _observers_set(self, obj: Thing) -> WeakSet:
         """Return a set used to notify changes.
 
-        Note that we need to supply the `.Thing` we are looking at, as in
+        Note that we need to supply the `~lt.Thing` we are looking at, as in
         general there may be more than one object of the same type, and
         descriptor instances are shared between all instances of their class.
 
-        :param obj: The `.Thing` on which the action is being observed.
+        :param obj: The `~lt.Thing` on which the action is being observed.
 
         :return: a weak set of callables to notify on changes to the action.
             This is used by websocket endpoints.
@@ -762,7 +843,7 @@ class ActionDescriptor(
         portal. Async code must not use the blocking portal as it can deadlock
         the event loop.
 
-        :param obj: The `.Thing` on which the action is being observed.
+        :param obj: The `~lt.Thing` on which the action is being observed.
         :param status: The status of the action, to be sent to observers.
         """
         obj._thing_server_interface.start_async_task_soon(
@@ -778,10 +859,10 @@ class ActionDescriptor(
         It will send messages to each observer to notify them that something
         has changed.
 
-        :param obj: The `.Thing` on which the action is defined.
+        :param obj: The `~lt.Thing` on which the action is defined.
             `.ActionDescriptor` objects are unique to the class, but there may
-            be more than one `.Thing` attached to a server with the same class.
-            We use ``obj`` to look up the observers of the current `.Thing`.
+            be more than one `~lt.Thing` attached to a server with the same class.
+            We use ``obj`` to look up the observers of the current `~lt.Thing`.
         :param value: The action status to communicate to the observers.
         """
         action_name = self.name
@@ -801,12 +882,12 @@ class ActionDescriptor(
         application.
 
         :param app: The `fastapi.FastAPI` app to add the endpoint to.
-        :param thing: The `.Thing` to which the action is attached. Bear in
-            mind that the descriptor may be used by more than one `.Thing`,
+        :param thing: The `~lt.Thing` to which the action is attached. Bear in
+            mind that the descriptor may be used by more than one `~lt.Thing`,
             so this can't be a property of the descriptor.
 
         :raises NotConnectedToServerError: if the function is run before the
-            ``thing`` has a ``path`` property. This is assigned when the `.Thing`
+            ``thing`` has a ``path`` property. This is assigned when the `~lt.Thing`
             is added to a server.
         """
 
@@ -901,15 +982,15 @@ class ActionDescriptor(
 
         This function describes the Action in :ref:`wot_td` format.
 
-        :param thing: The `.Thing` to which the action is attached.
+        :param thing: The `~lt.Thing` to which the action is attached.
         :param path: The prefix applied to all endpoints associated with the
-            `.Thing`. This is the URL for the Thing Description. If it is
+            `~lt.Thing`. This is the URL for the Thing Description. If it is
             omitted, we use the ``path`` property of the ``thing``.
 
         :return: An `.ActionAffordance` describing this action.
 
         :raises NotConnectedToServerError: if the function is run before the
-            ``thing`` has a ``path`` property. This is assigned when the `.Thing`
+            ``thing`` has a ``path`` property. This is assigned when the `~lt.Thing`
             is added to a server.
         """
         path = path or thing.path
@@ -968,7 +1049,7 @@ def action(
         ActionDescriptor[ActionParams, ActionReturn, OwnerT],
     ]
 ):
-    r"""Mark a method of a `.Thing` as a LabThings Action.
+    r"""Mark a method of a `~lt.Thing` as a LabThings Action.
 
     Methods decorated with :deco:`action` will be available to call
     over HTTP as actions. See :ref:`actions` for an introduction to the concept