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,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
+ )