Stricter ruff

dev-requirements.txt

@@ -55,6 +55,10 @@ email-validator==2.2.0
     # via
     #   fastapi
     #   pydantic
+exceptiongroup==1.3.0
+    # via
+    #   anyio
+    #   pytest
 fastapi==0.116.1
     # via labthings-fastapi (pyproject.toml)
 fastapi-cli==0.0.8
@@ -160,9 +164,10 @@ pyflakes==3.4.0
 pygments==2.19.2
     # via
     #   flake8-rst-docstrings
+    #   pytest
     #   rich
     #   sphinx
-pytest==7.4.4
+pytest==8.4.1
     # via
     #   labthings-fastapi (pyproject.toml)
     #   pytest-cov
@@ -241,6 +246,14 @@ sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 starlette==0.47.1
     # via fastapi
+tomli==2.2.1
+    # via
+    #   coverage
+    #   flake8-pyproject
+    #   mypy
+    #   pydoclint
+    #   pytest
+    #   sphinx
 typer==0.16.0
     # via
     #   fastapi-cli
@@ -251,16 +264,20 @@ typing-extensions==4.14.1
     # via
     #   labthings-fastapi (pyproject.toml)
     #   anyio
+    #   astroid
+    #   exceptiongroup
     #   fastapi
     #   mypy
     #   pydantic
     #   pydantic-core
     #   pydantic-extra-types
     #   referencing
+    #   rich
     #   rich-toolkit
     #   starlette
     #   typer
     #   typing-inspection
+    #   uvicorn
 typing-inspection==0.4.1
     # via pydantic-settings
 ujson==5.10.0

docs/source/quickstart/counter.py

@@ -1,13 +1,15 @@
+"""An example Thing that implements a counter."""
+
 import time
 import labthings_fastapi as lt
 
 
 class TestThing(lt.Thing):
-    """A test thing with a counter property and a couple of actions"""
+    """A test thing with a counter property and a couple of actions."""
 
     @lt.thing_action
     def increment_counter(self) -> None:
-        """Increment the counter property
+        """Increment the counter property.
 
         This action doesn't do very much - all it does, in fact,
         is increment the counter (which may be read using the
@@ -17,13 +19,13 @@ def increment_counter(self) -> None:
 
     @lt.thing_action
     def slowly_increase_counter(self) -> None:
-        """Increment the counter slowly over a minute"""
+        """Increment the counter slowly over a minute."""
         for _i in range(60):
             time.sleep(1)
             self.increment_counter()
 
     counter: int = lt.property(default=0, readonly=True)
-    "A pointless counter"
+    "A pointless counter."
 
 
 if __name__ == "__main__":

docs/source/quickstart/counter_client.py

@@ -1,3 +1,5 @@
+"""Client code that interacts with the counter Thing over HTTP."""
+
 from labthings_fastapi import ThingClient
 
 counter = ThingClient.from_url("http://localhost:5000/counter/")

pyproject.toml

@@ -25,7 +25,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-  "pytest>=7.4.0, <8",
+  "pytest>=8.4.0",
   "pytest-cov",
   "pytest-mock",
   "mypy>=1.6.1, <2",
@@ -77,7 +77,20 @@ docstring-code-format = true
 
 [tool.ruff.lint]
 external = ["DOC401", "F824", "DOC101", "DOC103"]  # used via flake8/pydoclint
-select = ["B", "E4", "E7", "E9", "F", "D", "DOC"]
+select = [
+  "ANN",   # type annotations (ensuring they are present, complements mypy)
+  "ASYNC", # flake8 async rules
+  "B",     # flake8-bugbear
+  "BLE",   # don't catch Exception
+  "C4",    # flake8-comprehension rules
+  "E",     # flake8
+  "F",     # flake8
+  "FAST",  # FastAPI rules (mostly around dependencies)
+  "D",     # pydoclint (recommended by the developers over flake8 plugin)
+  "DOC",   # pydocstyle (limited support for sphinx style: see ignores)
+  "FAST",  # FastAPI rules
+  "S",     # flake8-bandit - notably, this disallows `assert`
+]
 ignore = [
     "D203",  # incompatible with D204
     "D213",  # incompatible with D212
@@ -88,16 +101,24 @@ ignore = [
     "B008",  # This disallows function calls in default values.
     # FastAPI Depends() breaks this rule, and FastAPI's response is "disable it".
     # see https://github.com/fastapi/fastapi/issues/1522
+    "ANN401",  # ANN401 disallows Any. There are quite a few places where Any is
+    # needed for dynamically typed code.
 ]
 preview = true
 
 [tool.ruff.lint.per-file-ignores]
 # Tests are currently not fully docstring-ed, we'll ignore this for now.
-"tests/*" = ["D", "DOC"]
+"tests/*" = [
+    "D",      # Tests are not yet fully covered by docstrings
+    "DOC",    # Tests are not yet fully covered by docstrings
+    "ANN",    # We don't require type hints in test code.
+    "S101",   # S101 disallows assert. That's not appropriate for tests.
+]
 # Typing tests do have docstrings, but it's not helpful to insist on imperative
 # mood etc.
 "typing_tests/*" = ["D404", "D401"]
-"docs/*" = ["D", "DOC"]
+# The docs config file is a python file, but doesn't conform to the usual rules.
+"docs/source/conf.py" = ["D", "DOC", "ANN"]
 
 [tool.ruff.lint.pydocstyle]
 # This lets the D401 checker understand that decorated thing properties and thing

src/labthings_fastapi/actions/__init__.py

@@ -78,7 +78,7 @@
         dependencies: Optional[dict[str, Any]] = None,
         log_len: int = 1000,
         cancel_hook: Optional[CancelHook] = None,
-    ):
+    ) -> None:
         """Create a thread to run an action and track its outputs.
 
         :param action: provides the function that we run, as well as metadata
@@ -142,8 +142,8 @@
         """
         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."
