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,101 @@
|
|
|
1
|
+
"""HashValue value object.
|
|
2
|
+
|
|
3
|
+
Wraps an (algorithm, value) pair and handles the ``"sha256:abc..."``
|
|
4
|
+
string format used throughout the JSON-LD documents.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
from ._base import TROVModel
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class HashValue(TROVModel):
|
|
17
|
+
"""Immutable (algorithm, hex-value) pair."""
|
|
18
|
+
|
|
19
|
+
algorithm: str
|
|
20
|
+
value: str
|
|
21
|
+
|
|
22
|
+
# ------------------------------------------------------------------
|
|
23
|
+
# Convenience constructors
|
|
24
|
+
# ------------------------------------------------------------------
|
|
25
|
+
|
|
26
|
+
@classmethod
|
|
27
|
+
def from_string(cls, s: str) -> "HashValue":
|
|
28
|
+
"""Parse ``"<algorithm>:<hex>"`` string (e.g. ``"sha256:abc..."``).
|
|
29
|
+
|
|
30
|
+
Args:
|
|
31
|
+
s: Colon-separated algorithm + hex value string.
|
|
32
|
+
|
|
33
|
+
Returns:
|
|
34
|
+
HashValue instance.
|
|
35
|
+
|
|
36
|
+
Raises:
|
|
37
|
+
ValueError: If the string is not in the expected format.
|
|
38
|
+
"""
|
|
39
|
+
if ":" not in s:
|
|
40
|
+
raise ValueError(f"Expected '<algorithm>:<value>' format, got: {s!r}")
|
|
41
|
+
algorithm, value = s.split(":", 1)
|
|
42
|
+
return cls(algorithm=algorithm, value=value)
|
|
43
|
+
|
|
44
|
+
# ------------------------------------------------------------------
|
|
45
|
+
# String representation
|
|
46
|
+
# ------------------------------------------------------------------
|
|
47
|
+
|
|
48
|
+
def to_string(self) -> str:
|
|
49
|
+
"""Return ``"<algorithm>:<hex>"`` form."""
|
|
50
|
+
return f"{self.algorithm}:{self.value}"
|
|
51
|
+
|
|
52
|
+
def __str__(self) -> str: # noqa: D105
|
|
53
|
+
return self.to_string()
|
|
54
|
+
|
|
55
|
+
# ------------------------------------------------------------------
|
|
56
|
+
# JSON-LD serialisation
|
|
57
|
+
# ------------------------------------------------------------------
|
|
58
|
+
|
|
59
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
60
|
+
"""Serialise to ``{"trov:hashAlgorithm": ..., "trov:hashValue": ...}``."""
|
|
61
|
+
return {
|
|
62
|
+
"trov:hashAlgorithm": self.algorithm,
|
|
63
|
+
"trov:hashValue": self.value,
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
@classmethod
|
|
67
|
+
def from_jsonld(cls, data: dict[str, Any] | list | str) -> "HashValue":
|
|
68
|
+
"""Deserialise from several supported JSON-LD hash shapes.
|
|
69
|
+
|
|
70
|
+
Handles:
|
|
71
|
+
* ``{"trov:hashAlgorithm": str, "trov:hashValue": str}``
|
|
72
|
+
* ``[{"trov:hashAlgorithm": ..., "trov:hashValue": ...}, ...]`` — first sha256 wins
|
|
73
|
+
* ``{"trov:sha256": str}`` — legacy format
|
|
74
|
+
* ``"sha256:abc..."`` — plain string
|
|
75
|
+
|
|
76
|
+
Args:
|
|
77
|
+
data: JSON-LD hash representation.
|
|
78
|
+
|
|
79
|
+
Returns:
|
|
80
|
+
HashValue instance.
|
|
81
|
+
"""
|
|
82
|
+
if isinstance(data, str):
|
|
83
|
+
return cls.from_string(data)
|
|
84
|
+
|
|
85
|
+
if isinstance(data, list):
|
|
86
|
+
# Prefer sha256 if present in the list
|
|
87
|
+
for entry in data:
|
|
88
|
+
if entry.get("trov:hashAlgorithm") == "sha256":
|
|
89
|
+
return cls.from_jsonld(entry)
|
|
90
|
+
return cls.from_jsonld(data[0])
|
|
91
|
+
|
|
92
|
+
if "trov:hashAlgorithm" in data and "trov:hashValue" in data:
|
|
93
|
+
return cls(
|
|
94
|
+
algorithm=data["trov:hashAlgorithm"],
|
|
95
|
+
value=data["trov:hashValue"],
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
if "trov:sha256" in data:
|
|
99
|
+
return cls(algorithm="sha256", value=data["trov:sha256"])
|
|
100
|
+
|
|
101
|
+
raise ValueError(f"Unrecognised hash JSON-LD shape: {data!r}")
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
"""TrustedResearchPerformance and PerformanceAttribute models."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import datetime
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from ._base import TROVModel, ensure_aware
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
@dataclass
|
|
13
|
+
class ArrangementBinding(TROVModel):
|
|
14
|
+
"""Maps an arrangement to a specific mount path for a particular performance.
|
|
15
|
+
|
|
16
|
+
An intermediate RDF object (``trov:ArrangementBinding``) that associates an
|
|
17
|
+
:class:`~tro_utils.models.arrangement.ArtifactArrangement` with a mount path
|
|
18
|
+
scoped to one :class:`TrustedResearchPerformance`, avoiding the ambiguity that
|
|
19
|
+
arises when the same arrangement is mounted at different paths in different
|
|
20
|
+
performances.
|
|
21
|
+
|
|
22
|
+
Analogous to ``trov:ArtifactLocation`` for arrangements.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
binding_id: str
|
|
26
|
+
arrangement_id: str
|
|
27
|
+
path: str | None = None
|
|
28
|
+
|
|
29
|
+
# ------------------------------------------------------------------
|
|
30
|
+
# JSON-LD serialisation
|
|
31
|
+
# ------------------------------------------------------------------
|
|
32
|
+
|
|
33
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
34
|
+
result: dict[str, Any] = {
|
|
35
|
+
"@id": self.binding_id,
|
|
36
|
+
"@type": "trov:ArrangementBinding",
|
|
37
|
+
"trov:arrangement": {"@id": self.arrangement_id},
|
|
38
|
+
}
|
|
39
|
+
if self.path is not None:
|
|
40
|
+
result["trov:boundTo"] = self.path
|
|
41
|
+
return result
|
|
42
|
+
|
|
43
|
+
@classmethod
|
|
44
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "ArrangementBinding":
|
|
45
|
+
return cls(
|
|
46
|
+
binding_id=data["@id"],
|
|
47
|
+
arrangement_id=data["trov:arrangement"]["@id"],
|
|
48
|
+
path=data.get("trov:boundTo"),
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@dataclass
|
|
53
|
+
class PerformanceAttribute(TROVModel):
|
|
54
|
+
"""A single attribute of a :class:`TrustedResearchPerformance`.
|
|
55
|
+
|
|
56
|
+
Warranted by a :class:`~tro_utils.models.trs.TRSCapability`.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
attribute_id: str
|
|
60
|
+
attribute_type: str
|
|
61
|
+
warranted_by_id: str
|
|
62
|
+
|
|
63
|
+
# ------------------------------------------------------------------
|
|
64
|
+
# JSON-LD serialisation
|
|
65
|
+
# ------------------------------------------------------------------
|
|
66
|
+
|
|
67
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
68
|
+
return {
|
|
69
|
+
"@id": self.attribute_id,
|
|
70
|
+
"@type": self.attribute_type,
|
|
71
|
+
"trov:warrantedBy": {"@id": self.warranted_by_id},
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
@classmethod
|
|
75
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "PerformanceAttribute":
|
|
76
|
+
return cls(
|
|
77
|
+
attribute_id=data["@id"],
|
|
78
|
+
attribute_type=data["@type"],
|
|
79
|
+
warranted_by_id=data["trov:warrantedBy"]["@id"],
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
@dataclass
|
|
84
|
+
class TrustedResearchPerformance(TROVModel):
|
|
85
|
+
"""A record of a single execution run within a TRO."""
|
|
86
|
+
|
|
87
|
+
performance_id: str
|
|
88
|
+
comment: str = ""
|
|
89
|
+
conducted_by_id: str = "trs"
|
|
90
|
+
started_at: datetime.datetime | None = None
|
|
91
|
+
ended_at: datetime.datetime | None = None
|
|
92
|
+
accessed_arrangements: list[ArrangementBinding] = field(default_factory=list)
|
|
93
|
+
contributed_to_arrangements: list[ArrangementBinding] = field(default_factory=list)
|
|
94
|
+
attributes: list[PerformanceAttribute] = field(default_factory=list)
|
|
95
|
+
extra_attributes: dict[str, Any] = field(default_factory=dict)
|
|
96
|
+
|
|
97
|
+
def __post_init__(self) -> None:
|
|
98
|
+
# Performance timestamps must be unambiguous; naive values are read as
|
|
99
|
+
# local wall-clock time. See ``ensure_aware``.
|
|
100
|
+
self.started_at = ensure_aware(self.started_at)
|
|
101
|
+
self.ended_at = ensure_aware(self.ended_at)
|
|
102
|
+
|
|
103
|
+
# ------------------------------------------------------------------
|
|
104
|
+
# JSON-LD serialisation
|
|
105
|
+
# ------------------------------------------------------------------
|
|
106
|
+
|
|
107
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
108
|
+
result: dict[str, Any] = {
|
|
109
|
+
"@id": self.performance_id,
|
|
110
|
+
"@type": "trov:TrustedResearchPerformance",
|
|
111
|
+
"rdfs:comment": self.comment,
|
|
112
|
+
"trov:wasConductedBy": {"@id": self.conducted_by_id},
|
|
113
|
+
"trov:hasPerformanceAttribute": [
|
|
114
|
+
attr.to_jsonld() for attr in self.attributes
|
|
115
|
+
],
|
|
116
|
+
}
|
|
117
|
+
if self.started_at is not None:
|
|
118
|
+
result["trov:startedAtTime"] = ensure_aware(self.started_at).isoformat()
|
|
119
|
+
if self.ended_at is not None:
|
|
120
|
+
result["trov:endedAtTime"] = ensure_aware(self.ended_at).isoformat()
|
|
121
|
+
if len(self.accessed_arrangements) == 1:
|
|
122
|
+
result["trov:accessedArrangement"] = self.accessed_arrangements[
|
|
123
|
+
0
|
|
124
|
+
].to_jsonld()
|
|
125
|
+
elif len(self.accessed_arrangements) > 1:
|
|
126
|
+
result["trov:accessedArrangement"] = [
|
|
127
|
+
ref.to_jsonld() for ref in self.accessed_arrangements
|
|
128
|
+
]
|
|
129
|
+
if len(self.contributed_to_arrangements) == 1:
|
|
130
|
+
result["trov:contributedToArrangement"] = self.contributed_to_arrangements[
|
|
131
|
+
0
|
|
132
|
+
].to_jsonld()
|
|
133
|
+
elif len(self.contributed_to_arrangements) > 1:
|
|
134
|
+
result["trov:contributedToArrangement"] = [
|
|
135
|
+
ref.to_jsonld() for ref in self.contributed_to_arrangements
|
|
136
|
+
]
|
|
137
|
+
if self.extra_attributes:
|
|
138
|
+
result.update(self.extra_attributes)
|
|
139
|
+
return result
|
|
140
|
+
|
|
141
|
+
@classmethod
|
|
142
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "TrustedResearchPerformance":
|
|
143
|
+
"""Deserialise from a JSON-LD performance dict.
|
|
144
|
+
|
|
145
|
+
Args:
|
|
146
|
+
data: Dict with ``@id``, optional timing keys, arrangement refs, etc.
|
|
147
|
+
|
|
148
|
+
Returns:
|
|
149
|
+
:class:`TrustedResearchPerformance` instance.
|
|
150
|
+
"""
|
|
151
|
+
|
|
152
|
+
def _parse_dt(value: str | None) -> datetime.datetime | None:
|
|
153
|
+
"""Parse an ISO 8601 timestamp, assuming local time if no offset."""
|
|
154
|
+
if value is None:
|
|
155
|
+
return None
|
|
156
|
+
return ensure_aware(datetime.datetime.fromisoformat(value))
|
|
157
|
+
|
|
158
|
+
attributes = [
|
|
159
|
+
PerformanceAttribute.from_jsonld(attr)
|
|
160
|
+
for attr in data.get("trov:hasPerformanceAttribute", [])
|
|
161
|
+
]
|
|
162
|
+
|
|
163
|
+
def _parse_refs(value: Any) -> list[ArrangementBinding]:
|
|
164
|
+
if value is None:
|
|
165
|
+
return []
|
|
166
|
+
if isinstance(value, list):
|
|
167
|
+
return [ArrangementBinding.from_jsonld(item) for item in value]
|
|
168
|
+
return [ArrangementBinding.from_jsonld(value)]
|
|
169
|
+
|
|
170
|
+
known_keys = {
|
|
171
|
+
"@id",
|
|
172
|
+
"@type",
|
|
173
|
+
"rdfs:comment",
|
|
174
|
+
"trov:wasConductedBy",
|
|
175
|
+
"trov:hasPerformanceAttribute",
|
|
176
|
+
"trov:startedAtTime",
|
|
177
|
+
"trov:endedAtTime",
|
|
178
|
+
"trov:accessedArrangement",
|
|
179
|
+
"trov:contributedToArrangement",
|
|
180
|
+
}
|
|
181
|
+
extra = {k: v for k, v in data.items() if k not in known_keys}
|
|
182
|
+
|
|
183
|
+
return cls(
|
|
184
|
+
performance_id=data["@id"],
|
|
185
|
+
comment=data.get("rdfs:comment", ""),
|
|
186
|
+
conducted_by_id=data.get("trov:wasConductedBy", {}).get("@id", "trs"),
|
|
187
|
+
started_at=_parse_dt(data.get("trov:startedAtTime")),
|
|
188
|
+
ended_at=_parse_dt(data.get("trov:endedAtTime")),
|
|
189
|
+
accessed_arrangements=_parse_refs(data.get("trov:accessedArrangement")),
|
|
190
|
+
contributed_to_arrangements=_parse_refs(
|
|
191
|
+
data.get("trov:contributedToArrangement")
|
|
192
|
+
),
|
|
193
|
+
attributes=attributes,
|
|
194
|
+
extra_attributes=extra,
|
|
195
|
+
)
|