Improved docstrings

Author: kzscisoft

simvue/api/objects/events.py

@@ -108,6 +108,11 @@ def get(
         -------
         Generator[EventSet]
 
+        Raises
+        ------
+        RuntimeError
+            if the expected 'data' key was not found in server response
+
         """
         _class_instance = cls(_read_only=True, _local=True)
         _count: int = 0
@@ -191,6 +196,16 @@ def histogram(
         window: int,
         filters: list[str] | None,
     ) -> list[dict[str, str | int]]:
+        """Retrieve events as a histogram.
+
+        Parameters
+        ----------
+        timestamp_begin : datetime.datetime
+            start point for event time range
+        timestamp_end : datetime.datetime
+            end point for event time range
+
+        """
         if timestamp_end - timestamp_begin <= datetime.timedelta(seconds=window):
             raise ValueError(
                 "Invalid arguments for datetime range, "

simvue/api/objects/folder.py

@@ -326,6 +326,23 @@ def _set_favourite(self, *, starred: bool) -> dict:
 def get_folder_from_path(
     path: typing.Annotated[str, pydantic.Field(pattern=FOLDER_REGEX)],
 ) -> Folder:
+    """Retrieve a folder from its path.
+
+    Parameters
+    ----------
+    path : str
+        folder path on server
+
+    Returns
+    -------
+    Folder
+        object representing folder on the server
+
+    Raises
+    ------
+    ObjectNotFoundError
+        if no match was found for this path
+    """
     _folders = Folder.get(filters=json.dumps([f"path == {path}"]), count=1)
 
     if not (_first_entry := next(_folders, None)):

simvue/api/objects/grids.py

@@ -39,18 +39,34 @@
 
 
 def check_ordered_array(
-    axis_ticks: list[list[float]] | np.ndarray,
+    array: list[list[float]] | np.ndarray,
 ) -> list[list[float]]:
-    """Returns if array is ordered or reverse ordered."""
-    if isinstance(axis_ticks, np.ndarray):
-        axis_ticks = axis_ticks.tolist()
-    for i, array in enumerate(axis_ticks):
+    """Returns if a 2D array is ordered or reverse ordered.
+
+    Parameters
+    ----------
+    array : list[list[float]] | np.ndarray
+        array to check for ordering
+
+    Returns
+    -------
+    list[list[float]]
+        original array as list
+
+    Raises
+    ------
+    ValueError
+        if the values are unordered
+    """
+    if isinstance(array, np.ndarray):
+        array = array.tolist()
+    for i, array in enumerate(array):
         _array = np.array(array)
         if not np.all(np.sort(_array) == _array) or np.all(
             reversed(np.sort(_array)) == _array,
         ):
             raise ValueError(f"Axis {i} has unordered values.")
-    return axis_ticks
+    return array
 
 
 class Grid(SimvueObject):
@@ -127,6 +143,11 @@ def on_reconnect(self, id_mapping: dict[str, str]) -> None:
         id_mapping : dict[str, str]
             mapping from offline identifier to new online identifier.
 
+        Raises
+        ------
+        RuntimeError
+            If metrics could not be attached to uploaded runs on reconnect.
+
         """
         _online_runs = (
             (id_mapping[run_id], metric_name)

simvue/api/objects/run.py

@@ -836,6 +836,11 @@ def abort(self, reason: str) -> dict[str, typing.Any]:
         dict[str, Any]
             server response after updating abort status.
 
+        Raises
+        ------
+        RuntimeError
+            if no server URL has been specified or found
+
         """
         if not self._abort_url:
             raise RuntimeError("Cannot abort run, no endpoint defined")

simvue/api/objects/tag.py

@@ -25,6 +25,8 @@
 
 
 class TagSort(Sort):
+    """Class defining the sorting of tag data when retrieved from the server."""
+
     @pydantic.field_validator("column")
     @classmethod
     def check_column(cls, column: str) -> str:

simvue/models.py

@@ -26,7 +26,25 @@
 
 
 def validate_timestamp(timestamp: str, *, raise_except: bool = True) -> bool:
-    """Validate a user-provided timestamp."""
+    """Validate a user-provided timestamp.
+
+    Parameters
+    -----------
+    timestamp : str
+        timestamp to check
+    raise_except : bool, optional
+        whether to raise an exception on failure, default True
+
+    Returns
+    -------
+    bool
+        if check passed successfully
+
+    Raises
+    ------
+    ValueError
+        if exception throwing is enabled and the check fails
+    """
     try:
         _ = datetime.datetime.strptime(timestamp, DATETIME_FORMAT).astimezone()
     except ValueError:
@@ -73,6 +91,8 @@ def simvue_timestamp(
 
 # Pydantic class to validate run.init()
 class RunInput(pydantic.BaseModel):
+    """Validate inputs for user run."""
+
     model_config = pydantic.ConfigDict(extra="forbid")
     name: str | None = pydantic.Field(None, pattern=NAME_REGEX)
     metadata: dict[MetadataKeyString, str | int | float | None] | None = None
@@ -84,6 +104,8 @@ class RunInput(pydantic.BaseModel):
 
 
 class MetricSet(pydantic.BaseModel):
+    """Model for a set of metrics retrieved from the server."""
+
     model_config = pydantic.ConfigDict(extra="forbid")
     time: float | int
     timestamp: typing.Annotated[str | None, pydantic.BeforeValidator(simvue_timestamp)]
@@ -92,6 +114,8 @@ class MetricSet(pydantic.BaseModel):
 
 
 class GridMetricSet(pydantic.BaseModel):
+    """Model for a set of grid metrics retrieved from the server."""
+
     model_config = pydantic.ConfigDict(
         arbitrary_types_allowed=True,
         extra="forbid",
@@ -110,12 +134,15 @@ def serialize_array(
         value: np.ndarray | list[float] | list[list[float]],
         *_,
     ) -> list[float] | list[list[float]]:
+        """Serialize a numpy array."""
         if isinstance(value, list):
             return value
         return value.tolist()
 
 
 class EventSet(pydantic.BaseModel):
+    """Model for a set of events retrieved from the server."""
+
     model_config = pydantic.ConfigDict(extra="forbid")
     message: str
     log_level: (

simvue/run.py

@@ -91,6 +91,14 @@
 def check_run_initialised(
     function: typing.Callable[..., typing.Any],
 ) -> typing.Callable[..., typing.Any]:
+    """Decorator to ensure that the run object has been initialised.
+
+    A lot of functionality within the Run class only works if the object has first
+    been initialised by the user, this decorator catches the invalid case as soon
+    as possible.
+
+    """
+
     @functools.wraps(function)
     def _wrapper(self: Self, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
         # Tidy pydantic errors