Further docs modifications

Author: kzscisoft

simvue/api/objects/artifact/fetch.py

@@ -15,6 +15,16 @@
 class Artifact:
     """Generic Simvue artifact retrieval class"""
 
+    def __init__(self, identifier: str | None = None, *args, **kwargs) -> None:
+        """Initialise an instance of generic artifact retriever.
+
+        Parameters
+        ----------
+        identifier : str
+            identifier of artifact object to retrieve
+        """
+        super().__init__(identifier=identifier, *args, **kwargs)
+
     def __new__(cls, identifier: str | None = None, **kwargs):
         """Retrieve an object representing an Artifact by id"""
         _artifact_pre = ArtifactBase(identifier=identifier, **kwargs)
@@ -86,6 +96,20 @@ def from_run(
     def from_name(
         cls, run_id: str, name: str, **kwargs
     ) -> typing.Union[FileArtifact | ObjectArtifact, None]:
+        """Retrieve an artifact by name.
+
+        Parameters
+        ----------
+        run_id : str
+            the identifier of the run to retrieve from.
+        name : str
+            the name of the artifact to retrieve.
+
+        Returns
+        -------
+        FileArtifact | ObjectArtifact | None
+            the artifact if found
+        """
         _temp = ArtifactBase(**kwargs)
         _url = URL(_temp._user_config.server.url) / f"runs/{run_id}/artifacts"
         _response = sv_get(url=f"{_url}", params={"name": name}, headers=_temp._headers)

simvue/api/objects/base.py

@@ -443,6 +443,13 @@ def _get_all_objects(
         )
 
     def read_only(self, is_read_only: bool) -> None:
+        """Set whether this object is in read only state.
+
+        Parameters
+        ----------
+        is_read_only : bool
+            whether object is read only.
+        """
         self._read_only = is_read_only
 
         # If using writable mode, clear the staging dictionary as
@@ -649,6 +656,10 @@ def to_dict(self) -> dict[str, typing.Any]:
         return self._get() | self._staging
 
     def on_reconnect(self, id_mapping: dict[str, str]) -> None:
+        """Executed when a run switches from offline to online mode.
+
+        In this case no action is taken.
+        """
         pass
 
     @property

simvue/api/objects/metrics.py

@@ -139,11 +139,27 @@ def _post(self, **kwargs) -> dict[str, typing.Any]:
         return super()._post(is_json=False, **kwargs)
 
     def delete(self, **kwargs) -> dict[str, typing.Any]:
+        """Metrics cannot be deleted"""
         raise NotImplementedError("Cannot delete metric set")
 
     def on_reconnect(self, id_mapping: dict[str, str]):
+        """Action performed when mode switched from offline to online.
+
+        Parameters
+        ----------
+        id_mapping : dict[str, str]
+            mapping from offline to online identifier.
+
+        """
         if online_run_id := id_mapping.get(self._staging["run"]):
             self._staging["run"] = online_run_id
 
     def to_dict(self) -> dict[str, typing.Any]:
+        """Convert metrics object to dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            dictionary representation of metrics object.
+        """
         return self._staging

simvue/api/objects/stats.py

@@ -20,6 +20,7 @@ class Stats(SimvueObject):
     """Class for accessing Server statistics."""
 
     def __init__(self) -> None:
+        """Initialise a statistics query object."""
         self.runs = RunStatistics(self)
         self._label = "stat"
         super().__init__()
@@ -30,11 +31,76 @@ def __init__(self) -> None:
 
     @classmethod
     def new(cls, **kwargs) -> None:
-        """Creation of multiple stats objects is not logical here"""
+        """Creation of multiple stats objects is not logical here.
+
+        Raises
+        ------
+        AttributeError
+        """
         raise AttributeError("Creation of statistics objects is not supported")
 
+    @classmethod
+    def delete(cls, **kwargs) -> None:
+        """Deletion of stats object is not logical here.
+
+        Raises
+        ------
+        AttributeError
+        """
+        raise AttributeError("Deletion of statistics is not supported")
+
+    def read_only(self) -> None:
+        """Statistics can only be read-only.
+
+        Raises
+        ------
+        NotImplementedError
+        """
+        raise NotImplementedError("Statistics are not modifiable.")
+
+    def id(self) -> None:
+        """No unique indentifier for statistics retrieval.
+
+        Returns
+        -------
+        None
+        """
+        return None
+
+    def on_reconnect(self, **_) -> None:
+        """No offline to online reconnect functionality for statistics."""
+        pass
+
+    @classmethod
+    def get(cls, **kwargs) -> None:
+        """Retrieval of multiple stats object is not logical here.
+
+        Raises
+        ------
+        AttributeError
+        """
+        raise AttributeError(
+            "Retrieval of multiple of statistics objects is not supported"
+        )
+
+    @classmethod
+    def ids(cls, **kwargs) -> None:
+        """Retrieval of identifiers is not logical here.
+
+        Raises
+        ------
+        AttributeError
+        """
+        raise AttributeError("Retrieval of ids for statistics objects is not supported")
+
     def whoami(self) -> dict[str, str]:
-        """Return the current user"""
+        """Return the current user information.
+
+        Returns
+        -------
+        dict[str, str]
+            server response for 'whomai' query.
+        """
         _url: URL = URL(self._user_config.server.url) / "whoami"
         _response = sv_get(url=f"{_url}", headers=self._headers)
         return get_json_from_response(
@@ -56,9 +122,19 @@ def _get_visibility(self) -> dict[str, bool | list[str]]:
         return {}
 
     def to_dict(self) -> dict[str, typing.Any]:
-        """Returns dictionary form of statistics"""
+        """Dictionary form of statistics.
+
+        Returns
+        -------
+        doct[str, Any]
+            statistics data as dictionary
+        """
         return {"runs": self._get_run_stats()}
 
+    def commit(self) -> None:
+        """Does nothing, no data sendable to server."""
+        pass
+
 
 class RunStatistics:
     """Interface to the run section of statistics output"""

simvue/api/objects/storage/fetch.py

@@ -21,6 +21,16 @@
 class Storage:
     """Generic Simvue storage retrieval class"""
 
+    def __init__(self, identifier: str | None = None, *args, **kwargs) -> None:
+        """Initialise an instance of generic storage retriever.
+
+        Parameters
+        ----------
+        identifier : str
+            identifier of storage object to retrieve
+        """
+        super().__init__(identifier=identifier, *args, **kwargs)
+
     def __new__(cls, identifier: str | None = None, **kwargs):
         """Retrieve an object representing an storage either locally or on the server by id"""
         _storage_pre = StorageBase(identifier=identifier, **kwargs)

simvue/api/objects/storage/file.py

@@ -42,11 +42,11 @@ def new(
             name to allocated to this storage system
         disable_check : bool
             whether to disable checks for this system
-        tenant_usable : bool
+        is_tenant_useable : bool
             whether this system is usable by the current tenant
         is_enabled : bool
             whether to enable this system
-        default : bool
+        is_default : bool
             if this storage system should become the new default
         offline : bool, optional
             if this instance should be created in offline mode, default False

simvue/api/objects/storage/s3.py

@@ -64,7 +64,7 @@ def new(
             the secret access key, stored as a secret string
         bucket : str
             the bucket associated with this storage system
-        tenant_usable : bool
+        is_tenant_useable : bool
             whether this system is usable by the current tenant
         is_enabled : bool
             whether to enable this system
@@ -119,7 +119,13 @@ def __init__(self, storage: S3Storage) -> None:
     @property
     @staging_check
     def endpoint_url(self) -> str:
-        """Retrieve the endpoint URL for this storage"""
+        """Set/retrieve the endpoint URL for this storage.
+
+        Returns
+        -------
+        str
+            the endpoint for this storage object
+        """
         try:
             return self._sv_obj.get_config()["endpoint_url"]
         except KeyError as e:
@@ -131,7 +137,6 @@ def endpoint_url(self) -> str:
     @write_only
     @pydantic.validate_call
     def endpoint_url(self, endpoint_url: pydantic.HttpUrl) -> None:
-        """Modify the endpoint URL for this storage"""
         _config = self._sv_obj.get_config() | {"endpoint_url": endpoint_url.__str__()}
         self._sv_obj._staging["config"] = _config