Skip to content

Commit 5084f9c

Browse files
authored
Merge pull request #765 from simvue-io/feature/v2-docs-refinement
Docstring Improvements to 2.0
2 parents 051414c + f90e093 commit 5084f9c

File tree

19 files changed

+777
-126
lines changed

19 files changed

+777
-126
lines changed

simvue/api/objects/artifact/base.py

Lines changed: 113 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,14 @@ class ArtifactBase(SimvueObject):
4242
def __init__(
4343
self, identifier: str | None = None, _read_only: bool = True, **kwargs
4444
) -> None:
45+
"""Initialise an artifact connection.
46+
47+
Parameters
48+
----------
49+
identifier : str, optional
50+
the identifier of this object on the server.
51+
"""
52+
4553
self._label = "artifact"
4654
self._endpoint = f"{self._label}s"
4755
super().__init__(identifier=identifier, _read_only=_read_only, **kwargs)
@@ -51,10 +59,19 @@ def __init__(
5159
self._init_data: dict[str, dict] = {}
5260

5361
def commit(self) -> None:
62+
"""Not applicable, cannot commit single write artifact."""
5463
self._logger.info("Cannot call method 'commit' on write-once type 'Artifact'")
5564

5665
def attach_to_run(self, run_id: str, category: Category) -> None:
57-
"""Attach this artifact to a given run"""
66+
"""Attach this artifact to a given run.
67+
68+
Parameters
69+
----------
70+
run_id : str
71+
identifier of run to associate this artifact with.
72+
category : Literal['input', 'output', 'code']
73+
category of this artifact with respect to the run.
74+
"""
5875
self._init_data["runs"][run_id] = category
5976

6077
if self._offline:
@@ -80,6 +97,13 @@ def attach_to_run(self, run_id: str, category: Category) -> None:
8097
)
8198

