Merge branch 'v2.0' into dev

Author: kzscisoft

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Change log
-
-## [v2.0.0](https://github.com/simvue-io/python-api/releases/tag/v2.0.0) - 2025-03-07
+## [v2.0.1](https://github.com/simvue-io/client/releases/tag/v2.0.1) - 2025-03-24
+* Improvements to docstrings on methods, classes and functions.
+## [v2.0.0](https://github.com/simvue-io/client/releases/tag/v2.0.0) - 2025-03-07
 * Add new example notebooks
 * Update and refactor examples to work with v2.0
 * Fix bug in offline artifacts using wrong file path

CITATION.cff

@@ -42,9 +42,9 @@ keywords:
   - alerting
   - simulation
 license: Apache-2.0
-commit: 88bdd861e01153a2853191c0a8d1bb64dfabe296
-version: 2.0.0
-date-released: '2025-03-07'
+commit: 5084f9c17ae4b7f77e188f5aa8a51ebd3f790c9e
+version: 2.0.1
+date-released: '2025-03-24'
 references:
 - title: mlco2/codecarbon
   version: v2.8.2

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simvue"
-version = "2.0.0"
+version = "2.0.1"
 description = "Simulation tracking and monitoring"
 authors = [
   {name = "Simvue Development Team", email = "info@simvue.io"}

simvue/api/objects/artifact/base.py

@@ -42,6 +42,14 @@ class ArtifactBase(SimvueObject):
     def __init__(
         self, identifier: str | None = None, _read_only: bool = True, **kwargs
     ) -> None:
+        """Initialise an artifact connection.
+
+        Parameters
+        ----------
+        identifier : str, optional
+            the identifier of this object on the server.
+        """
+
         self._label = "artifact"
         self._endpoint = f"{self._label}s"
         super().__init__(identifier=identifier, _read_only=_read_only, **kwargs)
@@ -51,10 +59,19 @@ def __init__(
         self._init_data: dict[str, dict] = {}
 
     def commit(self) -> None:
+        """Not applicable, cannot commit single write artifact."""
         self._logger.info("Cannot call method 'commit' on write-once type 'Artifact'")
 
     def attach_to_run(self, run_id: str, category: Category) -> None:
-        """Attach this artifact to a given run"""
+        """Attach this artifact to a given run.
+
+        Parameters
+        ----------
+        run_id : str
+            identifier of run to associate this artifact with.
+        category : Literal['input', 'output', 'code']
+            category of this artifact with respect to the run.
+        """
         self._init_data["runs"][run_id] = category
 
         if self._offline:
@@ -80,6 +97,13 @@ def attach_to_run(self, run_id: str, category: Category) -> None:
         )
 
     def on_reconnect(self, id_mapping: dict[str, str]) -> None:
+        """Operations performed when this artifact is switched from offline to online mode.
+
+        Parameters
+        ----------
+        id_mapping : dict[str, str]
+            mapping from offline identifier to new online identifier.
+        """
         _offline_staging = self._init_data["runs"].copy()
         for id, category in _offline_staging.items():
             self.attach_to_run(run_id=id_mapping[id], category=category)
@@ -134,42 +158,82 @@ def _get(
 
     @property
     def checksum(self) -> str:
-        """Retrieve the checksum for this artifact"""
+        """Retrieve the checksum for this artifact.
+
+        Returns
+        -------
+        str
+        """
         return self._get_attribute("checksum")
 
     @property
     def storage_url(self) -> URL | None:
-        """Retrieve upload URL for artifact"""
+        """Retrieve upload URL for artifact.
+
+        Returns
+        -------
+        simvue.api.url.URL | None
+        """
         return URL(_url) if (_url := self._init_data.get("url")) else None
 
     @property
     def original_path(self) -> str:
-        """Retrieve the original path of the file associated with this artifact"""
+        """Retrieve the original path of the file associated with this artifact.
+
+        Returns
+        -------
+        str
+        """
         return self._get_attribute("original_path")
 
     @property
     def storage_id(self) -> str | None:
-        """Retrieve the storage identifier for this artifact"""
+        """Retrieve the storage identifier for this artifact.
+
+        Returns
+        -------
+        str | None
+        """
         return self._get_attribute("storage_id")
 
     @property
     def mime_type(self) -> str:
-        """Retrieve the MIME type for this artifact"""
+        """Retrieve the MIME type for this artifact.
+
+        Returns
+        -------
+        str
+        """
         return self._get_attribute("mime_type")
 
     @property
     def size(self) -> int:
-        """Retrieve the size for this artifact in bytes"""
+        """Retrieve the size for this artifact in bytes.
+
+        Returns
+        -------
+        int
+        """
         return self._get_attribute("size")
 
     @property
     def name(self) -> str | None:
-        """Retrieve name for the artifact"""
+        """Retrieve name for the artifact.
+
+        Returns
+        -------
+        str | None
+        """
         return self._get_attribute("name")
 
     @property
     def created(self) -> datetime.datetime | None:
-        """Retrieve created datetime for the artifact"""
+        """Retrieve created datetime for the artifact.
+
+        Returns
+        -------
+        datetime.datetime | None
+        """
         _created: str | None = self._get_attribute("created")
         return (
             datetime.datetime.strptime(_created, DATETIME_FORMAT) if _created else None
@@ -178,7 +242,12 @@ def created(self) -> datetime.datetime | None:
     @property
     @staging_check
     def uploaded(self) -> bool:
-        """Returns whether a file was uploaded for this artifact."""
+        """Returns whether a file was uploaded for this artifact.
+
+        Returns
+        -------
+        bool
+        """
         return self._get_attribute("uploaded")
 
     @uploaded.setter
@@ -190,17 +259,37 @@ def uploaded(self, is_uploaded: bool) -> None:
 
     @property
     def download_url(self) -> URL | None:
-        """Retrieve the URL for downloading this artifact"""
+        """Retrieve the URL for downloading this artifact
+
+        Returns
+        -------
+        simvue.api.url.URL | None
+        """
         return self._get_attribute("url")
 
     @property
     def runs(self) -> typing.Generator[str, None, None]:
-        """Retrieve all runs for which this artifact is related"""
+        """Retrieve all runs for which this artifact is related.
+
+        Yields
+        ------
+        str
+            run identifier for run associated with this artifact
+
+        Returns
+        -------
+        Generator[str, None, None]
+        """
         for _id, _ in Run.get(filters=[f"artifact.id == {self.id}"]):
             yield _id
 
     def get_category(self, run_id: str) -> Category:
-        """Retrieve the category of this artifact with respect to a given run"""
+        """Retrieve the category of this artifact with respect to a given run.
+
+        Returns
+        -------
+        Literal['input', 'output', 'code']
+        """
         _run_url = (
             URL(self._user_config.server.url)
             / f"runs/{run_id}/artifacts/{self._identifier}"
@@ -220,7 +309,17 @@ def get_category(self, run_id: str) -> Category:
 
     @pydantic.validate_call
     def download_content(self) -> typing.Generator[bytes, None, None]:
-        """Stream artifact content"""
+        """Stream artifact content.
+
+        Yields
+        ------
+        bytes
+            artifact content from server.
+
+        Returns
+        -------
+        Generator[bytes, None, None]
+        """
         if not self.download_url:
             raise ValueError(
                 f"Could not retrieve URL for artifact '{self._identifier}'"

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)
@@ -36,8 +46,11 @@ def from_run(
         ----------
         run_id : str
             The ID of the run to retriece artifacts from
-        category : typing.Literal["input", "output", "code"] | None, optional
-            The category of artifacts to return, by default all artifacts are returned
+        category : Literal['input', 'output', 'code'] | None
+            category of artifacts to return, if None, do not filter
+                * input - this file is an input file.
+                * output - this file is created by the run.
+                * code - this file represents an executed script
 
         Returns
         -------
@@ -83,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/artifact/file.py

@@ -14,6 +14,20 @@
 
 
 class FileArtifact(ArtifactBase):
+    """File based artifact modification and creation class."""
+
+    def __init__(
+        self, identifier: str | None = None, _read_only: bool = True, **kwargs
+    ) -> None:
+        """Initialise a new file artifact connection.
+
+        Parameters
+        ----------
+        identifier : str, optional
+            the identifier of this object on the server.
+        """
+        super().__init__(identifier=identifier, _read_only=_read_only, **kwargs)
+
     @classmethod
     def new(
         cls,
@@ -36,8 +50,6 @@ def new(
             the name for this artifact
         storage : str | None
             the identifier for the storage location for this object
-        category : "code" | "input" | "output"
-            the category of this artifact
         file_path : pathlib.Path | str
             path to the file this artifact represents
         mime_type : str | None

simvue/api/objects/artifact/object.py

@@ -15,9 +15,18 @@
 
 
 class ObjectArtifact(ArtifactBase):
+    """Object based artifact modification and creation class."""
+
     def __init__(
         self, identifier: str | None = None, _read_only: bool = True, **kwargs
     ) -> None:
+        """Initialise a new object artifact connection.
+
+        Parameters
+        ----------
+        identifier : str, optional
+            the identifier of this object on the server.
+        """
         kwargs.pop("original_path", None)
         super().__init__(identifier, _read_only, original_path="", **kwargs)