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/trs.py
ADDED
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
"""TrustedResearchSystem and TRSCapability models."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from ._base import TROVModel
|
|
10
|
+
|
|
11
|
+
# Profile keys that are handled as typed fields on TrustedResearchSystem;
|
|
12
|
+
# all other keys are stored verbatim in ``extra_fields``.
|
|
13
|
+
_KNOWN_TRS_KEYS = {
|
|
14
|
+
"@id",
|
|
15
|
+
"@type",
|
|
16
|
+
"schema:name",
|
|
17
|
+
"schema:description",
|
|
18
|
+
"trov:publicKey",
|
|
19
|
+
"trov:hasCapability",
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
#: Used when a profile identifies the TRS neither by ``@id`` nor by a URL.
|
|
23
|
+
UNIDENTIFIED_TRS_ID = "https://w3id.org/trace/tro-utils#unidentified-trs"
|
|
24
|
+
|
|
25
|
+
# An absolute IRI and a compact IRI share this shape: a scheme/prefix per
|
|
26
|
+
# RFC 3986, a colon, then a non-empty remainder. What this rules out is a
|
|
27
|
+
# bare relative reference such as "trs" or "trs/capability/1", which resolves
|
|
28
|
+
# against whatever document happens to contain it.
|
|
29
|
+
_IRI_RE = re.compile(r"^(?P<prefix>[A-Za-z][A-Za-z0-9+.\-]*):(?P<rest>.+)$")
|
|
30
|
+
|
|
31
|
+
# The trov prefix names the vocabulary itself, so a TRS minted under it would
|
|
32
|
+
# not be the same TRS wherever it is defined.
|
|
33
|
+
_RESERVED_PREFIX = "trov"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def iri_prefix(value: Any) -> str | None:
|
|
37
|
+
"""Return the scheme/prefix of *value*, or ``None`` if it is not an IRI.
|
|
38
|
+
|
|
39
|
+
Args:
|
|
40
|
+
value: A candidate ``@id``.
|
|
41
|
+
|
|
42
|
+
Returns:
|
|
43
|
+
The part before the first colon, or ``None`` when *value* is a
|
|
44
|
+
relative reference, a blank node, or not a string at all.
|
|
45
|
+
"""
|
|
46
|
+
if not isinstance(value, str):
|
|
47
|
+
return None
|
|
48
|
+
match = _IRI_RE.match(value)
|
|
49
|
+
return match.group("prefix") if match else None
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def is_conforming_trs_id(value: Any) -> bool:
|
|
53
|
+
"""Return whether *value* may identify a TRS.
|
|
54
|
+
|
|
55
|
+
A TRS ``@id`` must be an absolute IRI, or a compact IRI whose prefix is
|
|
56
|
+
not ``trov``, so that the same TRS carries the same identifier in every
|
|
57
|
+
document that mentions it.
|
|
58
|
+
|
|
59
|
+
Args:
|
|
60
|
+
value: A candidate ``@id``.
|
|
61
|
+
|
|
62
|
+
Returns:
|
|
63
|
+
``True`` when *value* conforms.
|
|
64
|
+
"""
|
|
65
|
+
prefix = iri_prefix(value)
|
|
66
|
+
return prefix is not None and prefix != _RESERVED_PREFIX
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def is_conforming_capability_id(value: Any) -> bool:
|
|
70
|
+
"""Return whether *value* may identify a TRS capability.
|
|
71
|
+
|
|
72
|
+
A capability belongs to the TRS rather than to any one declaration, so it
|
|
73
|
+
has to be named the same way everywhere: an absolute IRI or a compact IRI.
|
|
74
|
+
Unlike a TRS ``@id``, the ``trov`` prefix is allowed here -- the usual
|
|
75
|
+
identifier for a capability *is* its vocabulary term, e.g.
|
|
76
|
+
``trov:CanRecordInternetAccess``.
|
|
77
|
+
|
|
78
|
+
Args:
|
|
79
|
+
value: A candidate ``@id``.
|
|
80
|
+
|
|
81
|
+
Returns:
|
|
82
|
+
``True`` when *value* conforms.
|
|
83
|
+
"""
|
|
84
|
+
return iri_prefix(value) is not None
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def validate_capability_id(value: Any, source: str = "capability @id") -> str:
|
|
88
|
+
"""Return *value* unchanged, or raise if it cannot identify a capability.
|
|
89
|
+
|
|
90
|
+
Args:
|
|
91
|
+
value: The candidate ``@id``.
|
|
92
|
+
source: Label for the error message.
|
|
93
|
+
|
|
94
|
+
Returns:
|
|
95
|
+
*value*.
|
|
96
|
+
|
|
97
|
+
Raises:
|
|
98
|
+
ValueError: If *value* does not conform. See
|
|
99
|
+
:func:`is_conforming_capability_id`.
|
|
100
|
+
"""
|
|
101
|
+
if is_conforming_capability_id(value):
|
|
102
|
+
return value
|
|
103
|
+
raise ValueError(
|
|
104
|
+
f"{source} must be an absolute IRI or a compact IRI -- usually the "
|
|
105
|
+
f"capability's own term, e.g. 'trov:CanRecordInternetAccess' -- so "
|
|
106
|
+
f"that trov:warrantedBy refers to the same capability wherever it is "
|
|
107
|
+
f"mentioned; got {value!r}. A relative id such as 'trs/capability/1' "
|
|
108
|
+
f"resolves against whichever document contains it. Omit @id to use "
|
|
109
|
+
f"the capability's @type."
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def validate_trs_id(value: Any, source: str = "TRS @id") -> str:
|
|
114
|
+
"""Return *value* unchanged, or raise if it cannot identify a TRS.
|
|
115
|
+
|
|
116
|
+
Args:
|
|
117
|
+
value: The candidate ``@id``.
|
|
118
|
+
source: Label for the error message.
|
|
119
|
+
|
|
120
|
+
Returns:
|
|
121
|
+
*value*.
|
|
122
|
+
|
|
123
|
+
Raises:
|
|
124
|
+
ValueError: If *value* does not conform. See :func:`is_conforming_trs_id`.
|
|
125
|
+
"""
|
|
126
|
+
if is_conforming_trs_id(value):
|
|
127
|
+
return value
|
|
128
|
+
raise ValueError(
|
|
129
|
+
f"{source} must be an absolute IRI (e.g. "
|
|
130
|
+
f"'https://example.org/trs') or a compact IRI whose prefix is not "
|
|
131
|
+
f"'{_RESERVED_PREFIX}' (e.g. 'ex:trs'), so that the TRS is the same "
|
|
132
|
+
f"wherever it is defined; got {value!r}"
|
|
133
|
+
)
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
@dataclass
|
|
137
|
+
class TRSCapability(TROVModel):
|
|
138
|
+
"""A single capability declared by a :class:`TrustedResearchSystem`.
|
|
139
|
+
|
|
140
|
+
The ``@id`` is what ``trov:warrantedBy`` points at from a performance
|
|
141
|
+
attribute, so it has to name the same capability in every declaration --
|
|
142
|
+
see :func:`is_conforming_capability_id`. A profile that states no ``@id``
|
|
143
|
+
gets the capability's own term, which is the usual identifier for it.
|
|
144
|
+
"""
|
|
145
|
+
|
|
146
|
+
capability_id: str
|
|
147
|
+
capability_type: str
|
|
148
|
+
|
|
149
|
+
# ------------------------------------------------------------------
|
|
150
|
+
# Convenience constructors
|
|
151
|
+
# ------------------------------------------------------------------
|
|
152
|
+
|
|
153
|
+
@classmethod
|
|
154
|
+
def from_profile_entry(cls, data: dict[str, Any]) -> "TRSCapability":
|
|
155
|
+
"""Build a capability from one ``trov:hasCapability`` profile entry.
|
|
156
|
+
|
|
157
|
+
Args:
|
|
158
|
+
data: Dict with ``@type`` and an optional ``@id``.
|
|
159
|
+
|
|
160
|
+
Returns:
|
|
161
|
+
:class:`TRSCapability` identified by its stated ``@id``, or by its
|
|
162
|
+
``@type`` when none is stated.
|
|
163
|
+
|
|
164
|
+
Raises:
|
|
165
|
+
ValueError: If a stated ``@id`` cannot identify a capability, or if
|
|
166
|
+
the entry has no usable ``@type``.
|
|
167
|
+
"""
|
|
168
|
+
capability_type = data["@type"]
|
|
169
|
+
if "@id" in data:
|
|
170
|
+
capability_id = validate_capability_id(
|
|
171
|
+
data["@id"], "TRS profile capability @id"
|
|
172
|
+
)
|
|
173
|
+
else:
|
|
174
|
+
capability_id = validate_capability_id(
|
|
175
|
+
capability_type, "TRS profile capability @type"
|
|
176
|
+
)
|
|
177
|
+
return cls(capability_id=capability_id, capability_type=capability_type)
|
|
178
|
+
|
|
179
|
+
# ------------------------------------------------------------------
|
|
180
|
+
# JSON-LD serialisation
|
|
181
|
+
# ------------------------------------------------------------------
|
|
182
|
+
|
|
183
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
184
|
+
return {
|
|
185
|
+
"@id": self.capability_id,
|
|
186
|
+
"@type": self.capability_type,
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
@classmethod
|
|
190
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "TRSCapability":
|
|
191
|
+
"""Deserialise from a declaration, permissively.
|
|
192
|
+
|
|
193
|
+
Declarations written before capabilities were named by a conforming
|
|
194
|
+
IRI carry a relative ``@id``; they have to stay loadable, so nothing
|
|
195
|
+
is validated here. :meth:`from_profile_entry` is the checked path.
|
|
196
|
+
"""
|
|
197
|
+
return cls(
|
|
198
|
+
capability_id=data["@id"],
|
|
199
|
+
capability_type=data["@type"],
|
|
200
|
+
)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
@dataclass
|
|
204
|
+
class TrustedResearchSystem(TROVModel):
|
|
205
|
+
"""A Trusted Research System (TRS) that assembled and/or ran a TRO.
|
|
206
|
+
|
|
207
|
+
The TRS is a ``schema:Organization``, so it is described with schema.org
|
|
208
|
+
properties: ``schema:name`` and ``schema:description`` are typed fields,
|
|
209
|
+
and the rest (``schema:url``, ``schema:email``, ``schema:owner``, plus any
|
|
210
|
+
vendor-specific keys) are stored in :attr:`extra_fields` and round-tripped
|
|
211
|
+
verbatim through ``to_jsonld()`` / ``from_jsonld()``.
|
|
212
|
+
"""
|
|
213
|
+
|
|
214
|
+
trs_id: str = UNIDENTIFIED_TRS_ID
|
|
215
|
+
name: str = ""
|
|
216
|
+
description: str = ""
|
|
217
|
+
public_key: str | None = None
|
|
218
|
+
capabilities: list[TRSCapability] = field(default_factory=list)
|
|
219
|
+
extra_fields: dict[str, Any] = field(default_factory=dict)
|
|
220
|
+
|
|
221
|
+
# ------------------------------------------------------------------
|
|
222
|
+
# Convenience constructors
|
|
223
|
+
# ------------------------------------------------------------------
|
|
224
|
+
|
|
225
|
+
@classmethod
|
|
226
|
+
def from_profile(
|
|
227
|
+
cls, profile: dict[str, Any], trs_id: str | None = None
|
|
228
|
+
) -> "TrustedResearchSystem":
|
|
229
|
+
"""Load a TRS from the profile dict used by the existing CLI.
|
|
230
|
+
|
|
231
|
+
The profile format mirrors what is stored under ``trov:wasAssembledBy``
|
|
232
|
+
in a JSON-LD document. All unrecognised keys are preserved in
|
|
233
|
+
:attr:`extra_fields`.
|
|
234
|
+
|
|
235
|
+
The identifier is taken from *trs_id*, else the profile's ``@id``, else
|
|
236
|
+
its ``schema:url``, else :data:`UNIDENTIFIED_TRS_ID`. Whichever is
|
|
237
|
+
used must conform -- see :func:`validate_trs_id`.
|
|
238
|
+
|
|
239
|
+
Args:
|
|
240
|
+
profile: Dict with optional keys ``@id``, ``schema:name``,
|
|
241
|
+
``schema:description``, ``trov:publicKey``,
|
|
242
|
+
``trov:hasCapability``, plus any vendor-specific fields.
|
|
243
|
+
trs_id: Overrides the ``@id`` carried by *profile*.
|
|
244
|
+
|
|
245
|
+
Returns:
|
|
246
|
+
:class:`TrustedResearchSystem` instance.
|
|
247
|
+
|
|
248
|
+
Raises:
|
|
249
|
+
ValueError: If the resolved identifier does not conform.
|
|
250
|
+
"""
|
|
251
|
+
capabilities = [
|
|
252
|
+
TRSCapability.from_profile_entry(cap)
|
|
253
|
+
for cap in profile.get("trov:hasCapability", [])
|
|
254
|
+
]
|
|
255
|
+
extra = {k: v for k, v in profile.items() if k not in _KNOWN_TRS_KEYS}
|
|
256
|
+
return cls(
|
|
257
|
+
trs_id=cls._resolve_profile_id(profile, trs_id),
|
|
258
|
+
name=profile.get("schema:name", ""),
|
|
259
|
+
description=profile.get("schema:description", ""),
|
|
260
|
+
public_key=profile.get("trov:publicKey"),
|
|
261
|
+
capabilities=capabilities,
|
|
262
|
+
extra_fields=extra,
|
|
263
|
+
)
|
|
264
|
+
|
|
265
|
+
@staticmethod
|
|
266
|
+
def _resolve_profile_id(profile: dict[str, Any], trs_id: str | None) -> str:
|
|
267
|
+
"""Pick the TRS ``@id`` for *profile* and check that it conforms.
|
|
268
|
+
|
|
269
|
+
An identifier the caller or profile states explicitly is validated
|
|
270
|
+
rather than quietly replaced, so a non-conforming one is reported
|
|
271
|
+
instead of being papered over by the fallback.
|
|
272
|
+
"""
|
|
273
|
+
if trs_id is not None:
|
|
274
|
+
return validate_trs_id(trs_id, "TRS @id")
|
|
275
|
+
if "@id" in profile:
|
|
276
|
+
return validate_trs_id(profile["@id"], "TRS profile @id")
|
|
277
|
+
# A TRS's URL already identifies it globally. trov:url is read only
|
|
278
|
+
# for profiles written before the TRS was described with schema.org
|
|
279
|
+
# properties; the TROV vocabulary never defined that term.
|
|
280
|
+
for key in ("schema:url", "trov:url"):
|
|
281
|
+
url = profile.get(key)
|
|
282
|
+
if url is not None and is_conforming_trs_id(url):
|
|
283
|
+
return url
|
|
284
|
+
return UNIDENTIFIED_TRS_ID
|
|
285
|
+
|
|
286
|
+
# ------------------------------------------------------------------
|
|
287
|
+
# JSON-LD serialisation
|
|
288
|
+
# ------------------------------------------------------------------
|
|
289
|
+
|
|
290
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
291
|
+
result: dict[str, Any] = {
|
|
292
|
+
"@id": self.trs_id,
|
|
293
|
+
"@type": ["trov:TrustedResearchSystem", "schema:Organization"],
|
|
294
|
+
"trov:hasCapability": [cap.to_jsonld() for cap in self.capabilities],
|
|
295
|
+
}
|
|
296
|
+
# Merge extra (vendor) fields first so typed fields can override
|
|
297
|
+
result.update(self.extra_fields)
|
|
298
|
+
if self.name:
|
|
299
|
+
result["schema:name"] = self.name
|
|
300
|
+
if self.description:
|
|
301
|
+
result["schema:description"] = self.description
|
|
302
|
+
if self.public_key is not None:
|
|
303
|
+
result["trov:publicKey"] = self.public_key
|
|
304
|
+
return result
|
|
305
|
+
|
|
306
|
+
@classmethod
|
|
307
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "TrustedResearchSystem":
|
|
308
|
+
"""Deserialise from a JSON-LD TRS dict (``trov:wasAssembledBy`` value).
|
|
309
|
+
|
|
310
|
+
Args:
|
|
311
|
+
data: Dict with ``@id``, optional ``schema:name``, etc.
|
|
312
|
+
|
|
313
|
+
Returns:
|
|
314
|
+
:class:`TrustedResearchSystem` instance.
|
|
315
|
+
"""
|
|
316
|
+
capabilities = [
|
|
317
|
+
TRSCapability.from_jsonld(cap) for cap in data.get("trov:hasCapability", [])
|
|
318
|
+
]
|
|
319
|
+
extra = {k: v for k, v in data.items() if k not in _KNOWN_TRS_KEYS}
|
|
320
|
+
return cls(
|
|
321
|
+
# Read as-is: declarations predating this rule carry a bare
|
|
322
|
+
# "trs", and they must stay loadable.
|
|
323
|
+
trs_id=data.get("@id", UNIDENTIFIED_TRS_ID),
|
|
324
|
+
name=data.get("schema:name", ""),
|
|
325
|
+
description=data.get("schema:description", ""),
|
|
326
|
+
public_key=data.get("trov:publicKey"),
|
|
327
|
+
capabilities=capabilities,
|
|
328
|
+
extra_fields=extra,
|
|
329
|
+
)
|
tro_utils/models/tsa.py
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""TimeStampingAuthority model."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from ._base import TROVModel
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@dataclass
|
|
12
|
+
class TimeStampingAuthority(TROVModel):
|
|
13
|
+
"""A Time Stamping Authority (TSA) that signed a TRO timestamp."""
|
|
14
|
+
|
|
15
|
+
tsa_id: str = "tsa"
|
|
16
|
+
public_key: str | None = None
|
|
17
|
+
|
|
18
|
+
# ------------------------------------------------------------------
|
|
19
|
+
# JSON-LD serialisation
|
|
20
|
+
# ------------------------------------------------------------------
|
|
21
|
+
|
|
22
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
23
|
+
result: dict[str, Any] = {
|
|
24
|
+
"@id": self.tsa_id,
|
|
25
|
+
"@type": "trov:TimeStampingAuthority",
|
|
26
|
+
}
|
|
27
|
+
if self.public_key is not None:
|
|
28
|
+
result["trov:publicKey"] = self.public_key
|
|
29
|
+
return result
|
|
30
|
+
|
|
31
|
+
@classmethod
|
|
32
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "TimeStampingAuthority":
|
|
33
|
+
"""Deserialise from a JSON-LD TSA dict (``trov:wasTimestampedBy`` value).
|
|
34
|
+
|
|
35
|
+
Args:
|
|
36
|
+
data: Dict with ``@id`` and optional ``trov:publicKey``.
|
|
37
|
+
|
|
38
|
+
Returns:
|
|
39
|
+
:class:`TimeStampingAuthority` instance.
|
|
40
|
+
"""
|
|
41
|
+
return cls(
|
|
42
|
+
tsa_id=data.get("@id", "tsa"),
|
|
43
|
+
public_key=data.get("trov:publicKey"),
|
|
44
|
+
)
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
"""ReplicationPackage — verifies a research package against a TRO arrangement.
|
|
2
|
+
|
|
3
|
+
Provides a standalone :class:`ReplicationPackage` class for verifying that a
|
|
4
|
+
directory or zip archive matches the file-hash mapping recorded in an
|
|
5
|
+
:class:`~tro_utils.models.arrangement.ArtifactArrangement`.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import hashlib
|
|
11
|
+
import os
|
|
12
|
+
import pathlib
|
|
13
|
+
import zipfile
|
|
14
|
+
from dataclasses import dataclass, field
|
|
15
|
+
from typing import Iterator
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass
|
|
19
|
+
class VerificationResult:
|
|
20
|
+
"""Result of a :meth:`ReplicationPackage.verify` call."""
|
|
21
|
+
|
|
22
|
+
files_missing_in_arrangement: list[str] = field(default_factory=list)
|
|
23
|
+
mismatched_hashes: list[tuple[str, str | None, str]] = field(default_factory=list)
|
|
24
|
+
files_missing_in_package: list[str] = field(default_factory=list)
|
|
25
|
+
|
|
26
|
+
@property
|
|
27
|
+
def is_valid(self) -> bool:
|
|
28
|
+
"""``True`` when all checks pass."""
|
|
29
|
+
return not (
|
|
30
|
+
self.files_missing_in_arrangement
|
|
31
|
+
or self.mismatched_hashes
|
|
32
|
+
or self.files_missing_in_package
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class ReplicationPackage:
|
|
37
|
+
"""Verify a research package (directory or zip) against an arrangement.
|
|
38
|
+
|
|
39
|
+
Example::
|
|
40
|
+
|
|
41
|
+
from tro_utils.models import TransparentResearchObject
|
|
42
|
+
from tro_utils.replication_package import ReplicationPackage
|
|
43
|
+
|
|
44
|
+
tro = TransparentResearchObject.load("my_tro.jsonld")
|
|
45
|
+
arrangement = tro.arrangements[1] # "after execution" snapshot
|
|
46
|
+
result = ReplicationPackage.verify(
|
|
47
|
+
arrangement, tro.composition, "path/to/package"
|
|
48
|
+
)
|
|
49
|
+
if result.is_valid:
|
|
50
|
+
print("Package matches arrangement.")
|
|
51
|
+
"""
|
|
52
|
+
|
|
53
|
+
# ------------------------------------------------------------------
|
|
54
|
+
# Public API
|
|
55
|
+
# ------------------------------------------------------------------
|
|
56
|
+
|
|
57
|
+
@classmethod
|
|
58
|
+
def verify(
|
|
59
|
+
cls,
|
|
60
|
+
arrangement,
|
|
61
|
+
composition,
|
|
62
|
+
package: str | pathlib.Path,
|
|
63
|
+
subpath: str | None = None,
|
|
64
|
+
) -> VerificationResult:
|
|
65
|
+
"""Verify *package* against *arrangement*.
|
|
66
|
+
|
|
67
|
+
Args:
|
|
68
|
+
arrangement: :class:`~tro_utils.models.arrangement.ArtifactArrangement`
|
|
69
|
+
to compare against.
|
|
70
|
+
composition: :class:`~tro_utils.models.composition.ArtifactComposition`
|
|
71
|
+
that owns the artifact hashes.
|
|
72
|
+
package: Path to a directory or ``.zip`` file to inspect.
|
|
73
|
+
subpath: If set, only package entries whose path starts with
|
|
74
|
+
*subpath* are considered (relative to *subpath* after stripping).
|
|
75
|
+
|
|
76
|
+
Returns:
|
|
77
|
+
A :class:`VerificationResult` describing any discrepancies.
|
|
78
|
+
"""
|
|
79
|
+
arrangement_map: dict[str, str] = arrangement.to_path_hash_map(composition)
|
|
80
|
+
result = VerificationResult()
|
|
81
|
+
|
|
82
|
+
for rel_filename, file_hash in cls._iterate_package_files(package, subpath):
|
|
83
|
+
if rel_filename not in arrangement_map:
|
|
84
|
+
result.files_missing_in_arrangement.append(rel_filename)
|
|
85
|
+
|
|
86
|
+
expected_hash = arrangement_map.pop(rel_filename, None)
|
|
87
|
+
if file_hash != expected_hash:
|
|
88
|
+
result.mismatched_hashes.append(
|
|
89
|
+
(rel_filename, expected_hash, file_hash)
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
# Files present in the arrangement but absent from the package
|
|
93
|
+
result.files_missing_in_package = sorted(arrangement_map.keys())
|
|
94
|
+
result.files_missing_in_arrangement.sort()
|
|
95
|
+
result.mismatched_hashes.sort()
|
|
96
|
+
return result
|
|
97
|
+
|
|
98
|
+
# ------------------------------------------------------------------
|
|
99
|
+
# Internal helpers
|
|
100
|
+
# ------------------------------------------------------------------
|
|
101
|
+
|
|
102
|
+
@staticmethod
|
|
103
|
+
def _iterate_package_files(
|
|
104
|
+
package: str | pathlib.Path,
|
|
105
|
+
subpath: str | None,
|
|
106
|
+
) -> Iterator[tuple[str, str]]:
|
|
107
|
+
"""Yield ``(relative_path, "sha256:<hex>")`` pairs from *package*.
|
|
108
|
+
|
|
109
|
+
Args:
|
|
110
|
+
package: Directory or zip archive path.
|
|
111
|
+
subpath: Optional path prefix to strip (directories inside zip).
|
|
112
|
+
|
|
113
|
+
Yields:
|
|
114
|
+
Tuples of ``(relative_filename, hash_string)``.
|
|
115
|
+
"""
|
|
116
|
+
package = pathlib.Path(package)
|
|
117
|
+
if package.is_dir():
|
|
118
|
+
yield from ReplicationPackage._iter_directory(package, subpath)
|
|
119
|
+
else:
|
|
120
|
+
yield from ReplicationPackage._iter_zip(package, subpath)
|
|
121
|
+
|
|
122
|
+
@staticmethod
|
|
123
|
+
def _iter_directory(
|
|
124
|
+
root: pathlib.Path,
|
|
125
|
+
subpath: str | None,
|
|
126
|
+
) -> Iterator[tuple[str, str]]:
|
|
127
|
+
# os.walk yields filesystem order, so sort to keep the reported
|
|
128
|
+
# discrepancy lists identical from one machine to the next.
|
|
129
|
+
discovered: list[pathlib.Path] = []
|
|
130
|
+
for dirpath, _dirs, files in os.walk(root):
|
|
131
|
+
for filename in files:
|
|
132
|
+
discovered.append(pathlib.Path(dirpath) / filename)
|
|
133
|
+
discovered.sort(key=lambda p: p.relative_to(root).as_posix())
|
|
134
|
+
|
|
135
|
+
for filepath in discovered:
|
|
136
|
+
original = filepath.relative_to(root).as_posix()
|
|
137
|
+
rel = ReplicationPackage._apply_subpath(original, subpath)
|
|
138
|
+
if rel is None:
|
|
139
|
+
continue
|
|
140
|
+
hash_str = ReplicationPackage._sha256_file(filepath)
|
|
141
|
+
yield rel, hash_str
|
|
142
|
+
|
|
143
|
+
@staticmethod
|
|
144
|
+
def _iter_zip(
|
|
145
|
+
zip_path: pathlib.Path,
|
|
146
|
+
subpath: str | None,
|
|
147
|
+
) -> Iterator[tuple[str, str]]:
|
|
148
|
+
with zipfile.ZipFile(zip_path, "r") as zf:
|
|
149
|
+
for fileinfo in zf.infolist():
|
|
150
|
+
rel = ReplicationPackage._apply_subpath(fileinfo.filename, subpath)
|
|
151
|
+
if rel is None:
|
|
152
|
+
continue
|
|
153
|
+
sha256 = hashlib.sha256()
|
|
154
|
+
with zf.open(fileinfo.filename) as f:
|
|
155
|
+
for chunk in iter(lambda: f.read(4096), b""):
|
|
156
|
+
sha256.update(chunk)
|
|
157
|
+
yield rel, f"sha256:{sha256.hexdigest()}"
|
|
158
|
+
|
|
159
|
+
@staticmethod
|
|
160
|
+
def _apply_subpath(original: str, subpath: str | None) -> str | None:
|
|
161
|
+
"""Strip *subpath* prefix from *original*, or return ``None`` to skip."""
|
|
162
|
+
if subpath is None:
|
|
163
|
+
return original
|
|
164
|
+
import pathlib as _pl
|
|
165
|
+
|
|
166
|
+
orig = _pl.PurePosixPath(original)
|
|
167
|
+
sub = _pl.PurePosixPath(subpath)
|
|
168
|
+
try:
|
|
169
|
+
return orig.relative_to(sub).as_posix()
|
|
170
|
+
except ValueError:
|
|
171
|
+
return None
|
|
172
|
+
|
|
173
|
+
@staticmethod
|
|
174
|
+
def _sha256_file(filepath: pathlib.Path) -> str:
|
|
175
|
+
sha256 = hashlib.sha256()
|
|
176
|
+
with open(filepath, "rb") as f:
|
|
177
|
+
for chunk in iter(lambda: f.read(4096), b""):
|
|
178
|
+
sha256.update(chunk)
|
|
179
|
+
return f"sha256:{sha256.hexdigest()}"
|
|
Binary file
|