8299
def on_reconnect(self, id_mapping: dict[str, str]) -> None:
100+
"""Operations performed when this artifact is switched from offline to online mode.
101+
102+
Parameters
103+
----------
104+
id_mapping : dict[str, str]
105+
mapping from offline identifier to new online identifier.
106+
"""
83107
_offline_staging = self._init_data["runs"].copy()
84108
for id, category in _offline_staging.items():
85109
self.attach_to_run(run_id=id_mapping[id], category=category)
@@ -134,42 +158,82 @@ def _get(
134158

135159
@property
136160
def checksum(self) -> str:
137-
"""Retrieve the checksum for this artifact"""
161+
"""Retrieve the checksum for this artifact.
162+
163+
Returns
164+
-------
165+
str
166+
"""
138167
return self._get_attribute("checksum")
139168

140169
@property
141170
def storage_url(self) -> URL | None:
142-
"""Retrieve upload URL for artifact"""
171+
"""Retrieve upload URL for artifact.
172+
173+
Returns
174+
-------
175+
simvue.api.url.URL | None
176+
"""
143177
return URL(_url) if (_url := self._init_data.get("url")) else None
144178

145179
@property
146180
def original_path(self) -> str:
147-
"""Retrieve the original path of the file associated with this artifact"""
181+
"""Retrieve the original path of the file associated with this artifact.
182+
183+
Returns
184+
-------
185+
str
186+
"""
148187
return self._get_attribute("original_path")
149188

150189
@property
151190
def storage_id(self) -> str | None:
152-
"""Retrieve the storage identifier for this artifact"""
191+
"""Retrieve the storage identifier for this artifact.
192+
193+
Returns
194+
-------
195+
str | None
196+
"""
153197
return self._get_attribute("storage_id")
154198

155199
@property
156200
def mime_type(self) -> str:
157-
"""Retrieve the MIME type for this artifact"""
201+
"""Retrieve the MIME type for this artifact.
202+
203+
Returns
204+
-------
205+
str
206+
"""
158207
return self._get_attribute("mime_type")
159208

160209
@property
161210
def size(self) -> int:
162-
"""Retrieve the size for this artifact in bytes"""
211+
"""Retrieve the size for this artifact in bytes.
212+
213+
Returns
214+
-------
215+
int
216+
"""
163217
return self._get_attribute("size")
164218

165219
@property
166220
def name(self) -> str | None:
167-
"""Retrieve name for the artifact"""
221+
"""Retrieve name for the artifact.
222+
223+
Returns
224+
-------
225+
str | None
226+
"""
168227
return self._get_attribute("name")
169228

170229
@property
171230
def created(self) -> datetime.datetime | None:
172-
"""Retrieve created datetime for the artifact"""
231+
"""Retrieve created datetime for the artifact.
232+
233+
Returns
234+
-------
235+
datetime.datetime | None
236+
"""
173237
_created: str | None = self._get_attribute("created")
174238
return (
175239
datetime.datetime.strptime(_created, DATETIME_FORMAT) if _created else None
@@ -178,7 +242,12 @@ def created(self) -> datetime.datetime | None:
178242
@property
179243
@staging_check
180244
def uploaded(self) -> bool:
181-
"""Returns whether a file was uploaded for this artifact."""
245+
"""Returns whether a file was uploaded for this artifact.
246+
247+
Returns
248+
-------
249+
bool
250+
"""
182251
return self._get_attribute("uploaded")
183252

184253
@uploaded.setter
@@ -190,17 +259,37 @@ def uploaded(self, is_uploaded: bool) -> None:
190259

191260
@property
192261
def download_url(self) -> URL | None:
193-
"""Retrieve the URL for downloading this artifact"""
262+
"""Retrieve the URL for downloading this artifact
263+
264+
Returns
265+
-------
266+
simvue.api.url.URL | None
267+
"""
194268
return self._get_attribute("url")
195269

196270
@property
197271
def runs(self) -> typing.Generator[str, None, None]:
198-
"""Retrieve all runs for which this artifact is related"""
272+
"""Retrieve all runs for which this artifact is related.
273+
274+
Yields
275+
------
276+
str
277+
run identifier for run associated with this artifact
278+
279+
Returns
280+
-------
281+
Generator[str, None, None]
282+
"""
199283
for _id, _ in Run.get(filters=[f"artifact.id == {self.id}"]):
200284
yield _id
201285

202286
def get_category(self, run_id: str) -> Category:
203-
"""Retrieve the category of this artifact with respect to a given run"""
287+
"""Retrieve the category of this artifact with respect to a given run.
288+
289+
Returns
290+
-------
291+
Literal['input', 'output', 'code']
292+
"""
204293
_run_url = (
205294
URL(self._user_config.server.url)
206295
/ f"runs/{run_id}/artifacts/{self._identifier}"
@@ -220,7 +309,17 @@ def get_category(self, run_id: str) -> Category:
220309

221310
@pydantic.validate_call
222311
def download_content(self) -> typing.Generator[bytes, None, None]:
223-
"""Stream artifact content"""
312+
"""Stream artifact content.
313+
314+
Yields
315+
------
316+
bytes
317+
artifact content from server.
318+
319+
Returns
320+
-------
321+
Generator[bytes, None, None]
322+
"""
224323
if not self.download_url:
225324
raise ValueError(
226325
f"Could not retrieve URL for artifact '{self._identifier}'"

simvue/api/objects/artifact/fetch.py

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,16 @@
1515
class Artifact:
1616
"""Generic Simvue artifact retrieval class"""
1717

18+
def __init__(self, identifier: str | None = None, *args, **kwargs) -> None:
19+
"""Initialise an instance of generic artifact retriever.
20+
21+
Parameters
22+
----------
23+
identifier : str
24+
identifier of artifact object to retrieve
25+
"""
26+
super().__init__(identifier=identifier, *args, **kwargs)
27+
1828
def __new__(cls, identifier: str | None = None, **kwargs):
1929
"""Retrieve an object representing an Artifact by id"""
2030
_artifact_pre = ArtifactBase(identifier=identifier, **kwargs)
@@ -36,8 +46,11 @@ def from_run(
3646
----------
3747
run_id : str
3848
The ID of the run to retriece artifacts from
39-
category : typing.Literal["input", "output", "code"] | None, optional
40-
The category of artifacts to return, by default all artifacts are returned
49+
category : Literal['input', 'output', 'code'] | None
50+
category of artifacts to return, if None, do not filter
51+
* input - this file is an input file.
52+
* output - this file is created by the run.
53+
* code - this file represents an executed script
4154
4255
Returns
4356
-------
@@ -83,6 +96,20 @@ def from_run(
8396
def from_name(
8497
cls, run_id: str, name: str, **kwargs
8598
) -> typing.Union[FileArtifact | ObjectArtifact, None]:
99+
"""Retrieve an artifact by name.
100+
101+
Parameters
102+
----------
103+
run_id : str
104+
the identifier of the run to retrieve from.
105+
name : str
106+
the name of the artifact to retrieve.
107+
108+
Returns
109+
-------
110+
FileArtifact | ObjectArtifact | None
111+
the artifact if found
112+
"""
86113
_temp = ArtifactBase(**kwargs)
87114
_url = URL(_temp._user_config.server.url) / f"runs/{run_id}/artifacts"
88115
_response = sv_get(url=f"{_url}", params={"name": name}, headers=_temp._headers)

simvue/api/objects/artifact/file.py

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,20 @@
1414

1515

1616
class FileArtifact(ArtifactBase):
17+
"""File based artifact modification and creation class."""
18+
19+
def __init__(
20+
self, identifier: str | None = None, _read_only: bool = True, **kwargs
21+
) -> None:
22+
"""Initialise a new file artifact connection.
23+
24+
Parameters
25+
----------
26+
identifier : str, optional
27+
the identifier of this object on the server.
28+
"""
29+
super().__init__(identifier=identifier, _read_only=_read_only, **kwargs)
30+
1731
@classmethod
1832
def new(
1933
cls,
@@ -36,8 +50,6 @@ def new(
3650
the name for this artifact
3751
storage : str | None
3852
the identifier for the storage location for this object
39-
category : "code" | "input" | "output"
40-
the category of this artifact
4153
file_path : pathlib.Path | str
4254
path to the file this artifact represents
4355
mime_type : str | None

simvue/api/objects/artifact/object.py

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,18 @@
1515

1616

1717
class ObjectArtifact(ArtifactBase):
18+
"""Object based artifact modification and creation class."""
19+
1820
def __init__(
1921
self, identifier: str | None = None, _read_only: bool = True, **kwargs
2022
) -> None:
23+
"""Initialise a new object artifact connection.
24+
25+
Parameters
26+
----------
27+
identifier : str, optional
28+
the identifier of this object on the server.
29+
"""
2130
kwargs.pop("original_path", None)
2231
super().__init__(identifier, _read_only, original_path="", **kwargs)
2332

0 commit comments

Comments
 (0)