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/tro_utils.py ADDED
@@ -0,0 +1,740 @@
1
+ """Main module — TRO facade.
2
+
3
+ The :class:`TRO` class is a thin facade that delegates data-model operations
4
+ to :class:`~tro_utils.models.TransparentResearchObject` while keeping
5
+ signing, timestamping, and report-generation logic here.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import base64
11
+ import datetime
12
+ import hashlib
13
+ import importlib.resources
14
+ import json
15
+ import os
16
+ import pathlib
17
+ import subprocess
18
+ import tempfile
19
+ from dataclasses import dataclass, field
20
+
21
+ from jinja2 import Template
22
+ import graphviz
23
+
24
+ from . import __version__, tsa
25
+ from .models import TransparentResearchObject
26
+ from .models.agent import ORGANIZATION, Agent
27
+ from .models.trs import TrustedResearchSystem
28
+ from .trs_keys import TRSKeyList, normalize_fingerprint
29
+
30
+ #: TRACE logo shown in report headers, bundled so reports don't depend on a
31
+ #: remote URL. Reduced to a 16-color palette to keep reports small; the
32
+ #: full-color original is at
33
+ #: https://transparency-certified.github.io/img/logo/trace-logo.png
34
+ _LOGO = importlib.resources.files(__package__) / "static" / "trace-logo.png"
35
+
36
+ GPG_HOME = os.environ.get("GPG_HOME")
37
+
38
+ # A key gpg fetches by itself, from a key server or a URL in the signature,
39
+ # is found by the fingerprint the signer chose, so it vouches for nothing.
40
+ _VERIFY_OPTIONS = ["--no-auto-key-retrieve"]
41
+
42
+
43
+ def _kill_gpg_agent(gnupghome):
44
+ """Stop the gpg-agent serving *gnupghome*, which would outlive its removal."""
45
+ try:
46
+ subprocess.run(
47
+ ["gpgconf", "--homedir", gnupghome, "--kill", "all"],
48
+ check=False,
49
+ capture_output=True,
50
+ )
51
+ except FileNotFoundError:
52
+ pass
53
+
54
+
55
+ @dataclass
56
+ class SignatureVerification:
57
+ """Result of :meth:`TRO.verify_signature`."""
58
+
59
+ valid: bool
60
+ status: str
61
+ fingerprint: str | None
62
+ username: str | None = None
63
+ trust: str | None = None
64
+ #: Whether something other than the TRO vouches for the key: an expected
65
+ #: fingerprint it matched, a keyring file it was found in, or at least
66
+ #: marginal validity in the keyring. Mere presence in the keyring does not.
67
+ trusted: bool = False
68
+ used_embedded_key: bool = False
69
+ embedded_key_matches: bool | None = None
70
+ #: The keyring file the key was looked up in, if one was given.
71
+ keyring: str | None = None
72
+ #: Whether the key matched an expected fingerprint; ``None`` if none given.
73
+ fingerprint_matches: bool | None = None
74
+ #: The key's status in the key list, if one was given and lists it.
75
+ listed_status: str | None = None
76
+ #: Time of the TRO's trusted timestamp, when a key list needed it.
77
+ timestamp: datetime.datetime | None = None
78
+ #: Conditions that did not fail the verification but should be reported.
79
+ warnings: list[str] = field(default_factory=list)
80
+
81
+ @property
82
+ def key_missing(self) -> bool:
83
+ """``True`` when the signing key is not in the keyring used."""
84
+ return self.status == "no public key"
85
+
86
+
87
+ class TRO:
88
+ gpg_fingerprint = None
89
+ gpg_key_id = None
90
+ gpg_passphrase = None
91
+ basename = None
92
+ profile = None
93
+ _gpg_obj = None
94
+
95
+ def __init__(
96
+ self,
97
+ filepath=None,
98
+ gpg_fingerprint=None,
99
+ gpg_passphrase=None,
100
+ profile=None,
101
+ tro_creator=None,
102
+ tro_creator_type=None,
103
+ tro_name=None,
104
+ tro_description=None,
105
+ extra_context=None,
106
+ ):
107
+ if filepath is None:
108
+ self.basename = "some_tro"
109
+ self.dirname = "."
110
+ else:
111
+ filepath_obj = pathlib.Path(filepath)
112
+ self.basename = filepath_obj.stem
113
+ self.dirname = (
114
+ str(filepath_obj.parent)
115
+ if filepath_obj.parent != pathlib.Path(".")
116
+ else "."
117
+ )
118
+
119
+ if profile is not None and pathlib.Path(profile).exists():
120
+ print(f"Loading profile from {profile}")
121
+ self.profile = json.load(open(profile))
122
+ else:
123
+ self.profile = {
124
+ "schema:description": "Default TRS with no capabilities",
125
+ "trov:hasCapability": [],
126
+ "trov:publicKey": None,
127
+ }
128
+
129
+ if not pathlib.Path(self.tro_filename).exists():
130
+ trs = TrustedResearchSystem.from_profile(self.profile)
131
+ # A bare name carries no type, so honour tro_creator_type and fall
132
+ # back to an organization. None lets the model credit the TRS.
133
+ creator = None
134
+ if tro_creator:
135
+ creator = Agent(
136
+ name=tro_creator,
137
+ agent_type=tro_creator_type or ORGANIZATION,
138
+ )
139
+ self._model = TransparentResearchObject(
140
+ creator=creator,
141
+ name=tro_name or "Some TRO",
142
+ description=tro_description or "Some description",
143
+ trs=trs,
144
+ created_with_name="tro-utils",
145
+ created_with_version=__version__,
146
+ )
147
+ else:
148
+ self._model = TransparentResearchObject.load(self.tro_filename)
149
+
150
+ if extra_context:
151
+ self._model.extra_context.update(extra_context)
152
+
153
+ # GPG configuration is only recorded here; nothing touches the keyring
154
+ # until a signature is actually produced. See _gpg() and
155
+ # attach_public_key().
156
+ if gpg_fingerprint:
157
+ self.gpg_fingerprint = gpg_fingerprint
158
+ if gpg_passphrase:
159
+ self.gpg_passphrase = gpg_passphrase
160
+
161
+ # ------------------------------------------------------------------
162
+ # File path helpers
163
+ # ------------------------------------------------------------------
164
+
165
+ @property
166
+ def base_filename(self):
167
+ if not self.basename:
168
+ raise ValueError("basename is not set")
169
+ return str((pathlib.Path(self.dirname) / self.basename).resolve())
170
+
171
+ @property
172
+ def tro_filename(self):
173
+ return f"{self.base_filename}.jsonld"
174
+
175
+ @property
176
+ def sig_filename(self):
177
+ return f"{self.base_filename}.sig"
178
+
179
+ @property
180
+ def tsr_filename(self):
181
+ return f"{self.base_filename}.tsr"
182
+
183
+ # ------------------------------------------------------------------
184
+ # data property — computed from the underlying model
185
+ # ------------------------------------------------------------------
186
+
187
+ @property
188
+ def data(self) -> dict:
189
+ """Return the current JSON-LD representation of the TRO.
190
+
191
+ Computed on every access from the underlying
192
+ :class:`~tro_utils.models.TransparentResearchObject`.
193
+ """
194
+ return self._model.to_jsonld()
195
+
196
+ # ------------------------------------------------------------------
197
+ # Delegation helpers
198
+ # ------------------------------------------------------------------
199
+
200
+ def get_composition_seq(self):
201
+ return len(self._model.composition.artifacts)
202
+
203
+ def get_arrangement_seq(self):
204
+ return len(self._model.arrangements)
205
+
206
+ def list_arrangements(self):
207
+ return self.data["@graph"][0]["trov:hasArrangement"]
208
+
209
+ def list_performances(self):
210
+ """Return the performances as JSON-LD dicts, in insertion order.
211
+
212
+ Unlike the serialised declaration, ``trov:accessedArrangement`` and
213
+ ``trov:contributedToArrangement`` are always lists (possibly empty), so
214
+ callers need not special-case a single binding.
215
+ """
216
+ performances = []
217
+ for perf in self._model.performances:
218
+ data = perf.to_jsonld()
219
+ data["trov:accessedArrangement"] = [
220
+ b.to_jsonld() for b in perf.accessed_arrangements
221
+ ]
222
+ data["trov:contributedToArrangement"] = [
223
+ b.to_jsonld() for b in perf.contributed_to_arrangements
224
+ ]
225
+ performances.append(data)
226
+ return performances
227
+
228
+ def get_arrangement_path_hash_map(self, arrangement_id):
229
+ arrangement = next(
230
+ (a for a in self._model.arrangements if a.arrangement_id == arrangement_id),
231
+ None,
232
+ )
233
+ if arrangement is None:
234
+ available = [a.arrangement_id for a in self._model.arrangements]
235
+ raise ValueError(
236
+ f"Arrangement '{arrangement_id}' not found. "
237
+ f"Available arrangements: {available}"
238
+ )
239
+ return arrangement.to_path_hash_map(self._model.composition)
240
+
241
+ def add_arrangement(
242
+ self, directory, ignore_dirs=None, comment=None, resolve_symlinks=True
243
+ ):
244
+ self._model.add_arrangement(
245
+ directory=directory,
246
+ comment=comment,
247
+ ignore_dirs=ignore_dirs,
248
+ resolve_symlinks=resolve_symlinks,
249
+ )
250
+
251
+ def add_arrangement_from_snapshot(self, filepath, comment=None):
252
+ self._model.add_arrangement_from_snapshot(filepath=filepath, comment=comment)
253
+
254
+ def save(self):
255
+ self._model.save(self.tro_filename)
256
+
257
+ # ------------------------------------------------------------------
258
+ # Hashing utilities
259
+ # ------------------------------------------------------------------
260
+
261
+ @staticmethod
262
+ def sha256_for_file(filepath, resolve_symlinks=True):
263
+ from .models.arrangement import ArtifactArrangement
264
+
265
+ return ArtifactArrangement._sha256_for_file(filepath, resolve_symlinks)
266
+
267
+ # ------------------------------------------------------------------
268
+ # Signing and timestamping
269
+ # ------------------------------------------------------------------
270
+
271
+ def _gpg(self):
272
+ """Return the GPG interface, constructing it on first use.
273
+
274
+ Instantiating :class:`gnupg.GPG` spawns the ``gpg`` binary, so it is
275
+ deferred until a key is actually needed. Creating, mutating, saving,
276
+ reporting on and verifying a TRO therefore require neither the binary
277
+ nor a keyring.
278
+ """
279
+ if self._gpg_obj is None:
280
+ import gnupg
281
+
282
+ self._gpg_obj = gnupg.GPG(gnupghome=GPG_HOME, verbose=False)
283
+ return self._gpg_obj
284
+
285
+ def _resolve_key_id(self):
286
+ """Resolve the configured fingerprint against the local keyring."""
287
+ if self.gpg_fingerprint is None:
288
+ raise RuntimeError("GPG fingerprint was not provided")
289
+ if self.gpg_key_id is None:
290
+ try:
291
+ self.gpg_key_id = (
292
+ self._gpg().list_keys().key_map[self.gpg_fingerprint]["keyid"]
293
+ )
294
+ except KeyError:
295
+ raise RuntimeError(
296
+ f"GPG key {self.gpg_fingerprint} was not found in the keyring"
297
+ ) from None
298
+ return self.gpg_key_id
299
+
300
+ def attach_public_key(self):
301
+ """Record the public half of the signing key in the declaration.
302
+
303
+ Called by :meth:`request_timestamp` before the declaration is hashed or
304
+ signed, so that ``trov:publicKey`` is by construction the public half of
305
+ the key that produced the signature. A value supplied by a TRS profile
306
+ acts as a default until it is replaced here.
307
+ """
308
+ self._model.trs.public_key = self._gpg().export_keys(self._resolve_key_id())
309
+
310
+ def trs_signature(self):
311
+ if self.gpg_fingerprint is None:
312
+ raise RuntimeError("GPG fingerprint was not provided")
313
+ if self.gpg_passphrase is None:
314
+ raise RuntimeError("GPG passphrase was not provided")
315
+ signature = self._gpg().sign(
316
+ json.dumps(self.data, indent=2, sort_keys=True),
317
+ keyid=self._resolve_key_id(),
318
+ passphrase=self.gpg_passphrase,
319
+ detach=True,
320
+ )
321
+ # The timestamp covers the LF-terminated signature, as for save().
322
+ with open(self.sig_filename, "w", newline="\n") as fp:
323
+ fp.write(str(signature))
324
+ return signature
325
+
326
+ def request_timestamp(self):
327
+ """Request a timestamp from a remote TSA and store the result in a file.
328
+
329
+ The public key is attached and the declaration written out *before*
330
+ anything is hashed, so that the signature and the timestamp both cover
331
+ the declaration exactly as it ends up on disk. Injecting the key any
332
+ later — inside :meth:`trs_signature`, say — would make every TRO fail
333
+ its own :meth:`verify_timestamp`.
334
+ """
335
+ self.attach_public_key()
336
+ self.save()
337
+ ts_data = {
338
+ "tro_declaration": hashlib.sha512(
339
+ json.dumps(self.data, indent=2, sort_keys=True).encode("utf-8")
340
+ ).hexdigest(),
341
+ "trs_signature": hashlib.sha512(
342
+ str(self.trs_signature()).encode("utf-8")
343
+ ).hexdigest(),
344
+ }
345
+ tsr_payload = json.dumps(ts_data, indent=2, sort_keys=True).encode()
346
+ tsr = tsa.request_token(tsr_payload)
347
+ with open(self.tsr_filename, "wb") as fs:
348
+ fs.write(tsr)
349
+
350
+ def get_composition_info(self):
351
+ return self.data["@graph"][0]["trov:hasComposition"]
352
+
353
+ def created_with_mismatch(self):
354
+ """Explain why this TRO may not verify with the running tro-utils.
355
+
356
+ tro-utils makes no backward-compatibility guarantee, so a TRO is only
357
+ guaranteed to verify with the version recorded in ``trov:createdWith``.
358
+
359
+ Returns:
360
+ A human-readable message if the TRO was created by different
361
+ software or a different tro-utils version, otherwise ``None``.
362
+ """
363
+ name = self._model.created_with_name
364
+ version = self._model.created_with_version
365
+ if name == "tro-utils" and version == __version__:
366
+ return None
367
+ if not name and not version:
368
+ return (
369
+ "The TRO does not record which software created it "
370
+ "(no trov:createdWith); it may not verify with "
371
+ f"tro-utils {__version__}."
372
+ )
373
+ created = " ".join(filter(None, [name or "unknown software", version]))
374
+ msg = (
375
+ f"The TRO was created with {created}, but this is "
376
+ f"tro-utils {__version__}."
377
+ )
378
+ if name == "tro-utils" and version:
379
+ msg += f" Verify it with: pip install tro-utils=={version}"
380
+ return msg
381
+
382
+ def verify_timestamp(self, quiet=False):
383
+ """Verify that a run is valid and signed.
384
+
385
+ Args:
386
+ quiet: Don't pass on what openssl prints.
387
+ """
388
+
389
+ try:
390
+ with open(self.sig_filename, "rb") as fp:
391
+ trs_signature = fp.read()
392
+ except FileNotFoundError:
393
+ raise RuntimeError("Signature file does not exist")
394
+ # Hash the declaration as stored, as verify_signature() does: the
395
+ # re-serialized model need not match the bytes that were timestamped.
396
+ with open(self.tro_filename, "rb") as fp:
397
+ declaration = fp.read()
398
+
399
+ ts_data = {
400
+ "tro_declaration": hashlib.sha512(declaration).hexdigest(),
401
+ "trs_signature": hashlib.sha512(trs_signature).hexdigest(),
402
+ }
403
+ tsr_payload = json.dumps(ts_data, indent=2, sort_keys=True).encode()
404
+ try:
405
+ with open(self.tsr_filename, "rb") as fp:
406
+ response = fp.read()
407
+ except FileNotFoundError:
408
+ raise RuntimeError("Timestamp file does not exist")
409
+
410
+ try:
411
+ tsa.verify_token(tsr_payload, response, quiet=quiet)
412
+ except subprocess.CalledProcessError as err:
413
+ mismatch = self.created_with_mismatch()
414
+ if mismatch is None:
415
+ raise
416
+ raise RuntimeError(f"Timestamp verification failed. {mismatch}") from err
417
+
418
+ def timestamp_time(self):
419
+ """Return the time in the TRO's timestamp, without verifying it."""
420
+ with open(self.tsr_filename, "rb") as fp:
421
+ return tsa.token_time(fp.read())
422
+
423
+ def verify_signature(
424
+ self,
425
+ use_embedded_key=False,
426
+ gnupghome=None,
427
+ keyring=None,
428
+ fingerprints=None,
429
+ trs_keys=None,
430
+ ):
431
+ """Verify the TRS signature against the declaration as stored on disk.
432
+
433
+ The signing key is looked up in the verifier's keyring: tro-utils does
434
+ not decide how a TRS key comes to be trusted. The ``trov:publicKey``
435
+ embedded in the TRO is only attested by the TRO itself, so it is used
436
+ for verification only when explicitly requested.
437
+
438
+ Args:
439
+ use_embedded_key: Verify with a throwaway keyring holding only the
440
+ key embedded in the TRO instead of the verifier's keyring.
441
+ gnupghome: GnuPG home of the keyring to use; defaults to
442
+ ``GPG_HOME`` or GnuPG's own default.
443
+ keyring: A key file (armored or binary) to verify with instead,
444
+ through a throwaway keyring holding only the keys in it.
445
+ fingerprints: Fingerprints the signing key is expected to have,
446
+ e.g. as published by the TRS. A signature by any other key is
447
+ reported as invalid.
448
+ trs_keys: A key list (path or :class:`TRSKeyList`) saying which
449
+ keys the TRS signed with and when. The key is then judged by
450
+ the list at the time of the TRO's trusted timestamp, which is
451
+ verified too, instead of by its current OpenPGP state. Unless
452
+ ``gnupghome`` or ``keyring`` is given, the key embedded in
453
+ the TRO is used, since the list vouches for its fingerprint.
454
+
455
+ Returns:
456
+ A :class:`SignatureVerification`.
457
+ """
458
+ import gnupg
459
+
460
+ if use_embedded_key + bool(gnupghome) + bool(keyring) > 1:
461
+ raise ValueError(
462
+ "use_embedded_key, gnupghome and keyring are mutually exclusive"
463
+ )
464
+ expected = {normalize_fingerprint(fp) for fp in fingerprints or ()}
465
+ key_list = None
466
+ if trs_keys is not None:
467
+ key_list = (
468
+ trs_keys
469
+ if isinstance(trs_keys, TRSKeyList)
470
+ else TRSKeyList.load(trs_keys)
471
+ )
472
+ if not gnupghome and not keyring:
473
+ use_embedded_key = True
474
+ if not os.path.exists(self.sig_filename):
475
+ raise RuntimeError("Signature file does not exist")
476
+ with open(self.tro_filename, "rb") as fp:
477
+ declaration = fp.read()
478
+ public_key = self._model.trs.public_key
479
+
480
+ if use_embedded_key and not public_key:
481
+ raise RuntimeError("The TRO does not embed a public key")
482
+
483
+ throwaway = use_embedded_key or keyring is not None
484
+ with tempfile.TemporaryDirectory() as tmp_home:
485
+ try:
486
+ if throwaway:
487
+ gpg = gnupg.GPG(gnupghome=tmp_home, options=_VERIFY_OPTIONS)
488
+ imported = (
489
+ gpg.import_keys(public_key)
490
+ if use_embedded_key
491
+ else gpg.import_keys_file(keyring)
492
+ )
493
+ if keyring is not None and not imported.fingerprints:
494
+ raise RuntimeError(f"No public keys found in {keyring}")
495
+ else:
496
+ gpg = gnupg.GPG(
497
+ gnupghome=gnupghome or GPG_HOME, options=_VERIFY_OPTIONS
498
+ )
499
+
500
+ result = gpg.verify_data(self.sig_filename, declaration)
501
+ embedded = set()
502
+ if public_key:
503
+ for key in gpg.scan_keys_mem(public_key):
504
+ embedded.add(key["fingerprint"])
505
+ embedded.update(s[2] for s in key.get("subkeys", []) if s[2])
506
+ finally:
507
+ if throwaway:
508
+ _kill_gpg_agent(tmp_home)
509
+
510
+ fingerprint = (
511
+ getattr(result, "pubkey_fingerprint", None)
512
+ or result.fingerprint
513
+ or result.key_id
514
+ )
515
+ # gpg reports VALIDSIG after EXPKEYSIG/REVKEYSIG, which overwrites
516
+ # status with "signature valid"; key_status keeps the reason.
517
+ status = result.key_status or result.status or "signature error"
518
+ valid = bool(result.valid)
519
+ # Before GnuPG 2.2.7 a missing key is reported by key ID only, which is
520
+ # the tail of its fingerprint.
521
+ signer = {result.fingerprint, fingerprint} - {None}
522
+
523
+ warnings = []
524
+ listed = None
525
+ signed_at = None
526
+ # VALIDSIG, i.e. the signature is cryptographically correct, whatever
527
+ # gpg thinks of the key's expiry or revocation today.
528
+ if key_list is not None and result.status == "signature valid":
529
+ if os.path.exists(self.tsr_filename):
530
+ try:
531
+ self.verify_timestamp(quiet=True)
532
+ except subprocess.CalledProcessError as err:
533
+ raise RuntimeError(
534
+ "Timestamp verification failed, so the time of signing "
535
+ "is unknown"
536
+ ) from err
537
+ signed_at = self.timestamp_time()
538
+ trs_id = self._model.trs.trs_id
539
+ listed_keys = key_list.keys_for(trs_id)
540
+ listed = next(
541
+ (k for k in listed_keys or () if k.fingerprint in signer), None
542
+ )
543
+ if listed_keys is None:
544
+ valid = False
545
+ status = f"the key list has no TRS with @id {trs_id}"
546
+ elif listed is None:
547
+ valid = False
548
+ status = f"the signing key is not listed for {trs_id}"
549
+ else:
550
+ valid, message = listed.check(signed_at)
551
+ if not valid:
552
+ status = message
553
+ else:
554
+ status = "signature valid"
555
+ if message:
556
+ warnings.append(message)
557
+ if result.key_status:
558
+ warnings.append(
559
+ f"GnuPG reports: {result.key_status}; the key was "
560
+ "judged by the key list instead"
561
+ )
562
+ if result.trust_level == result.TRUST_NEVER:
563
+ valid = False
564
+ status = "signing key is marked as never trusted"
565
+ # The primary key or the subkey that made the signature may be named.
566
+ fingerprint_matches = bool(signer & expected) if expected else None
567
+ if valid and fingerprint_matches is False:
568
+ valid = False
569
+ status = "signing key does not have the expected fingerprint"
570
+ return SignatureVerification(
571
+ valid=valid,
572
+ status=status,
573
+ fingerprint=fingerprint,
574
+ username=result.username,
575
+ trust=result.trust_text if valid else None,
576
+ trusted=valid
577
+ and (
578
+ fingerprint_matches is True
579
+ or listed is not None
580
+ or keyring is not None
581
+ or (
582
+ not use_embedded_key
583
+ and result.trust_level is not None
584
+ and result.trust_level >= result.TRUST_MARGINAL
585
+ )
586
+ ),
587
+ used_embedded_key=use_embedded_key,
588
+ keyring=keyring,
589
+ fingerprint_matches=fingerprint_matches,
590
+ listed_status=listed.status if listed is not None else None,
591
+ timestamp=signed_at,
592
+ warnings=warnings,
593
+ embedded_key_matches=(
594
+ any(fp.endswith(s) for fp in embedded for s in signer)
595
+ if embedded
596
+ else None
597
+ ),
598
+ )
599
+
600
+ # ------------------------------------------------------------------
601
+ # Replication package verification
602
+ # ------------------------------------------------------------------
603
+
604
+ def verify_replication_package(self, arrangement_id, package, subpath=None):
605
+ from .replication_package import ReplicationPackage
606
+
607
+ arrangement = next(
608
+ (a for a in self._model.arrangements if a.arrangement_id == arrangement_id),
609
+ None,
610
+ )
611
+ if arrangement is None:
612
+ available = [a.arrangement_id for a in self._model.arrangements]
613
+ raise ValueError(
614
+ f"Arrangement '{arrangement_id}' not found. "
615
+ f"Available arrangements: {available}"
616
+ )
617
+ result = ReplicationPackage.verify(
618
+ arrangement, self._model.composition, package, subpath
619
+ )
620
+ return (
621
+ result.files_missing_in_arrangement,
622
+ result.mismatched_hashes,
623
+ result.files_missing_in_package,
624
+ result.is_valid,
625
+ )
626
+
627
+ # ------------------------------------------------------------------
628
+ # Performance recording
629
+ # ------------------------------------------------------------------
630
+
631
+ def add_performance(
632
+ self,
633
+ start_time,
634
+ end_time,
635
+ comment=None,
636
+ accessed_arrangement=None, # str | (str, str|None) | list[...] | None
637
+ modified_arrangement=None, # str | (str, str|None) | list[...] | None
638
+ attrs=None,
639
+ extra_attributes=None,
640
+ ):
641
+ self._model.add_performance(
642
+ start_time=start_time,
643
+ end_time=end_time,
644
+ comment=comment,
645
+ accessed_arrangement=accessed_arrangement,
646
+ modified_arrangement=modified_arrangement,
647
+ attrs=attrs,
648
+ extra_attributes=extra_attributes,
649
+ )
650
+
651
+ # ------------------------------------------------------------------
652
+ # Report generation
653
+ # ------------------------------------------------------------------
654
+
655
+ def generate_report(self, template, report):
656
+ graph = self.data["@graph"][0]
657
+ artifact_lookup = {a.artifact_id: a for a in self._model.composition.artifacts}
658
+ arrangements = {}
659
+ for arr in self._model.arrangements:
660
+ artifacts = {
661
+ loc.path: {
662
+ "hash": artifact_lookup[loc.artifact_id].hash.to_string(),
663
+ "creator": "trs",
664
+ "createdDate": "None",
665
+ }
666
+ for loc in sorted(arr.locations, key=lambda _: _.path)
667
+ }
668
+ arrangements[arr.arrangement_id] = {
669
+ "name": arr.comment,
670
+ "artifacts": artifacts,
671
+ }
672
+
673
+ dot = graphviz.Digraph("TRO")
674
+ dot.graph_attr["rankdir"] = "LR"
675
+ dot.attr("edge", color="black")
676
+ dot.graph_attr["dpi"] = "200"
677
+
678
+ dot.attr("node", shape="box", style="filled, rounded", fillcolor="#FFFFD1")
679
+ for arr_id in arrangements:
680
+ dot.node(arrangements[arr_id]["name"])
681
+
682
+ dot.attr("node", shape="box3d", style="filled, rounded", fillcolor="#D6FDD0")
683
+ for perf in self._model.performances:
684
+ dot.node(perf.comment)
685
+ for ref in perf.accessed_arrangements:
686
+ dot.edge(arrangements[ref.arrangement_id]["name"], perf.comment)
687
+ for ref in perf.contributed_to_arrangements:
688
+ dot.edge(perf.comment, arrangements[ref.arrangement_id]["name"])
689
+
690
+ png_bytes = dot.pipe(format="png")
691
+ png_base64 = base64.b64encode(png_bytes).decode("utf-8")
692
+
693
+ keys = list(arrangements.keys())
694
+
695
+ for n in reversed(range(1, len(keys))):
696
+ for location in arrangements[keys[n]]["artifacts"]:
697
+ if location in arrangements[keys[n - 1]]["artifacts"]:
698
+ if (
699
+ arrangements[keys[n]]["artifacts"][location]["hash"]
700
+ != arrangements[keys[n - 1]]["artifacts"][location]["hash"]
701
+ ):
702
+ arrangements[keys[n]]["artifacts"][location][
703
+ "status"
704
+ ] = "Changed"
705
+ else:
706
+ arrangements[keys[n]]["artifacts"][location][
707
+ "status"
708
+ ] = "Unchanged"
709
+ else:
710
+ arrangements[keys[n]]["artifacts"][location]["status"] = "Created"
711
+
712
+ data = {
713
+ **graph,
714
+ "workflow_diagram": png_base64,
715
+ "logo": base64.b64encode(_LOGO.read_bytes()).decode("utf-8"),
716
+ "trps": [
717
+ {
718
+ "id": perf.performance_id,
719
+ "started": perf.started_at.isoformat() if perf.started_at else None,
720
+ "ended": perf.ended_at.isoformat() if perf.ended_at else None,
721
+ "accessed": [
722
+ arrangements[ref.arrangement_id]["name"]
723
+ for ref in perf.accessed_arrangements
724
+ ],
725
+ "contributed": [
726
+ arrangements[ref.arrangement_id]["name"]
727
+ for ref in perf.contributed_to_arrangements
728
+ ],
729
+ "description": perf.comment,
730
+ }
731
+ for perf in self._model.performances
732
+ ],
733
+ "arrangements": arrangements,
734
+ }
735
+
736
+ with open(template) as file_:
737
+ template = Template(file_.read())
738
+
739
+ with open(report, "w") as fh:
740
+ fh.write(template.render(tro=data))