Docstring improvements in dependencies/action_manager

Author: rwb27

pyproject.toml

@@ -71,6 +71,7 @@ select = ["E4", "E7", "E9", "F", "D", "DOC"]
 ignore = [
     "D203",  # incompatible with D204
     "D213",  # incompatible with D212
+    "DOC402",  # doesn't work with sphinx-style docstrings, use pydoclint
     "DOC201",  # doesn't work with sphinx-style docstrings, use pydoclint
     "DOC501",  # doesn't work with sphinx-style docstrings, use pydoclint
     "DOC502",  # doesn't work with sphinx-style docstrings, use pydoclint

src/labthings_fastapi/dependencies/action_manager.py

@@ -1,36 +1,44 @@
-"""
-Context Var access to the Action Manager
+"""Context Var access to the Action Manager.
 
 This module provides a context var to access the Action Manager instance.
 While LabThings tries pretty hard to conform to FastAPI's excellent convention
 that everything should be passed as a parameter, there are some cases where
 that's hard. In particular, generating URLs when responses are serialised is
-difficult, because `pydantic` doesn't have a way to pass in extra context.
+difficult, because `pydantic` doesn't have a way to access the `fastapi.Request`
+object and use `fastapi.Request.url_for`.
+
+If an endpoint uses the `.ActionManagerDep` dependency, then the `.ActionManager`
+is supplied as an argument. More usefully, when the output is serialised the
+`.ActionManager` is available using `.ActionManagerContext.get()`.
 
-If an endpoint uses the `ActionManagerDep` dependency, then the Action Manager
-is available using `ActionManagerContext.get()`.
+This is currently only used by `.Blob` objects, as "serialising" a `.Blob`
+involves adding it to the `.ActionManager` and generating a download URL.
 """
 
 from __future__ import annotations
 
 from contextvars import ContextVar
 
-from typing import Annotated
+from typing import Annotated, AsyncGenerator
 from typing_extensions import TypeAlias
 from fastapi import Depends, Request
 from ..dependencies.thing_server import find_thing_server
 from ..actions import ActionManager
 
 
 def action_manager_from_thing_server(request: Request) -> ActionManager:
-    """Retrieve the Action Manager from the Thing Server
+    """Retrieve the Action Manager from the Thing Server.
+
+    This is for use as a FastAPI dependency. We use the ``request`` to
+    access the `.ThingServer` and thus access the `.ActionManager`.
 
-    This is for use as a FastAPI dependency, so the thing server is
-    retrieved from the request object.
+    :param request: the FastAPI request object. This will be supplied by
+        FastAPI when this function is used as a dependency.
+
+    :return: the `.ActionManager` object associated with our `.ThingServer`.
     """
     action_manager = find_thing_server(request.app).action_manager
-    if action_manager is None:
-        raise RuntimeError("Could not get the blocking portal from the server.")
+    assert action_manager is not None
     return action_manager
 
 
@@ -43,10 +51,19 @@ def action_manager_from_thing_server(request: Request) -> ActionManager:
 ActionManagerContext = ContextVar[ActionManager]("ActionManagerContext")
 
 
-async def make_action_manager_context_available(action_manager: ActionManagerDep):
-    """Make the Action Manager available in the context
+async def make_action_manager_context_available(
+    action_manager: ActionManagerDep,
+) -> AsyncGenerator[ActionManager]:
+    """Make the Action Manager available in the context variable.
+
+    The action manager may be accessed using `ActionManagerContext.get()` within
+    this context manager.
+
+    :param action_manager: The `.ActionManager` object. Note that this is an
+        annotated type so it will be supplied automatically when used as a FastAPI
+        dependency.
 
-    The action manager may be accessed using `ActionManagerContext.get()`.
+    :yield: the `.ActionManager` object.
     """
     ActionManagerContext.set(action_manager)
     yield action_manager