@@ -169,16 +169,30 @@
 
     @property
     def action(self) -> ActionDescriptor:
-        """The `.ActionDescriptor` object running in this thread."""
+        """The `.ActionDescriptor` object running in this thread.
+
+        :raises RuntimeError: if the action descriptor has been deleted.
+            This should never happen, as the descriptor is a property of
+            a class, which won't be deleted.
+        """
         action = self.action_ref()
-        assert action is not None, "The action for an `Invocation` has been deleted!"
+        if action is None:  # pragma: no cover
+            # Action descriptors should only be deleted after the server has
+            # stopped, so this error should never occur.
+            raise RuntimeError("The action for an `Invocation` has been deleted!")
         return action
 
     @property
     def thing(self) -> Thing:
-        """The `.Thing` to which the action is bound, i.e. this is ``self``."""
+        """The `.Thing` to which the action is bound, i.e. this is ``self``.
+
+        :raises RuntimeError: if the Thing no longer exists.
+        """
         thing = self.thing_ref()
-        assert thing is not None, "The `Thing` on which an action was run is missing!"
+        if thing is None:  # pragma: no cover
+            # this error block is primarily for mypy: the Thing will exist as
+            # long as the server is running, so we should never hit this error.
+            raise RuntimeError("The `Thing` on which an action was run is missing!")
         return thing
 
     def cancel(self) -> None:
@@ -250,6 +264,8 @@
         stored. The status is then set to ERROR and the thread terminates.
 
         See `.Invocation.status` for status values.
+
+        :raises RuntimeError: if there is no Thing associated with the invocation.
         """
         # self.action evaluates to an ActionDescriptor. This confuses mypy,
         # which thinks we are calling ActionDescriptor.__get__.
@@ -264,7 +280,11 @@
 
             thing = self.thing
             kwargs = model_to_dict(self.input)
-            assert thing is not None
+            if thing is None:  # pragma: no cover
+                # The Thing is stored as a weakref, but it will always exist
+                # while the server is running - this error should never
+                # occur.
+                raise RuntimeError("Cannot start an invocation without a Thing.")
 
             with self._status_lock:
                 self._status = InvocationStatus.RUNNING
@@ -312,7 +332,7 @@
         self,
         dest: MutableSequence,
         level: int = logging.INFO,
-    ):
+    ) -> None:
         """Set up a log handler that appends messages to a deque.
 
         .. warning::
