@@ -42,6 +42,14 @@ class ArtifactBase(SimvueObject):
42
42
def __init__ (
43
43
self , identifier : str | None = None , _read_only : bool = True , ** kwargs
44
44
) -> 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
+
45
53
self ._label = "artifact"
46
54
self ._endpoint = f"{ self ._label } s"
47
55
super ().__init__ (identifier = identifier , _read_only = _read_only , ** kwargs )
@@ -51,10 +59,19 @@ def __init__(
51
59
self ._init_data : dict [str , dict ] = {}
52
60
53
61
def commit (self ) -> None :
62
+ """Not applicable, cannot commit single write artifact."""
54
63
self ._logger .info ("Cannot call method 'commit' on write-once type 'Artifact'" )
55
64
56
65
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
+ """
58
75
self ._init_data ["runs" ][run_id ] = category
59
76
60
77
if self ._offline :
@@ -80,6 +97,13 @@ def attach_to_run(self, run_id: str, category: Category) -> None:
80
97
)
81
98
82
99
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
+ """
83
107
_offline_staging = self ._init_data ["runs" ].copy ()
84
108
for id , category in _offline_staging .items ():
85
109
self .attach_to_run (run_id = id_mapping [id ], category = category )
@@ -134,42 +158,82 @@ def _get(
134
158
135
159
@property
136
160
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
+ """
138
167
return self ._get_attribute ("checksum" )
139
168
140
169
@property
141
170
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
+ """
143
177
return URL (_url ) if (_url := self ._init_data .get ("url" )) else None
144
178
145
179
@property
146
180
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
+ """
148
187
return self ._get_attribute ("original_path" )
149
188
150
189
@property
151
190
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
+ """
153
197
return self ._get_attribute ("storage_id" )
154
198
155
199
@property
156
200
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
+ """
158
207
return self ._get_attribute ("mime_type" )
159
208
160
209
@property
161
210
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
+ """
163
217
return self ._get_attribute ("size" )
164
218
165
219
@property
166
220
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
+ """
168
227
return self ._get_attribute ("name" )
169
228
170
229
@property
171
230
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
+ """
173
237
_created : str | None = self ._get_attribute ("created" )
174
238
return (
175
239
datetime .datetime .strptime (_created , DATETIME_FORMAT ) if _created else None
@@ -178,7 +242,12 @@ def created(self) -> datetime.datetime | None:
178
242
@property
179
243
@staging_check
180
244
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
+ """
182
251
return self ._get_attribute ("uploaded" )
183
252
184
253
@uploaded .setter
@@ -190,17 +259,37 @@ def uploaded(self, is_uploaded: bool) -> None:
190
259
191
260
@property
192
261
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
+ """
194
268
return self ._get_attribute ("url" )
195
269
196
270
@property
197
271
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
+ """
199
283
for _id , _ in Run .get (filters = [f"artifact.id == { self .id } " ]):
200
284
yield _id
201
285
202
286
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
+ """
204
293
_run_url = (
205
294
URL (self ._user_config .server .url )
206
295
/ f"runs/{ run_id } /artifacts/{ self ._identifier } "
@@ -220,7 +309,17 @@ def get_category(self, run_id: str) -> Category:
220
309
221
310
@pydantic .validate_call
222
311
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
+ """
224
323
if not self .download_url :
225
324
raise ValueError (
226
325
f"Could not retrieve URL for artifact '{ self ._identifier } '"
0 commit comments