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.
@@ -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
+ )