@@ -412,8 +432,8 @@
         :param id: the unique ID of the action to retrieve.
         :return: the `.Invocation` object.
         """
         with self._invocations_lock:
             return self._invocations[id]
 
     def list_invocations(
         self,
@@ -541,8 +561,8 @@
             with self._invocations_lock:
                 try:
                     invocation: Any = self._invocations[id]
                 except KeyError as e:
                     raise HTTPException(
                         status_code=404,
                         detail="No action invocation found with ID {id}",
                     ) from e
@@ -555,7 +575,7 @@
                     invocation.output.response
                 ):
                     # TODO: honour "accept" header
                     return invocation.output.response()
                 return invocation.output
 
         @app.delete(
@@ -580,8 +600,8 @@
             with self._invocations_lock:
                 try:
                     invocation: Any = self._invocations[id]
                 except KeyError as e:
                     raise HTTPException(
                         status_code=404,
                         detail="No action invocation found with ID {id}",
                     ) from e

src/labthings_fastapi/base_descriptor.py

@@ -244,11 +244,16 @@ def name(self) -> str:
 
         The ``name`` of :ref:`wot_affordances` is used in their URL and in
         the :ref:`gen_docs` served by LabThings.
+
+        :raises DescriptorNotAddedToClassError: if ``__set_name__`` has not yet
+            been called.
         """
         self.assert_set_name_called()
-        assert self._name is not None
-        # The assert statement is mostly for typing: if assert_set_name_called
-        # doesn't raise an error, self._name has been set.
+        if self._name is None:  # pragma: no cover
+            raise DescriptorNotAddedToClassError("`_name` is not set.")
+        # The exception is mostly for typing: if `assert_set_name_called``
+        # doesn't raise an error, `BaseDescriptor.__set_name__` has been
+        # called and thus `self._name`` has been set.
         return self._name
 
     @property
@@ -297,10 +302,10 @@ def description(self) -> str | None:
     # I have ignored D105 (missing docstrings) on the overloads - these should not
     # exist on @overload definitions.
     @overload
-    def __get__(self, obj: Thing, type: type | None = None) -> Value: ...  # noqa: D105
+    def __get__(self, obj: Thing, type: type | None = None) -> Value: ...
 
     @overload
-    def __get__(self, obj: None, type: type) -> Self: ...  # noqa: D105
+    def __get__(self, obj: None, type: type) -> Self: ...
 
     def __get__(self, obj: Thing | None, type: type | None = None) -> Value | Self:
         """Return the value or the descriptor, as per `property`.
@@ -429,7 +434,6 @@ class Example:
         return {}
     # The line below parses the class to get a syntax tree.
     module_ast = ast.parse(textwrap.dedent(src))
-    assert isinstance(module_ast, ast.Module)
     class_def = module_ast.body[0]
     if not isinstance(class_def, ast.ClassDef):
         raise TypeError("The object supplied was not a class.")

src/labthings_fastapi/client/__init__.py

@@ -54,11 +54,11 @@
     :raise KeyError: if there is no link with the specified ``rel`` value.
     """
     if "links" not in obj:
         raise ObjectHasNoLinksError(f"Can't find any links on {obj}.")
     try:
         return next(link for link in obj["links"] if link["rel"] == rel)
     except StopIteration as e:
         raise KeyError(f"No link was found with rel='{rel}' on {obj}.") from e
 
 
 def invocation_href(invocation: dict) -> str:
@@ -121,7 +121,7 @@
         creates a subclass with the right attributes.
     """
 
-    def __init__(self, base_url: str, client: Optional[httpx.Client] = None):
+    def __init__(self, base_url: str, client: Optional[httpx.Client] = None) -> None:
         """Create a ThingClient connected to a remote Thing.
 
         :param base_url: the base URL of the Thing. This should be the URL
@@ -144,9 +144,9 @@
 
         :return: the property's value, as deserialised from JSON.
         """
         r = self.client.get(urljoin(self.path, path))
         r.raise_for_status()
         return r.json()
 
     def set_property(self, path: str, value: Any) -> None:
         """Make a PUT request to set the value of a property.
@@ -156,8 +156,8 @@
         :param value: the property's value. Currently this must be
             serialisable to JSON.
         """
         r = self.client.put(urljoin(self.path, path), json=value)
         r.raise_for_status()
 
     def invoke_action(self, path: str, **kwargs: Any) -> Any:
         r"""Invoke an action on the Thing.
