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
tro_utils/models/tro.py
ADDED
|
@@ -0,0 +1,509 @@
|
|
|
1
|
+
"""TransparentResearchObject root model.
|
|
2
|
+
|
|
3
|
+
This is the top-level object that maps directly to the ``tro`` node in the
|
|
4
|
+
JSON-LD ``@graph`` and owns all other model objects.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import datetime
|
|
10
|
+
import json
|
|
11
|
+
import pathlib
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
from packaging.version import Version
|
|
16
|
+
|
|
17
|
+
from ._base import TROVModel, aware_now, ensure_aware
|
|
18
|
+
from .agent import ORGANIZATION, Agent
|
|
19
|
+
from .arrangement import ArtifactArrangement
|
|
20
|
+
from .attribute import TROAttribute
|
|
21
|
+
from .composition import ArtifactComposition
|
|
22
|
+
from .performance import (
|
|
23
|
+
ArrangementBinding,
|
|
24
|
+
PerformanceAttribute,
|
|
25
|
+
TrustedResearchPerformance,
|
|
26
|
+
)
|
|
27
|
+
from .trs import TrustedResearchSystem, validate_capability_id, validate_trs_id
|
|
28
|
+
from .tsa import TimeStampingAuthority
|
|
29
|
+
|
|
30
|
+
TROV_VOCABULARY_VERSION = Version("0.1")
|
|
31
|
+
|
|
32
|
+
_JSONLD_CONTEXT = {
|
|
33
|
+
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
|
|
34
|
+
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
|
|
35
|
+
"trov": f"https://w3id.org/trace/trov/{TROV_VOCABULARY_VERSION}#",
|
|
36
|
+
"schema": "https://schema.org/",
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _parse_creator(raw: Any) -> Agent | None:
|
|
41
|
+
"""Parse a ``schema:creator`` value, or ``None`` when absent.
|
|
42
|
+
|
|
43
|
+
``None`` lets :class:`TransparentResearchObject` fall back to the TRS.
|
|
44
|
+
A list (schema.org permits several creators) keeps only the first entry;
|
|
45
|
+
multiple creators are not modelled.
|
|
46
|
+
"""
|
|
47
|
+
if isinstance(raw, list):
|
|
48
|
+
raw = raw[0] if raw else None
|
|
49
|
+
if raw is None or raw == "":
|
|
50
|
+
return None
|
|
51
|
+
return Agent.coerce(raw)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass
|
|
55
|
+
class TransparentResearchObject(TROVModel):
|
|
56
|
+
"""Root object representing a full Transparent Research Object (TRO)."""
|
|
57
|
+
|
|
58
|
+
tro_id: str = "tro"
|
|
59
|
+
name: str = "Some TRO"
|
|
60
|
+
description: str = "Some description"
|
|
61
|
+
# An Agent, a JSON-LD agent dict, or a bare name (treated as an
|
|
62
|
+
# organization). None mirrors the TRS -- see __post_init__.
|
|
63
|
+
creator: Agent | dict | str | None = None
|
|
64
|
+
date_created: datetime.datetime = field(default_factory=aware_now)
|
|
65
|
+
vocabulary_version: str = str(TROV_VOCABULARY_VERSION)
|
|
66
|
+
trs: TrustedResearchSystem = field(default_factory=TrustedResearchSystem)
|
|
67
|
+
tsa: TimeStampingAuthority | None = None
|
|
68
|
+
created_with_name: str | None = None
|
|
69
|
+
created_with_version: str | None = None
|
|
70
|
+
composition: ArtifactComposition = field(default_factory=ArtifactComposition)
|
|
71
|
+
arrangements: list[ArtifactArrangement] = field(default_factory=list)
|
|
72
|
+
performances: list[TrustedResearchPerformance] = field(default_factory=list)
|
|
73
|
+
attributes: list[TROAttribute] = field(default_factory=list)
|
|
74
|
+
extra_context: dict = field(default_factory=dict)
|
|
75
|
+
|
|
76
|
+
def __post_init__(self) -> None:
|
|
77
|
+
# ``schema:dateCreated`` must be unambiguous; a naive value is read as
|
|
78
|
+
# local wall-clock time. See ``ensure_aware``.
|
|
79
|
+
self.date_created = ensure_aware(self.date_created)
|
|
80
|
+
# ``schema:creator`` is an agent node, never a bare name. With no
|
|
81
|
+
# creator given, credit the TRS that assembled this TRO.
|
|
82
|
+
if self.creator is None:
|
|
83
|
+
self.creator = self._creator_from_trs()
|
|
84
|
+
else:
|
|
85
|
+
self.creator = Agent.coerce(self.creator)
|
|
86
|
+
|
|
87
|
+
def _creator_from_trs(self) -> Agent:
|
|
88
|
+
"""Return the TRS as a ``schema:Organization`` creator.
|
|
89
|
+
|
|
90
|
+
The TRS is already typed ``schema:Organization`` under
|
|
91
|
+
``trov:wasAssembledBy``, so reference it by the same ``@id``.
|
|
92
|
+
"""
|
|
93
|
+
return Agent(
|
|
94
|
+
name=self.trs.name or "TRO utils",
|
|
95
|
+
agent_type=ORGANIZATION,
|
|
96
|
+
agent_id=self.trs.trs_id or None,
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
# ------------------------------------------------------------------
|
|
100
|
+
# File I/O
|
|
101
|
+
# ------------------------------------------------------------------
|
|
102
|
+
|
|
103
|
+
@classmethod
|
|
104
|
+
def load(cls, filepath: str | pathlib.Path) -> "TransparentResearchObject":
|
|
105
|
+
"""Deserialise a TRO from a JSON-LD file on disk.
|
|
106
|
+
|
|
107
|
+
Args:
|
|
108
|
+
filepath: Path to the ``.jsonld`` file.
|
|
109
|
+
|
|
110
|
+
Returns:
|
|
111
|
+
:class:`TransparentResearchObject` instance.
|
|
112
|
+
|
|
113
|
+
Raises:
|
|
114
|
+
RuntimeError: If the file was created with an incompatible vocabulary version.
|
|
115
|
+
"""
|
|
116
|
+
with open(filepath) as f:
|
|
117
|
+
raw = json.load(f)
|
|
118
|
+
return cls.from_jsonld(raw)
|
|
119
|
+
|
|
120
|
+
def save(self, filepath: str | pathlib.Path) -> None:
|
|
121
|
+
"""Serialise this TRO to a JSON-LD file on disk.
|
|
122
|
+
|
|
123
|
+
A declaration predating the TRS identifier rule loads fine but cannot
|
|
124
|
+
be written back out until its TRS carries a conforming ``@id``, so
|
|
125
|
+
that nothing non-conforming is written from here on.
|
|
126
|
+
|
|
127
|
+
Args:
|
|
128
|
+
filepath: Destination path (will be created/overwritten).
|
|
129
|
+
|
|
130
|
+
Raises:
|
|
131
|
+
ValueError: If the TRS ``@id``, a capability ``@id``, or a
|
|
132
|
+
performance attribute's ``trov:warrantedBy`` does not conform.
|
|
133
|
+
See :func:`~tro_utils.models.trs.validate_trs_id` and
|
|
134
|
+
:func:`~tro_utils.models.trs.validate_capability_id`.
|
|
135
|
+
"""
|
|
136
|
+
validate_trs_id(self.trs.trs_id, "TRS @id")
|
|
137
|
+
self._validate_capability_references()
|
|
138
|
+
# The signature covers the LF-terminated serialization, so keep it
|
|
139
|
+
# byte-for-byte on disk on every platform.
|
|
140
|
+
with open(filepath, "w", newline="\n") as f:
|
|
141
|
+
json.dump(self.to_jsonld(), f, indent=2, sort_keys=True)
|
|
142
|
+
|
|
143
|
+
def _validate_capability_references(self) -> None:
|
|
144
|
+
"""Check that capabilities, and the warrants pointing at them, conform.
|
|
145
|
+
|
|
146
|
+
A capability belongs to the TRS rather than to this declaration, so
|
|
147
|
+
both its own ``@id`` and every ``trov:warrantedBy`` that refers to it
|
|
148
|
+
have to name it the same way in any document -- a relative id resolves
|
|
149
|
+
against whichever document happens to contain it.
|
|
150
|
+
"""
|
|
151
|
+
for capability in self.trs.capabilities:
|
|
152
|
+
validate_capability_id(
|
|
153
|
+
capability.capability_id,
|
|
154
|
+
f"capability @id for {capability.capability_type!r}",
|
|
155
|
+
)
|
|
156
|
+
for performance in self.performances:
|
|
157
|
+
for attribute in performance.attributes:
|
|
158
|
+
validate_capability_id(
|
|
159
|
+
attribute.warranted_by_id,
|
|
160
|
+
f"trov:warrantedBy of {attribute.attribute_id!r}",
|
|
161
|
+
)
|
|
162
|
+
|
|
163
|
+
# ------------------------------------------------------------------
|
|
164
|
+
# High-level mutation helpers
|
|
165
|
+
# ------------------------------------------------------------------
|
|
166
|
+
|
|
167
|
+
def add_arrangement(
|
|
168
|
+
self,
|
|
169
|
+
directory: str | pathlib.Path,
|
|
170
|
+
comment: str | None = None,
|
|
171
|
+
ignore_dirs: list[str] | None = None,
|
|
172
|
+
resolve_symlinks: bool = True,
|
|
173
|
+
) -> ArtifactArrangement:
|
|
174
|
+
"""Scan *directory* and add a new arrangement (updating the composition).
|
|
175
|
+
|
|
176
|
+
Args:
|
|
177
|
+
directory: Directory to scan.
|
|
178
|
+
comment: Human-readable label for this arrangement snapshot.
|
|
179
|
+
ignore_dirs: Directory names to exclude (default: ``[".git"]``).
|
|
180
|
+
resolve_symlinks: Whether to follow symlinks.
|
|
181
|
+
|
|
182
|
+
Returns:
|
|
183
|
+
The newly created :class:`ArtifactArrangement`.
|
|
184
|
+
"""
|
|
185
|
+
arrangement_id = f"arrangement/{len(self.arrangements)}"
|
|
186
|
+
arrangement = ArtifactArrangement.from_directory(
|
|
187
|
+
directory=directory,
|
|
188
|
+
composition=self.composition,
|
|
189
|
+
arrangement_id=arrangement_id,
|
|
190
|
+
comment=comment,
|
|
191
|
+
ignore_dirs=ignore_dirs,
|
|
192
|
+
resolve_symlinks=resolve_symlinks,
|
|
193
|
+
)
|
|
194
|
+
self.arrangements.append(arrangement)
|
|
195
|
+
return arrangement
|
|
196
|
+
|
|
197
|
+
def add_arrangement_from_snapshot(
|
|
198
|
+
self,
|
|
199
|
+
filepath: str | pathlib.Path,
|
|
200
|
+
comment: str | None = None,
|
|
201
|
+
) -> ArtifactArrangement:
|
|
202
|
+
"""Load a pre-computed arrangement snapshot and merge it into this TRO.
|
|
203
|
+
|
|
204
|
+
Artifacts in the snapshot are merged into the existing composition by
|
|
205
|
+
content hash, avoiding duplicate entries.
|
|
206
|
+
|
|
207
|
+
Args:
|
|
208
|
+
filepath: Path to a JSON-LD snapshot file produced by
|
|
209
|
+
:meth:`~tro_utils.models.arrangement.ArtifactArrangement.save_snapshot`.
|
|
210
|
+
comment: Override the comment stored in the snapshot file.
|
|
211
|
+
|
|
212
|
+
Returns:
|
|
213
|
+
The newly added :class:`ArtifactArrangement`.
|
|
214
|
+
"""
|
|
215
|
+
arrangement_id = f"arrangement/{len(self.arrangements)}"
|
|
216
|
+
arrangement = ArtifactArrangement.load_snapshot(
|
|
217
|
+
filepath=filepath,
|
|
218
|
+
target_composition=self.composition,
|
|
219
|
+
arrangement_id=arrangement_id,
|
|
220
|
+
comment=comment,
|
|
221
|
+
)
|
|
222
|
+
self.arrangements.append(arrangement)
|
|
223
|
+
return arrangement
|
|
224
|
+
|
|
225
|
+
def add_performance(
|
|
226
|
+
self,
|
|
227
|
+
start_time: datetime.datetime,
|
|
228
|
+
end_time: datetime.datetime,
|
|
229
|
+
comment: str | None = None,
|
|
230
|
+
accessed_arrangement: "str | tuple[str, str | None] | list[str | tuple[str, str | None]] | None" = None,
|
|
231
|
+
modified_arrangement: "str | tuple[str, str | None] | list[str | tuple[str, str | None]] | None" = None,
|
|
232
|
+
attrs: list | None = None,
|
|
233
|
+
extra_attributes: dict[str, Any] | None = None,
|
|
234
|
+
) -> TrustedResearchPerformance:
|
|
235
|
+
"""Record a new performance (execution run).
|
|
236
|
+
|
|
237
|
+
Mirrors the logic of ``TRO.add_performance`` in ``tro_utils.py``.
|
|
238
|
+
|
|
239
|
+
Args:
|
|
240
|
+
start_time: When execution started.
|
|
241
|
+
end_time: When execution ended.
|
|
242
|
+
comment: Human-readable description.
|
|
243
|
+
accessed_arrangement: Input arrangement(s). Each item may be a
|
|
244
|
+
bare ``@id`` string or a ``(arrangement_id, mount_path)`` tuple.
|
|
245
|
+
A single value or a list is accepted.
|
|
246
|
+
modified_arrangement: Output arrangement(s). Same flexible input
|
|
247
|
+
as *accessed_arrangement*.
|
|
248
|
+
attrs: List of :class:`~tro_utils.TRPAttribute` members (or their
|
|
249
|
+
string values) to record as performance attributes.
|
|
250
|
+
extra_attributes: Additional raw key/value pairs to merge into the
|
|
251
|
+
performance JSON-LD (for forward compatibility).
|
|
252
|
+
|
|
253
|
+
Returns:
|
|
254
|
+
The newly created :class:`TrustedResearchPerformance`.
|
|
255
|
+
|
|
256
|
+
Raises:
|
|
257
|
+
ValueError: If a referenced arrangement does not exist, or if a
|
|
258
|
+
required TRS capability is missing.
|
|
259
|
+
"""
|
|
260
|
+
from tro_utils import (
|
|
261
|
+
TRPAttribute,
|
|
262
|
+
TROVCapability,
|
|
263
|
+
) # avoid circular at module level
|
|
264
|
+
|
|
265
|
+
if attrs is None:
|
|
266
|
+
attrs = []
|
|
267
|
+
if extra_attributes is None:
|
|
268
|
+
extra_attributes = {}
|
|
269
|
+
|
|
270
|
+
def _normalise_refs(value: Any) -> list[tuple[str, str | None]]:
|
|
271
|
+
"""Accept str | (str, str|None) | list[...] | None → list[(arrangement_id, path)]."""
|
|
272
|
+
if value is None:
|
|
273
|
+
return []
|
|
274
|
+
if isinstance(value, (str, tuple)):
|
|
275
|
+
value = [value]
|
|
276
|
+
return [item if isinstance(item, tuple) else (item, None) for item in value]
|
|
277
|
+
|
|
278
|
+
accessed_refs = _normalise_refs(accessed_arrangement)
|
|
279
|
+
modified_refs = _normalise_refs(modified_arrangement)
|
|
280
|
+
|
|
281
|
+
available_ids = {arr.arrangement_id for arr in self.arrangements}
|
|
282
|
+
|
|
283
|
+
for arr_id, _ in accessed_refs:
|
|
284
|
+
if arr_id not in available_ids:
|
|
285
|
+
raise ValueError(
|
|
286
|
+
f"Arrangement {arr_id!r} does not exist. "
|
|
287
|
+
f"Available: {sorted(available_ids)}"
|
|
288
|
+
)
|
|
289
|
+
for arr_id, _ in modified_refs:
|
|
290
|
+
if arr_id not in available_ids:
|
|
291
|
+
raise ValueError(
|
|
292
|
+
f"Arrangement {arr_id!r} does not exist. "
|
|
293
|
+
f"Available: {sorted(available_ids)}"
|
|
294
|
+
)
|
|
295
|
+
|
|
296
|
+
trs_caps = {
|
|
297
|
+
cap.capability_type: cap.capability_id for cap in self.trs.capabilities
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
performance_id = f"trp/{len(self.performances)}"
|
|
301
|
+
|
|
302
|
+
# Build ArrangementBinding objects with auto-generated IDs. A single
|
|
303
|
+
# counter across both lists keeps IDs unique within the performance.
|
|
304
|
+
binding_idx = 0
|
|
305
|
+
accessed_bindings: list[ArrangementBinding] = []
|
|
306
|
+
for arr_id, path in accessed_refs:
|
|
307
|
+
accessed_bindings.append(
|
|
308
|
+
ArrangementBinding(
|
|
309
|
+
binding_id=f"{performance_id}/binding/{binding_idx}",
|
|
310
|
+
arrangement_id=arr_id,
|
|
311
|
+
path=path,
|
|
312
|
+
)
|
|
313
|
+
)
|
|
314
|
+
binding_idx += 1
|
|
315
|
+
|
|
316
|
+
modified_bindings: list[ArrangementBinding] = []
|
|
317
|
+
for arr_id, path in modified_refs:
|
|
318
|
+
modified_bindings.append(
|
|
319
|
+
ArrangementBinding(
|
|
320
|
+
binding_id=f"{performance_id}/binding/{binding_idx}",
|
|
321
|
+
arrangement_id=arr_id,
|
|
322
|
+
path=path,
|
|
323
|
+
)
|
|
324
|
+
)
|
|
325
|
+
binding_idx += 1
|
|
326
|
+
|
|
327
|
+
performance_attributes: list[PerformanceAttribute] = []
|
|
328
|
+
for i, attr in enumerate(attrs):
|
|
329
|
+
if isinstance(attr, str):
|
|
330
|
+
attr = TRPAttribute(attr)
|
|
331
|
+
cap = TROVCapability.translate(attr)
|
|
332
|
+
if cap.value not in trs_caps:
|
|
333
|
+
raise ValueError(
|
|
334
|
+
f"Capability {cap.value!r} required for attribute {attr.value!r} "
|
|
335
|
+
f"but not present in TRS capabilities: {list(trs_caps.keys())}"
|
|
336
|
+
)
|
|
337
|
+
performance_attributes.append(
|
|
338
|
+
PerformanceAttribute(
|
|
339
|
+
attribute_id=f"{performance_id}/attribute/{i}",
|
|
340
|
+
attribute_type=attr.value,
|
|
341
|
+
warranted_by_id=trs_caps[cap.value],
|
|
342
|
+
)
|
|
343
|
+
)
|
|
344
|
+
|
|
345
|
+
trp = TrustedResearchPerformance(
|
|
346
|
+
performance_id=performance_id,
|
|
347
|
+
comment=comment or "Some performance",
|
|
348
|
+
conducted_by_id=self.trs.trs_id,
|
|
349
|
+
started_at=start_time,
|
|
350
|
+
ended_at=end_time,
|
|
351
|
+
accessed_arrangements=accessed_bindings,
|
|
352
|
+
contributed_to_arrangements=modified_bindings,
|
|
353
|
+
attributes=performance_attributes,
|
|
354
|
+
)
|
|
355
|
+
|
|
356
|
+
if extra_attributes:
|
|
357
|
+
trp.extra_attributes = extra_attributes
|
|
358
|
+
|
|
359
|
+
self.performances.append(trp)
|
|
360
|
+
return trp
|
|
361
|
+
|
|
362
|
+
# ------------------------------------------------------------------
|
|
363
|
+
# JSON-LD serialisation
|
|
364
|
+
# ------------------------------------------------------------------
|
|
365
|
+
|
|
366
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
367
|
+
graph_node: dict[str, Any] = {
|
|
368
|
+
"@id": self.tro_id,
|
|
369
|
+
"@type": ["trov:TransparentResearchObject", "schema:CreativeWork"],
|
|
370
|
+
"schema:creator": Agent.coerce(self.creator).to_jsonld(),
|
|
371
|
+
"schema:dateCreated": ensure_aware(self.date_created).isoformat(),
|
|
372
|
+
"schema:description": self.description,
|
|
373
|
+
"schema:name": self.name,
|
|
374
|
+
"trov:vocabularyVersion": self.vocabulary_version,
|
|
375
|
+
"trov:wasAssembledBy": self.trs.to_jsonld(),
|
|
376
|
+
"trov:hasComposition": self.composition.to_jsonld(),
|
|
377
|
+
"trov:hasArrangement": [arr.to_jsonld() for arr in self.arrangements],
|
|
378
|
+
"trov:hasPerformance": [perf.to_jsonld() for perf in self.performances],
|
|
379
|
+
"trov:hasAttribute": [attr.to_jsonld() for attr in self.attributes],
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
if self.tsa is not None:
|
|
383
|
+
graph_node["trov:wasTimestampedBy"] = self.tsa.to_jsonld()
|
|
384
|
+
|
|
385
|
+
if self.created_with_name or self.created_with_version:
|
|
386
|
+
created_with: dict[str, Any] = {
|
|
387
|
+
"@type": "schema:SoftwareApplication",
|
|
388
|
+
}
|
|
389
|
+
if self.created_with_name:
|
|
390
|
+
created_with["schema:name"] = self.created_with_name
|
|
391
|
+
if self.created_with_version:
|
|
392
|
+
created_with["schema:softwareVersion"] = self.created_with_version
|
|
393
|
+
graph_node["trov:createdWith"] = created_with
|
|
394
|
+
|
|
395
|
+
# Merge any extra_attributes from performances (forward compat)
|
|
396
|
+
for i, perf in enumerate(self.performances):
|
|
397
|
+
extra = getattr(perf, "_extra_attributes", {})
|
|
398
|
+
if extra:
|
|
399
|
+
graph_node["trov:hasPerformance"][i].update(extra)
|
|
400
|
+
|
|
401
|
+
return {
|
|
402
|
+
"@context": {**_JSONLD_CONTEXT, **self.extra_context},
|
|
403
|
+
"@graph": [graph_node],
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
@classmethod
|
|
407
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "TransparentResearchObject":
|
|
408
|
+
"""Deserialise a full TRO from its JSON-LD dict representation.
|
|
409
|
+
|
|
410
|
+
Args:
|
|
411
|
+
data: The top-level JSON-LD dict with ``@context`` and ``@graph``.
|
|
412
|
+
|
|
413
|
+
Returns:
|
|
414
|
+
:class:`TransparentResearchObject` instance.
|
|
415
|
+
|
|
416
|
+
Raises:
|
|
417
|
+
RuntimeError: If the vocabulary version is too old.
|
|
418
|
+
"""
|
|
419
|
+
graph = data["@graph"][0]
|
|
420
|
+
|
|
421
|
+
raw_context = data.get("@context", {})
|
|
422
|
+
if isinstance(raw_context, list):
|
|
423
|
+
# backward compat: merge list of dicts into a single dict
|
|
424
|
+
merged: dict = {}
|
|
425
|
+
for item in raw_context:
|
|
426
|
+
if isinstance(item, dict):
|
|
427
|
+
merged.update(item)
|
|
428
|
+
raw_context = merged
|
|
429
|
+
extra_context = {
|
|
430
|
+
k: v for k, v in raw_context.items() if k not in _JSONLD_CONTEXT
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
vocab_version = Version(graph.get("trov:vocabularyVersion", "0.0.1"))
|
|
434
|
+
if vocab_version < TROV_VOCABULARY_VERSION:
|
|
435
|
+
raise RuntimeError(
|
|
436
|
+
"Your TRO was created with an older version of the TRO vocabulary. "
|
|
437
|
+
"In order to properly parse it you need to use tro-utils < 0.3.0."
|
|
438
|
+
)
|
|
439
|
+
|
|
440
|
+
# TRS
|
|
441
|
+
trs = TrustedResearchSystem.from_jsonld(graph.get("trov:wasAssembledBy", {}))
|
|
442
|
+
|
|
443
|
+
# TSA (optional)
|
|
444
|
+
tsa: TimeStampingAuthority | None = None
|
|
445
|
+
if "trov:wasTimestampedBy" in graph:
|
|
446
|
+
tsa = TimeStampingAuthority.from_jsonld(graph["trov:wasTimestampedBy"])
|
|
447
|
+
|
|
448
|
+
# Composition
|
|
449
|
+
composition = ArtifactComposition.from_jsonld(
|
|
450
|
+
graph.get(
|
|
451
|
+
"trov:hasComposition", {"@id": "composition/1", "trov:hasArtifact": []}
|
|
452
|
+
)
|
|
453
|
+
)
|
|
454
|
+
|
|
455
|
+
# Arrangements
|
|
456
|
+
raw_arrangements = graph.get("trov:hasArrangement", [])
|
|
457
|
+
if isinstance(raw_arrangements, dict):
|
|
458
|
+
raw_arrangements = [raw_arrangements]
|
|
459
|
+
arrangements = [ArtifactArrangement.from_jsonld(a) for a in raw_arrangements]
|
|
460
|
+
|
|
461
|
+
# Performances
|
|
462
|
+
raw_performances = graph.get("trov:hasPerformance", [])
|
|
463
|
+
if isinstance(raw_performances, dict):
|
|
464
|
+
raw_performances = [raw_performances]
|
|
465
|
+
performances = [
|
|
466
|
+
TrustedResearchPerformance.from_jsonld(p) for p in raw_performances
|
|
467
|
+
]
|
|
468
|
+
|
|
469
|
+
# TRO-level attributes
|
|
470
|
+
raw_attributes = graph.get("trov:hasAttribute", [])
|
|
471
|
+
if isinstance(raw_attributes, dict):
|
|
472
|
+
raw_attributes = [raw_attributes]
|
|
473
|
+
attributes = [TROAttribute.from_jsonld(a) for a in raw_attributes]
|
|
474
|
+
|
|
475
|
+
# created_with (optional)
|
|
476
|
+
created_with = graph.get("trov:createdWith", {})
|
|
477
|
+
|
|
478
|
+
# date_created
|
|
479
|
+
date_created_raw = graph.get("schema:dateCreated")
|
|
480
|
+
if date_created_raw:
|
|
481
|
+
try:
|
|
482
|
+
# Timestamps without an offset are assumed to be local time.
|
|
483
|
+
date_created = ensure_aware(
|
|
484
|
+
datetime.datetime.fromisoformat(date_created_raw)
|
|
485
|
+
)
|
|
486
|
+
except ValueError:
|
|
487
|
+
date_created = aware_now()
|
|
488
|
+
else:
|
|
489
|
+
date_created = aware_now()
|
|
490
|
+
|
|
491
|
+
return cls(
|
|
492
|
+
tro_id=graph.get("@id", "tro"),
|
|
493
|
+
name=graph.get("schema:name", ""),
|
|
494
|
+
description=graph.get("schema:description", ""),
|
|
495
|
+
creator=_parse_creator(graph.get("schema:creator")),
|
|
496
|
+
date_created=date_created,
|
|
497
|
+
vocabulary_version=graph.get(
|
|
498
|
+
"trov:vocabularyVersion", str(TROV_VOCABULARY_VERSION)
|
|
499
|
+
),
|
|
500
|
+
trs=trs,
|
|
501
|
+
tsa=tsa,
|
|
502
|
+
created_with_name=created_with.get("schema:name"),
|
|
503
|
+
created_with_version=created_with.get("schema:softwareVersion"),
|
|
504
|
+
composition=composition,
|
|
505
|
+
arrangements=arrangements,
|
|
506
|
+
performances=performances,
|
|
507
|
+
attributes=attributes,
|
|
508
|
+
extra_context=extra_context,
|
|
509
|
+
)
|