tro-utils 0.5.4__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tro_utils/__init__.py +72 -0
- tro_utils/_version.py +24 -0
- tro_utils/certs/freetsa-root.pem +52 -0
- tro_utils/certs/freetsa-tsa.pem +100 -0
- tro_utils/cli.py +738 -0
- tro_utils/default.jinja2 +86 -0
- tro_utils/models/__init__.py +36 -0
- tro_utils/models/_base.py +68 -0
- tro_utils/models/agent.py +176 -0
- tro_utils/models/arrangement.py +378 -0
- tro_utils/models/artifact.py +101 -0
- tro_utils/models/attribute.py +51 -0
- tro_utils/models/composition.py +144 -0
- tro_utils/models/hash_value.py +101 -0
- tro_utils/models/performance.py +195 -0
- tro_utils/models/tro.py +509 -0
- tro_utils/models/trs.py +329 -0
- tro_utils/models/tsa.py +44 -0
- tro_utils/replication_package.py +179 -0
- tro_utils/static/trace-logo.png +0 -0
- tro_utils/tro_utils.py +740 -0
- tro_utils/trs_keys.py +251 -0
- tro_utils/tsa.py +149 -0
- tro_utils-0.5.4.dist-info/METADATA +222 -0
- tro_utils-0.5.4.dist-info/RECORD +29 -0
- tro_utils-0.5.4.dist-info/WHEEL +5 -0
- tro_utils-0.5.4.dist-info/entry_points.txt +2 -0
- tro_utils-0.5.4.dist-info/licenses/LICENSE +32 -0
- tro_utils-0.5.4.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
"""ArtifactArrangement and ArtifactLocation models.
|
|
2
|
+
|
|
3
|
+
An arrangement is a snapshot of file locations at a particular point in time,
|
|
4
|
+
linking each file path to a :class:`~tro_utils.models.artifact.ResearchArtifact`
|
|
5
|
+
stored in the :class:`~tro_utils.models.composition.ArtifactComposition`.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import hashlib
|
|
11
|
+
import json
|
|
12
|
+
import os
|
|
13
|
+
import pathlib
|
|
14
|
+
from dataclasses import dataclass, field
|
|
15
|
+
from typing import Any
|
|
16
|
+
|
|
17
|
+
from ._base import TROVModel, natural_id_key
|
|
18
|
+
from .artifact import ResearchArtifact
|
|
19
|
+
from .composition import ArtifactComposition
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass
|
|
23
|
+
class ArtifactLocation(TROVModel):
|
|
24
|
+
"""A single (path, artifact) binding within an arrangement."""
|
|
25
|
+
|
|
26
|
+
location_id: str
|
|
27
|
+
artifact_id: str
|
|
28
|
+
path: str
|
|
29
|
+
|
|
30
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
31
|
+
return {
|
|
32
|
+
"@id": self.location_id,
|
|
33
|
+
"@type": "trov:ArtifactLocation",
|
|
34
|
+
"trov:artifact": {"@id": self.artifact_id},
|
|
35
|
+
"trov:path": self.path,
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
@classmethod
|
|
39
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "ArtifactLocation":
|
|
40
|
+
return cls(
|
|
41
|
+
location_id=data["@id"],
|
|
42
|
+
artifact_id=data["trov:artifact"]["@id"],
|
|
43
|
+
path=data["trov:path"],
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass
|
|
48
|
+
class ArtifactArrangement(TROVModel):
|
|
49
|
+
"""A snapshot of all artifact locations at a given point in time."""
|
|
50
|
+
|
|
51
|
+
arrangement_id: str
|
|
52
|
+
comment: str = ""
|
|
53
|
+
locations: list[ArtifactLocation] = field(default_factory=list)
|
|
54
|
+
|
|
55
|
+
# ------------------------------------------------------------------
|
|
56
|
+
# Convenience constructors
|
|
57
|
+
# ------------------------------------------------------------------
|
|
58
|
+
|
|
59
|
+
@classmethod
|
|
60
|
+
def from_directory(
|
|
61
|
+
cls,
|
|
62
|
+
directory: str | pathlib.Path,
|
|
63
|
+
composition: ArtifactComposition,
|
|
64
|
+
arrangement_id: str,
|
|
65
|
+
comment: str | None = None,
|
|
66
|
+
ignore_dirs: list[str] | None = None,
|
|
67
|
+
resolve_symlinks: bool = True,
|
|
68
|
+
) -> "ArtifactArrangement":
|
|
69
|
+
"""Scan *directory* and create an arrangement, updating *composition* in place.
|
|
70
|
+
|
|
71
|
+
New files are added to *composition*; existing files (by hash) are reused.
|
|
72
|
+
|
|
73
|
+
Args:
|
|
74
|
+
directory: Root directory to scan.
|
|
75
|
+
composition: The :class:`ArtifactComposition` to add new artifacts to.
|
|
76
|
+
arrangement_id: The ``@id`` for this arrangement (e.g. ``"arrangement/1"``).
|
|
77
|
+
comment: Human-readable description of this arrangement snapshot.
|
|
78
|
+
ignore_dirs: Directory names to skip (default: ``[".git"]``).
|
|
79
|
+
resolve_symlinks: Whether to follow symlinks when walking the tree.
|
|
80
|
+
|
|
81
|
+
Returns:
|
|
82
|
+
A new :class:`ArtifactArrangement`.
|
|
83
|
+
"""
|
|
84
|
+
import magic # local import
|
|
85
|
+
|
|
86
|
+
if ignore_dirs is None:
|
|
87
|
+
ignore_dirs = [".git"]
|
|
88
|
+
if comment is None:
|
|
89
|
+
comment = f"Scanned {directory}"
|
|
90
|
+
|
|
91
|
+
directory = pathlib.Path(directory)
|
|
92
|
+
magic_wrapper = magic.Magic(mime=True, uncompress=False)
|
|
93
|
+
|
|
94
|
+
# Collect the file list first, then sort by relative path. os.walk
|
|
95
|
+
# yields entries in filesystem order, which differs between machines;
|
|
96
|
+
# since this order decides both artifact @id assignment below and the
|
|
97
|
+
# order of trov:hasArtifactLocation, scanning the same tree twice has
|
|
98
|
+
# to walk it in the same order to produce the same declaration.
|
|
99
|
+
discovered: list[pathlib.Path] = []
|
|
100
|
+
for root, dirs, files in os.walk(str(directory)):
|
|
101
|
+
dirs[:] = [d for d in dirs if d not in ignore_dirs]
|
|
102
|
+
for filename in files:
|
|
103
|
+
discovered.append(pathlib.Path(root) / filename)
|
|
104
|
+
discovered.sort(key=lambda p: p.relative_to(directory).as_posix())
|
|
105
|
+
|
|
106
|
+
# Collect sha256 for all files in the directory
|
|
107
|
+
file_hashes: dict[pathlib.Path, str] = {
|
|
108
|
+
filepath: cls._sha256_for_file(str(filepath), resolve_symlinks)
|
|
109
|
+
for filepath in discovered
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
# Add any new artifacts to the composition
|
|
113
|
+
for filepath, hash_str in file_hashes.items():
|
|
114
|
+
if composition.get_by_hash(hash_str) is None:
|
|
115
|
+
artifact_id = composition.next_artifact_id()
|
|
116
|
+
if filepath.is_symlink():
|
|
117
|
+
mime_type = "inode/symlink"
|
|
118
|
+
else:
|
|
119
|
+
mime_type = (
|
|
120
|
+
magic_wrapper.from_file(str(filepath))
|
|
121
|
+
or "application/octet-stream"
|
|
122
|
+
)
|
|
123
|
+
from .hash_value import HashValue
|
|
124
|
+
|
|
125
|
+
algorithm, value = hash_str.split(":", 1)
|
|
126
|
+
artifact = ResearchArtifact(
|
|
127
|
+
artifact_id=artifact_id,
|
|
128
|
+
hash=HashValue(algorithm=algorithm, value=value),
|
|
129
|
+
mime_type=mime_type,
|
|
130
|
+
)
|
|
131
|
+
composition.add_artifact(artifact)
|
|
132
|
+
|
|
133
|
+
# Build locations
|
|
134
|
+
locations: list[ArtifactLocation] = []
|
|
135
|
+
for i, (filepath, hash_str) in enumerate(file_hashes.items()):
|
|
136
|
+
artifact = composition.get_by_hash(hash_str)
|
|
137
|
+
assert artifact is not None # guaranteed by the loop above
|
|
138
|
+
rel_path = filepath.relative_to(directory).as_posix()
|
|
139
|
+
locations.append(
|
|
140
|
+
ArtifactLocation(
|
|
141
|
+
location_id=f"{arrangement_id}/location/{i}",
|
|
142
|
+
artifact_id=artifact.artifact_id,
|
|
143
|
+
path=rel_path,
|
|
144
|
+
)
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
return cls(
|
|
148
|
+
arrangement_id=arrangement_id,
|
|
149
|
+
comment=comment,
|
|
150
|
+
locations=locations,
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
# ------------------------------------------------------------------
|
|
154
|
+
# Helpers
|
|
155
|
+
# ------------------------------------------------------------------
|
|
156
|
+
|
|
157
|
+
@staticmethod
|
|
158
|
+
def _sha256_for_file(filepath: str, resolve_symlinks: bool = True) -> str:
|
|
159
|
+
"""Return ``"sha256:<hex>"`` for *filepath*, or ``"none:"`` for symlinks/non-files."""
|
|
160
|
+
p = pathlib.Path(filepath)
|
|
161
|
+
if not p.is_file() or p.is_symlink():
|
|
162
|
+
return "none:"
|
|
163
|
+
sha256 = hashlib.sha256()
|
|
164
|
+
with open(filepath, "rb") as f:
|
|
165
|
+
for chunk in iter(lambda: f.read(4096), b""):
|
|
166
|
+
sha256.update(chunk)
|
|
167
|
+
return f"sha256:{sha256.hexdigest()}"
|
|
168
|
+
|
|
169
|
+
def to_path_hash_map(self, composition: ArtifactComposition) -> dict[str, str]:
|
|
170
|
+
"""Return a ``{relative_path: "sha256:<hex>"}`` binding.
|
|
171
|
+
|
|
172
|
+
Requires the corresponding :class:`ArtifactComposition` to resolve
|
|
173
|
+
artifact IDs to hash strings.
|
|
174
|
+
|
|
175
|
+
Args:
|
|
176
|
+
composition: The composition that owns the artifacts referenced here.
|
|
177
|
+
|
|
178
|
+
Returns:
|
|
179
|
+
Dict mapping relative file path to hash string.
|
|
180
|
+
"""
|
|
181
|
+
result: dict[str, str] = {}
|
|
182
|
+
for location in self.locations:
|
|
183
|
+
artifact = composition.get_by_id(location.artifact_id)
|
|
184
|
+
if artifact is not None:
|
|
185
|
+
result[location.path] = artifact.hash.to_string()
|
|
186
|
+
return result
|
|
187
|
+
|
|
188
|
+
# ------------------------------------------------------------------
|
|
189
|
+
# JSON-LD serialisation
|
|
190
|
+
# ------------------------------------------------------------------
|
|
191
|
+
|
|
192
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
193
|
+
return {
|
|
194
|
+
"@id": self.arrangement_id,
|
|
195
|
+
"@type": "trov:ArtifactArrangement",
|
|
196
|
+
"rdfs:comment": self.comment,
|
|
197
|
+
"trov:hasArtifactLocation": [
|
|
198
|
+
loc.to_jsonld() for loc in self._sorted_locations()
|
|
199
|
+
],
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
def _sorted_locations(self) -> list[ArtifactLocation]:
|
|
203
|
+
"""Return locations in a stable, machine-independent order.
|
|
204
|
+
|
|
205
|
+
Sorted by path so a declaration serialises identically wherever it was
|
|
206
|
+
produced; ``location_id`` breaks ties for the rare duplicate path.
|
|
207
|
+
"""
|
|
208
|
+
return sorted(
|
|
209
|
+
self.locations, key=lambda loc: (loc.path, natural_id_key(loc.location_id))
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
@classmethod
|
|
213
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "ArtifactArrangement":
|
|
214
|
+
"""Deserialise from a JSON-LD arrangement dict.
|
|
215
|
+
|
|
216
|
+
Args:
|
|
217
|
+
data: Dict with ``@id``, ``rdfs:comment``, ``trov:hasArtifactLocation``.
|
|
218
|
+
|
|
219
|
+
Returns:
|
|
220
|
+
:class:`ArtifactArrangement` instance.
|
|
221
|
+
"""
|
|
222
|
+
locations = [
|
|
223
|
+
ArtifactLocation.from_jsonld(loc)
|
|
224
|
+
for loc in data.get("trov:hasArtifactLocation", [])
|
|
225
|
+
]
|
|
226
|
+
return cls(
|
|
227
|
+
arrangement_id=data["@id"],
|
|
228
|
+
comment=data.get("rdfs:comment", ""),
|
|
229
|
+
locations=locations,
|
|
230
|
+
)
|
|
231
|
+
|
|
232
|
+
# ------------------------------------------------------------------
|
|
233
|
+
# Snapshot serialisation / deserialisation
|
|
234
|
+
# ------------------------------------------------------------------
|
|
235
|
+
|
|
236
|
+
def to_snapshot(self, composition: ArtifactComposition) -> dict[str, Any]:
|
|
237
|
+
"""Serialise this arrangement and its referenced artifacts as a standalone dict.
|
|
238
|
+
|
|
239
|
+
The returned structure is self-contained: it embeds the subset of
|
|
240
|
+
*composition* artifacts that are referenced by this arrangement so the
|
|
241
|
+
snapshot can be loaded into a different TRO without the original
|
|
242
|
+
composition.
|
|
243
|
+
|
|
244
|
+
Args:
|
|
245
|
+
composition: The composition that owns the artifacts referenced by
|
|
246
|
+
this arrangement.
|
|
247
|
+
|
|
248
|
+
Returns:
|
|
249
|
+
A JSON-serialisable dict.
|
|
250
|
+
"""
|
|
251
|
+
artifact_ids = {loc.artifact_id for loc in self.locations}
|
|
252
|
+
artifacts = sorted(
|
|
253
|
+
(
|
|
254
|
+
a.to_jsonld()
|
|
255
|
+
for a in composition.artifacts
|
|
256
|
+
if a.artifact_id in artifact_ids
|
|
257
|
+
),
|
|
258
|
+
key=lambda a: natural_id_key(a["@id"]),
|
|
259
|
+
)
|
|
260
|
+
return {
|
|
261
|
+
"@type": "trov:ArrangementSnapshot",
|
|
262
|
+
"rdfs:comment": self.comment,
|
|
263
|
+
"trov:hasArtifactLocation": [
|
|
264
|
+
loc.to_jsonld() for loc in self._sorted_locations()
|
|
265
|
+
],
|
|
266
|
+
"trov:hasArtifact": artifacts,
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
def save_snapshot(
|
|
270
|
+
self, filepath: str | pathlib.Path, composition: ArtifactComposition
|
|
271
|
+
) -> None:
|
|
272
|
+
"""Write this arrangement as a standalone snapshot JSON-LD file.
|
|
273
|
+
|
|
274
|
+
Args:
|
|
275
|
+
filepath: Destination path (will be created/overwritten).
|
|
276
|
+
composition: The composition that owns the referenced artifacts.
|
|
277
|
+
"""
|
|
278
|
+
with open(filepath, "w") as f:
|
|
279
|
+
json.dump(self.to_snapshot(composition), f, indent=2, sort_keys=True)
|
|
280
|
+
|
|
281
|
+
@classmethod
|
|
282
|
+
def from_snapshot(
|
|
283
|
+
cls,
|
|
284
|
+
data: dict[str, Any],
|
|
285
|
+
target_composition: ArtifactComposition,
|
|
286
|
+
arrangement_id: str,
|
|
287
|
+
comment: str | None = None,
|
|
288
|
+
) -> "ArtifactArrangement":
|
|
289
|
+
"""Merge snapshot data into *target_composition* and return a new arrangement.
|
|
290
|
+
|
|
291
|
+
Artifacts are matched by content hash so duplicates are never inserted.
|
|
292
|
+
Location IDs are rewritten to fit the new *arrangement_id*.
|
|
293
|
+
|
|
294
|
+
Args:
|
|
295
|
+
data: Dict previously produced by :meth:`to_snapshot`.
|
|
296
|
+
target_composition: The composition to merge artifacts into.
|
|
297
|
+
arrangement_id: The ``@id`` to assign to the new arrangement.
|
|
298
|
+
comment: Override the comment stored in *data* when provided.
|
|
299
|
+
|
|
300
|
+
Returns:
|
|
301
|
+
A new :class:`ArtifactArrangement` whose locations point to
|
|
302
|
+
artifacts in *target_composition*.
|
|
303
|
+
"""
|
|
304
|
+
from .artifact import ResearchArtifact
|
|
305
|
+
|
|
306
|
+
# Build a local lookup: snapshot-local artifact @id to ResearchArtifact
|
|
307
|
+
snap_artifacts: dict[str, ResearchArtifact] = {
|
|
308
|
+
art_data["@id"]: ResearchArtifact.from_jsonld(art_data)
|
|
309
|
+
for art_data in data.get("trov:hasArtifact", [])
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
# Merge each snapshot artifact into the target composition, tracking
|
|
313
|
+
# IDs. Iterate in a fixed order: this decides the @id each artifact
|
|
314
|
+
# gets in the target composition.
|
|
315
|
+
id_remap: dict[str, str] = {} # snapshot_id to target composition id
|
|
316
|
+
for snap_id in sorted(snap_artifacts, key=natural_id_key):
|
|
317
|
+
artifact = snap_artifacts[snap_id]
|
|
318
|
+
hash_str = artifact.hash.to_string()
|
|
319
|
+
existing = target_composition.get_by_hash(hash_str)
|
|
320
|
+
if existing is not None:
|
|
321
|
+
id_remap[snap_id] = existing.artifact_id
|
|
322
|
+
else:
|
|
323
|
+
new_id = target_composition.next_artifact_id()
|
|
324
|
+
target_composition.add_artifact(
|
|
325
|
+
ResearchArtifact(
|
|
326
|
+
artifact_id=new_id,
|
|
327
|
+
hash=artifact.hash,
|
|
328
|
+
mime_type=artifact.mime_type,
|
|
329
|
+
)
|
|
330
|
+
)
|
|
331
|
+
id_remap[snap_id] = new_id
|
|
332
|
+
|
|
333
|
+
# Rebuild locations with remapped artifact IDs, in path order so the
|
|
334
|
+
# new location @ids do not depend on the snapshot's internal ordering.
|
|
335
|
+
locations: list[ArtifactLocation] = []
|
|
336
|
+
raw_locations = sorted(
|
|
337
|
+
data.get("trov:hasArtifactLocation", []),
|
|
338
|
+
key=lambda loc: (loc["trov:path"], natural_id_key(loc["@id"])),
|
|
339
|
+
)
|
|
340
|
+
for i, loc_data in enumerate(raw_locations):
|
|
341
|
+
snap_art_id = loc_data["trov:artifact"]["@id"]
|
|
342
|
+
locations.append(
|
|
343
|
+
ArtifactLocation(
|
|
344
|
+
location_id=f"{arrangement_id}/location/{i}",
|
|
345
|
+
artifact_id=id_remap[snap_art_id],
|
|
346
|
+
path=loc_data["trov:path"],
|
|
347
|
+
)
|
|
348
|
+
)
|
|
349
|
+
|
|
350
|
+
return cls(
|
|
351
|
+
arrangement_id=arrangement_id,
|
|
352
|
+
comment=comment if comment is not None else data.get("rdfs:comment", ""),
|
|
353
|
+
locations=locations,
|
|
354
|
+
)
|
|
355
|
+
|
|
356
|
+
@classmethod
|
|
357
|
+
def load_snapshot(
|
|
358
|
+
cls,
|
|
359
|
+
filepath: str | pathlib.Path,
|
|
360
|
+
target_composition: ArtifactComposition,
|
|
361
|
+
arrangement_id: str,
|
|
362
|
+
comment: str | None = None,
|
|
363
|
+
) -> "ArtifactArrangement":
|
|
364
|
+
"""Load a snapshot file and merge it into *target_composition*.
|
|
365
|
+
|
|
366
|
+
Args:
|
|
367
|
+
filepath: Path to a JSON-LD snapshot file previously saved with
|
|
368
|
+
:meth:`save_snapshot`.
|
|
369
|
+
target_composition: The composition to merge artifacts into.
|
|
370
|
+
arrangement_id: The ``@id`` to assign to the new arrangement.
|
|
371
|
+
comment: Override the comment stored in the file when provided.
|
|
372
|
+
|
|
373
|
+
Returns:
|
|
374
|
+
A new :class:`ArtifactArrangement`.
|
|
375
|
+
"""
|
|
376
|
+
with open(filepath) as f:
|
|
377
|
+
data = json.load(f)
|
|
378
|
+
return cls.from_snapshot(data, target_composition, arrangement_id, comment)
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
"""ResearchArtifact model.
|
|
2
|
+
|
|
3
|
+
Represents a single research artifact (file) tracked within a TRO
|
|
4
|
+
composition, including its content hash and MIME type.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import hashlib
|
|
10
|
+
import pathlib
|
|
11
|
+
from dataclasses import dataclass
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
from ._base import TROVModel
|
|
15
|
+
from .hash_value import HashValue
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass
|
|
19
|
+
class ResearchArtifact(TROVModel):
|
|
20
|
+
"""A single research artifact stored in an :class:`ArtifactComposition`."""
|
|
21
|
+
|
|
22
|
+
artifact_id: str
|
|
23
|
+
hash: HashValue
|
|
24
|
+
mime_type: str
|
|
25
|
+
|
|
26
|
+
# ------------------------------------------------------------------
|
|
27
|
+
# Convenience constructors
|
|
28
|
+
# ------------------------------------------------------------------
|
|
29
|
+
|
|
30
|
+
@classmethod
|
|
31
|
+
def from_file(
|
|
32
|
+
cls, path: str | pathlib.Path, artifact_id: str
|
|
33
|
+
) -> "ResearchArtifact":
|
|
34
|
+
"""Create a ``ResearchArtifact`` by hashing a file on disk.
|
|
35
|
+
|
|
36
|
+
Args:
|
|
37
|
+
path: Absolute or relative path to the file.
|
|
38
|
+
artifact_id: The ``@id`` to assign (e.g. ``"composition/1/artifact/3"``).
|
|
39
|
+
|
|
40
|
+
Returns:
|
|
41
|
+
A new :class:`ResearchArtifact`.
|
|
42
|
+
|
|
43
|
+
Raises:
|
|
44
|
+
FileNotFoundError: If *path* does not point to an existing regular file.
|
|
45
|
+
"""
|
|
46
|
+
import magic # local import — optional dep
|
|
47
|
+
|
|
48
|
+
p = pathlib.Path(path)
|
|
49
|
+
if not p.is_file():
|
|
50
|
+
raise FileNotFoundError(f"Not a regular file: {p}")
|
|
51
|
+
|
|
52
|
+
sha256 = hashlib.sha256()
|
|
53
|
+
with open(p, "rb") as f:
|
|
54
|
+
for chunk in iter(lambda: f.read(4096), b""):
|
|
55
|
+
sha256.update(chunk)
|
|
56
|
+
|
|
57
|
+
hash_value = HashValue(algorithm="sha256", value=sha256.hexdigest())
|
|
58
|
+
|
|
59
|
+
if p.is_symlink():
|
|
60
|
+
mime_type = "inode/symlink"
|
|
61
|
+
else:
|
|
62
|
+
magic_wrapper = magic.Magic(mime=True, uncompress=False)
|
|
63
|
+
mime_type = magic_wrapper.from_file(str(p)) or "application/octet-stream"
|
|
64
|
+
|
|
65
|
+
return cls(artifact_id=artifact_id, hash=hash_value, mime_type=mime_type)
|
|
66
|
+
|
|
67
|
+
# ------------------------------------------------------------------
|
|
68
|
+
# JSON-LD serialisation
|
|
69
|
+
# ------------------------------------------------------------------
|
|
70
|
+
|
|
71
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
72
|
+
return {
|
|
73
|
+
"@id": self.artifact_id,
|
|
74
|
+
"@type": "trov:ResearchArtifact",
|
|
75
|
+
"trov:hash": self.hash.to_jsonld(),
|
|
76
|
+
"trov:mimeType": self.mime_type,
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
@classmethod
|
|
80
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "ResearchArtifact":
|
|
81
|
+
"""Deserialise from a JSON-LD artifact dict.
|
|
82
|
+
|
|
83
|
+
Args:
|
|
84
|
+
data: Dict with ``@id``, ``trov:hash``/``trov:sha256``, ``trov:mimeType``.
|
|
85
|
+
|
|
86
|
+
Returns:
|
|
87
|
+
:class:`ResearchArtifact` instance.
|
|
88
|
+
"""
|
|
89
|
+
# Support both new trov:hash and legacy trov:sha256
|
|
90
|
+
if "trov:hash" in data:
|
|
91
|
+
h = HashValue.from_jsonld(data["trov:hash"])
|
|
92
|
+
elif "trov:sha256" in data:
|
|
93
|
+
h = HashValue(algorithm="sha256", value=data["trov:sha256"])
|
|
94
|
+
else:
|
|
95
|
+
raise ValueError(f"Artifact has no recognisable hash field: {data!r}")
|
|
96
|
+
|
|
97
|
+
return cls(
|
|
98
|
+
artifact_id=data["@id"],
|
|
99
|
+
hash=h,
|
|
100
|
+
mime_type=data.get("trov:mimeType", "application/octet-stream"),
|
|
101
|
+
)
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""TROAttribute model.
|
|
2
|
+
|
|
3
|
+
Represents a TRO-level attribute warranted by a performance attribute.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
from ._base import TROVModel
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@dataclass
|
|
15
|
+
class TROAttribute(TROVModel):
|
|
16
|
+
"""A TRO-level attribute (e.g. ``trov:IncludesAllInputData``).
|
|
17
|
+
|
|
18
|
+
TRO attributes are warranted by one or more
|
|
19
|
+
:class:`~tro_utils.models.performance.PerformanceAttribute` instances.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
attribute_id: str
|
|
23
|
+
attribute_type: str
|
|
24
|
+
warranted_by_id: str
|
|
25
|
+
|
|
26
|
+
# ------------------------------------------------------------------
|
|
27
|
+
# JSON-LD serialisation
|
|
28
|
+
# ------------------------------------------------------------------
|
|
29
|
+
|
|
30
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
31
|
+
return {
|
|
32
|
+
"@id": self.attribute_id,
|
|
33
|
+
"@type": self.attribute_type,
|
|
34
|
+
"trov:warrantedBy": {"@id": self.warranted_by_id},
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
@classmethod
|
|
38
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "TROAttribute":
|
|
39
|
+
"""Deserialise from a JSON-LD TRO attribute dict.
|
|
40
|
+
|
|
41
|
+
Args:
|
|
42
|
+
data: Dict with ``@id``, ``@type``, ``trov:warrantedBy``.
|
|
43
|
+
|
|
44
|
+
Returns:
|
|
45
|
+
:class:`TROAttribute` instance.
|
|
46
|
+
"""
|
|
47
|
+
return cls(
|
|
48
|
+
attribute_id=data["@id"],
|
|
49
|
+
attribute_type=data["@type"],
|
|
50
|
+
warranted_by_id=data["trov:warrantedBy"]["@id"],
|
|
51
|
+
)
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
"""ArtifactComposition and CompositionFingerprint models."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from ._base import TROVModel, natural_id_key
|
|
10
|
+
from .artifact import ResearchArtifact
|
|
11
|
+
from .hash_value import HashValue
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@dataclass(frozen=True)
|
|
15
|
+
class CompositionFingerprint(TROVModel):
|
|
16
|
+
"""SHA-256 fingerprint over the sorted artifact hashes in a composition."""
|
|
17
|
+
|
|
18
|
+
hash: HashValue
|
|
19
|
+
|
|
20
|
+
@classmethod
|
|
21
|
+
def compute(cls, artifacts: list[ResearchArtifact]) -> "CompositionFingerprint":
|
|
22
|
+
"""Compute the fingerprint for a list of artifacts.
|
|
23
|
+
|
|
24
|
+
The fingerprint is sha256 of the sorted, concatenated artifact hash values,
|
|
25
|
+
matching the existing ``TRO.calculate_fingerprint`` logic.
|
|
26
|
+
|
|
27
|
+
Args:
|
|
28
|
+
artifacts: List of :class:`ResearchArtifact` to fingerprint.
|
|
29
|
+
|
|
30
|
+
Returns:
|
|
31
|
+
A new :class:`CompositionFingerprint`.
|
|
32
|
+
"""
|
|
33
|
+
hash_values = sorted(a.hash.value for a in artifacts)
|
|
34
|
+
digest = hashlib.sha256("".join(hash_values).encode("utf-8")).hexdigest()
|
|
35
|
+
return cls(hash=HashValue(algorithm="sha256", value=digest))
|
|
36
|
+
|
|
37
|
+
# ------------------------------------------------------------------
|
|
38
|
+
# JSON-LD serialisation
|
|
39
|
+
# ------------------------------------------------------------------
|
|
40
|
+
|
|
41
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
42
|
+
return {
|
|
43
|
+
"@id": "fingerprint",
|
|
44
|
+
"@type": "trov:CompositionFingerprint",
|
|
45
|
+
"trov:hash": self.hash.to_jsonld(),
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
@classmethod
|
|
49
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "CompositionFingerprint":
|
|
50
|
+
return cls(hash=HashValue.from_jsonld(data["trov:hash"]))
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
@dataclass
|
|
54
|
+
class ArtifactComposition(TROVModel):
|
|
55
|
+
"""Registry of all unique :class:`ResearchArtifact` objects in a TRO."""
|
|
56
|
+
|
|
57
|
+
composition_id: str = "composition/1"
|
|
58
|
+
artifacts: list[ResearchArtifact] = field(default_factory=list)
|
|
59
|
+
fingerprint: CompositionFingerprint | None = None
|
|
60
|
+
|
|
61
|
+
# ------------------------------------------------------------------
|
|
62
|
+
# Mutation
|
|
63
|
+
# ------------------------------------------------------------------
|
|
64
|
+
|
|
65
|
+
def add_artifact(self, artifact: ResearchArtifact) -> None:
|
|
66
|
+
"""Append *artifact* and recompute the fingerprint.
|
|
67
|
+
|
|
68
|
+
Args:
|
|
69
|
+
artifact: The artifact to add.
|
|
70
|
+
"""
|
|
71
|
+
self.artifacts.append(artifact)
|
|
72
|
+
self._recompute_fingerprint()
|
|
73
|
+
|
|
74
|
+
def _recompute_fingerprint(self) -> None:
|
|
75
|
+
self.fingerprint = CompositionFingerprint.compute(self.artifacts)
|
|
76
|
+
|
|
77
|
+
# ------------------------------------------------------------------
|
|
78
|
+
# Lookup helpers
|
|
79
|
+
# ------------------------------------------------------------------
|
|
80
|
+
|
|
81
|
+
def get_by_hash(self, hash_str: str) -> ResearchArtifact | None:
|
|
82
|
+
"""Return the artifact whose hash string matches *hash_str*, or ``None``.
|
|
83
|
+
|
|
84
|
+
Args:
|
|
85
|
+
hash_str: Hash string in ``"<algorithm>:<value>"`` form.
|
|
86
|
+
"""
|
|
87
|
+
for artifact in self.artifacts:
|
|
88
|
+
if artifact.hash.to_string() == hash_str:
|
|
89
|
+
return artifact
|
|
90
|
+
return None
|
|
91
|
+
|
|
92
|
+
def get_by_id(self, artifact_id: str) -> ResearchArtifact | None:
|
|
93
|
+
"""Return the artifact with the given ``@id``, or ``None``."""
|
|
94
|
+
for artifact in self.artifacts:
|
|
95
|
+
if artifact.artifact_id == artifact_id:
|
|
96
|
+
return artifact
|
|
97
|
+
return None
|
|
98
|
+
|
|
99
|
+
def next_artifact_id(self) -> str:
|
|
100
|
+
"""Return the next sequential artifact ``@id``."""
|
|
101
|
+
return f"{self.composition_id}/artifact/{len(self.artifacts)}"
|
|
102
|
+
|
|
103
|
+
# ------------------------------------------------------------------
|
|
104
|
+
# JSON-LD serialisation
|
|
105
|
+
# ------------------------------------------------------------------
|
|
106
|
+
|
|
107
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
108
|
+
result: dict[str, Any] = {
|
|
109
|
+
"@id": self.composition_id,
|
|
110
|
+
"@type": "trov:ArtifactComposition",
|
|
111
|
+
"trov:hasArtifact": sorted(
|
|
112
|
+
[a.to_jsonld() for a in self.artifacts],
|
|
113
|
+
key=lambda x: natural_id_key(x["@id"]),
|
|
114
|
+
),
|
|
115
|
+
}
|
|
116
|
+
if self.fingerprint:
|
|
117
|
+
result["trov:hasFingerprint"] = self.fingerprint.to_jsonld()
|
|
118
|
+
return result
|
|
119
|
+
|
|
120
|
+
@classmethod
|
|
121
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "ArtifactComposition":
|
|
122
|
+
"""Deserialise from a JSON-LD composition dict.
|
|
123
|
+
|
|
124
|
+
Args:
|
|
125
|
+
data: Dict with ``@id``, ``trov:hasArtifact`` list, and optional fingerprint.
|
|
126
|
+
|
|
127
|
+
Returns:
|
|
128
|
+
:class:`ArtifactComposition` instance.
|
|
129
|
+
"""
|
|
130
|
+
artifacts = [
|
|
131
|
+
ResearchArtifact.from_jsonld(a) for a in data.get("trov:hasArtifact", [])
|
|
132
|
+
]
|
|
133
|
+
fingerprint = None
|
|
134
|
+
if "trov:hasFingerprint" in data:
|
|
135
|
+
fingerprint = CompositionFingerprint.from_jsonld(
|
|
136
|
+
data["trov:hasFingerprint"]
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
obj = cls(
|
|
140
|
+
composition_id=data.get("@id", "composition/1"),
|
|
141
|
+
artifacts=artifacts,
|
|
142
|
+
fingerprint=fingerprint,
|
|
143
|
+
)
|
|
144
|
+
return obj
|