@@ -207,7 +207,7 @@
                 )
             return invocation["output"]
         else:
             raise RuntimeError(f"Action did not complete successfully: {invocation}")
 
     def follow_link(self, response: dict, rel: str) -> httpx.Response:
         """Follow a link in a response object, by its `rel` attribute.

src/labthings_fastapi/client/in_server.py

@@ -54,7 +54,7 @@ class DirectThingClient:
     thing_path: str
     """The path to the Thing on the server. Relative to the server's base URL."""
 
-    def __init__(self, request: Request, **dependencies: Mapping[str, Any]):
+    def __init__(self, request: Request, **dependencies: Mapping[str, Any]) -> None:
         r"""Wrap a `.Thing` so it works like a `.ThingClient`.
 
         This class is designed to be used as a FastAPI dependency, and will
@@ -157,7 +157,7 @@ class DependencyNameClashError(KeyError):
     exception is raised.
     """
 
-    def __init__(self, name: str, existing: type, new: type):
+    def __init__(self, name: str, existing: type, new: type) -> None:
         """Create a DependencyNameClashError.
 
         See class docstring for an explanation of the error.

src/labthings_fastapi/client/outputs.py

@@ -35,7 +35,7 @@ class ClientBlobOutput:
 
     def __init__(
         self, media_type: str, href: str, client: Optional[httpx.Client] = None
-    ):
+    ) -> None:
         """Create a ClientBlobOutput to wrap a link to a downloadable file.
 
         :param media_type: the MIME type of the remote file.

src/labthings_fastapi/dependencies/action_manager.py

@@ -27,19 +27,17 @@
 
 
 def action_manager_from_thing_server(request: Request) -> ActionManager:
-    """Retrieve the Action Manager from the Thing Server.
+    r"""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`.
+    access the `.ThingServer` and thus access the `.ActionManager`\ .
 
     :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`.
+    :return: the `.ActionManager` object associated with our `.ThingServer`\ .
     """
-    action_manager = find_thing_server(request.app).action_manager
-    assert action_manager is not None
-    return action_manager
+    return find_thing_server(request.app).action_manager
 
 
 ActionManagerDep = Annotated[ActionManager, Depends(action_manager_from_thing_server)]

src/labthings_fastapi/dependencies/blocking_portal.py

@@ -28,6 +28,7 @@
 from fastapi import Depends, Request
 from anyio.from_thread import BlockingPortal as RealBlockingPortal
 from .thing_server import find_thing_server
+from ..exceptions import ServerNotRunningError
 
 
 def blocking_portal_from_thing_server(request: Request) -> RealBlockingPortal:
@@ -41,13 +42,20 @@ def blocking_portal_from_thing_server(request: Request) -> RealBlockingPortal:
 
     :return: the `anyio.from_thread.BlockingPortal` allowing access to the
         `.ThingServer`\ 's event loop.
+
+    :raises ServerNotRunningError: if the server does not have an available
+        blocking portal. This should not normally happen, as dependencies
+        are only evaluated while the server is running.
     """
     portal = find_thing_server(request.app).blocking_portal
-    assert portal is not None, RuntimeError(
-        "Could not get the blocking portal from the server."
-        # This should never happen, as the blocking portal is added
-        # and removed in `.ThingServer.lifecycle`.
-    )
+    if portal is None:  # pragma: no cover
+        raise ServerNotRunningError(
+            "Could not get the blocking portal from the server."
+            # This should never happen, as the blocking portal is added
+            # and removed in `.ThingServer.lifecycle`.
+            # As dependencies are only evaluated while the server is running,
+            # this error should never be raised.
+        )
     return portal
 
 

src/labthings_fastapi/dependencies/invocation.py

@@ -137,7 +137,7 @@ class CancelEvent(threading.Event):
     usually by a ``DELETE`` request to the invocation's URL.
     """
 
-    def __init__(self, id: InvocationID):
+    def __init__(self, id: InvocationID) -> None:
         """Initialise the cancellation event.
 
         :param id: The invocation ID, annotated as a dependency so it is