Standardise on :return: and :raise X:

Author: rwb27

src/labthings_fastapi/actions/__init__.py

@@ -224,7 +224,7 @@ def run(self) -> None:
 
         See `.Invocation.status` for status values.
 
-        :raises Exception: any exception raised in the action function will
+        :raise Exception: any exception raised in the action function will
             propagate through this method. Usually, this will just cause the
             thread to terminate after setting ``status`` to ``ERROR`` and
             saving the exception to ``self._exception``.
@@ -461,7 +461,7 @@ def action_invocation(
 
             :return: Details of the invocation.
 
-            :raises HTTPException: with code ``404`` if the invocation is not
+            :raise HTTPException: with code ``404`` if the invocation is not
                 found.
             """
             try:
@@ -500,7 +500,7 @@ def action_invocation_output(id: uuid.UUID, _blob_manager: BlobIOContextDep):
             :return: The output of the invocation, as a `pydantic.BaseModel`
                 instance. If this is a `.Blob`, it may be returned directly.
 
-            :raises HTTPException: with code ``404`` if the invocation is not
+            :raise HTTPException: with code ``404`` if the invocation is not
                 found.
             """
             with self._invocations_lock:
@@ -539,7 +539,7 @@ def delete_invocation(id: uuid.UUID) -> None:
 
             :param id: The unique ID of the invocation to cancel (from the URL).
 
-            :raises HTTPException: with code ``404`` if the invocation is not
+            :raise HTTPException: with code ``404`` if the invocation is not
                 found, or ``503`` if the invocation is not currently running.
             """
             with self._invocations_lock:

src/labthings_fastapi/client/__init__.py

@@ -50,8 +50,8 @@ def _get_link(obj: dict, rel: str) -> Mapping:
     :return: a dictionary representing the link. It should contain at least
         ``href`` and ``rel`` keys.
 
-    :raises ObjectHasNoLinksError: if there is no ``links`` item.
-    :raises KeyError: if there is no link with the specified ``rel`` value.
+    :raise ObjectHasNoLinksError: if there is no ``links`` item.
+    :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}.")
@@ -177,7 +177,7 @@ def invoke_action(self, path: str, **kwargs):
 
         :return: the output value of the action.
 
-        :raises RuntimeError: is raised if the action does not complete successfully.
+        :raise RuntimeError: is raised if the action does not complete successfully.
         """
         for k in kwargs.keys():
             if isinstance(kwargs[k], ClientBlobOutput):

src/labthings_fastapi/client/in_server.py

@@ -188,7 +188,7 @@ def add_action(
         the ``name`` in the supplied action descriptor.
     :param action: an `.ActionDescriptor` to be wrapped.
 
-    :raises DependencyNameClashError: if dependencies are inconsistent.
+    :raise DependencyNameClashError: if dependencies are inconsistent.
     """
 
     @wraps(action.func)

src/labthings_fastapi/dependencies/invocation.py

@@ -144,7 +144,7 @@ def raise_if_set(self):
             if cancel_event.is_set():
                 raise InvocationCancelledError()
 
-        :raises InvocationCancelledError: if the event has been cancelled.
+        :raise InvocationCancelledError: if the event has been cancelled.
         """
         if self.is_set():
             raise InvocationCancelledError("The action was cancelled.")
@@ -159,7 +159,7 @@ def sleep(self, timeout: float):
 
         :param timeout: The time to sleep for, in seconds.
 
-        :raises InvocationCancelledError: if the event has been cancelled.
+        :raise InvocationCancelledError: if the event has been cancelled.
         """
         if self.wait(timeout):
             raise InvocationCancelledError("The action was cancelled.")

src/labthings_fastapi/dependencies/thing_server.py

@@ -53,7 +53,7 @@ def find_thing_server(app: FastAPI) -> ThingServer:
 
     :return: the `.ThingServer` that owns the ``app``.
 
-    :raises RuntimeError: if there is no `.ThingServer` associated
+    :raise RuntimeError: if there is no `.ThingServer` associated
         with the current FastAPI application. This should only happen
         if this function is called on a `fastapi.FastAPI` instance
         that was not created by a `.ThingServer`.

src/labthings_fastapi/descriptors/action.py

@@ -201,7 +201,7 @@ def emit_changed_event(self, obj: Thing, status: str):
         :param obj: The `.Thing` on which the action is being observed.
         :param status: The status of the action, to be sent to observers.
 
-        :raises NotConnectedToServerError: if the Thing calling the action is not
+        :raise NotConnectedToServerError: if the Thing calling the action is not
             connected to a server with a running event loop.
         """
         try:

src/labthings_fastapi/descriptors/property.py

@@ -101,7 +101,7 @@ def __init__(
         :param getter: A function that gets the value of the property.
         :param setter: A function that sets the value of the property.
 
-        :raises ValueError: if the initial value or type are missing or incorrectly
+        :raise ValueError: if the initial value or type are missing or incorrectly
             specified.
         """
         if getter and initial_value is not None:
@@ -217,7 +217,7 @@ def emit_changed_event(self, obj: Thing, value: Any) -> None:
         :param obj: the `.Thing` to which we are attached.
         :param value: the new property value, to be sent to observers.
 
-        :raises NotConnectedToServerError: if the Thing that is calling the property
+        :raise NotConnectedToServerError: if the Thing that is calling the property
             update is not connected to a server with a running event loop.
         """
         runner = obj._labthings_blocking_portal

src/labthings_fastapi/example_things/__init__.py

@@ -125,15 +125,15 @@ class ThingWithBrokenAffordances(Thing):
     def broken_action(self):
         """Do something that raises an exception.
 
-        :raises RuntimeError: every time.
+        :raise RuntimeError: every time.
         """
         raise RuntimeError("This is a broken action")
 
     @thing_property
     def broken_property(self):
         """Raise an exception when the property is accessed.
 
-        :raises RuntimeError: every time.
+        :raise RuntimeError: every time.
         """
         raise RuntimeError("This is a broken property")
 
@@ -144,7 +144,7 @@ class ThingThatCantInstantiate(Thing):
     def __init__(self):
         """Fail to initialise.
 
-        :raises RuntimeError: every time.
+        :raise RuntimeError: every time.
         """
         raise RuntimeError("This thing can't be instantiated")
 
@@ -155,7 +155,7 @@ class ThingThatCantStart(Thing):
     def __enter__(self):
         """Fail to start the thing.
 
-        :raises RuntimeError: every time.
+        :raise RuntimeError: every time.
         """
         raise RuntimeError("This thing can't start")
 

src/labthings_fastapi/outputs/blob.py

@@ -228,7 +228,7 @@ def __init__(self, file_path: str, media_type: str, **kwargs):
             attributes. This may be used to stop temporary directories
             from being garbage collected while the `.Blob` exists.
 
-        :raises IOError: if the file specified does not exist.
+        :raise IOError: if the file specified does not exist.
         """
         if not os.path.exists(file_path):
             raise IOError("Tried to return a file that doesn't exist.")
@@ -348,10 +348,10 @@ def retrieve_data(self) -> Self:
 
         :return: the `.Blob` object (i.e. ``self``), after retrieving the data.
 
-        :raises ValueError: if the ``href`` is set as ``"blob://local"`` but
+        :raise ValueError: if the ``href`` is set as ``"blob://local"`` but
             the ``_data`` attribute has not been set. This happens when the
             `.Blob` is being constructed using `.Blob.from_bytes` or similar.
-        :raises LookupError: if the `.Blob` is being constructed from a URL
+        :raise LookupError: if the `.Blob` is being constructed from a URL
             and the URL does not correspond to a `.BlobData` instance that
             exists on this server (i.e. one that has been previously created
             and added to the `.BlobManager` as the result of a previous action).
@@ -389,7 +389,7 @@ def to_dict(self) -> Mapping[str, str]:
         :return: a JSON-serialisable dictionary with a URL that allows
             the `.Blob` to be downloaded from the `.BlobManager`.
 
-        :raises LookupError: if the context variable providing access to the
+        :raise LookupError: if the context variable providing access to the
             `.BlobManager` is not available. This usually means the `.Blob` is
             being serialised somewhere other than the output of an action.
         """
@@ -442,7 +442,7 @@ def data(self) -> ServerSideBlobData:
 
         :return: the data store wrapping data on disk or in memory.
 
-        :raises  ValueError: if there is no data stored on disk or in memory.
+        :raise  ValueError: if there is no data stored on disk or in memory.
         """
         if self._data is None:
             raise ValueError("This Blob has no data.")
@@ -583,7 +583,7 @@ class MyImageBlob(Blob):
 
     :return: a subclass of `.Blob` with the specified default media type.
 
-    :raises ValueError: if the media type contains ``'`` or ``\``.
+    :raise ValueError: if the media type contains ``'`` or ``\``.
     """
     if "'" in media_type or "\\" in media_type:
         raise ValueError("media_type must not contain single quotes or backslashes")
@@ -631,7 +631,7 @@ def add_blob(self, blob: ServerSideBlobData) -> uuid.UUID:
         :return: a unique ID identifying the data. This forms part of
             the URL to download the data.
 
-        :raises ValueError: if the `.ServerSideBlobData` object already
+        :raise ValueError: if the `.ServerSideBlobData` object already
             has an ``id`` attribute but is not in the dictionary of
             data. This suggests the object has been added to another
             `.BlobDataManager`, which should never happen.

src/labthings_fastapi/outputs/mjpeg_stream.py

@@ -230,7 +230,7 @@ async def next_frame(self) -> int:
 
         :return: the index of the next frame to arrive.
 
-        :raises StopAsyncIteration: if the stream has stopped.
+        :raise StopAsyncIteration: if the stream has stopped.
         """
         async with self.condition:
             await self.condition.wait()
@@ -317,7 +317,7 @@ def add_frame(self, frame: bytes, portal: BlockingPortal) -> None:
             The blocking portal may be obtained with a dependency, in
             `labthings_fastapi.dependencies.blocking_portal.BlockingPortal`.
 
-        :raises ValueError: if the supplied frame does not start with the JPEG
+        :raise ValueError: if the supplied frame does not start with the JPEG
             start bytes and end with the end bytes.
         """
         if not (