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/default.jinja2
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# <img src="data:image/png;base64,{{ tro['logo'] }}" width=40/> TRO Report
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
## TRO Information
|
|
5
|
+
| Property | Value |
|
|
6
|
+
| -------- | ----- |
|
|
7
|
+
| Name | {{ tro["schema:name"] }} |
|
|
8
|
+
| Description | {{ tro["schema:description"] }} |
|
|
9
|
+
| Created by | {{ tro["schema:creator"]["schema:name"] }} |
|
|
10
|
+
| Created date | {{ tro["schema:dateCreated"] }} |
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
## TRACE System Information
|
|
14
|
+
|
|
15
|
+
This TRO was generated by the following TRACE System:
|
|
16
|
+
|
|
17
|
+
{%- set trs = tro["trov:wasAssembledBy"] %}
|
|
18
|
+
{#- The TRS is a schema:Organization, so it is described with schema:
|
|
19
|
+
properties. The trov: fallbacks read declarations written before that,
|
|
20
|
+
whose profiles used trov:name and friends -- keys the TROV vocabulary
|
|
21
|
+
never defined. #}
|
|
22
|
+
{%- set owner = trs.get("schema:owner", trs.get("trov:owner", "")) %}
|
|
23
|
+
|
|
24
|
+
| Property | Value |
|
|
25
|
+
| -------- | ----- |
|
|
26
|
+
| Name | {{ trs.get("schema:name", trs.get("trov:name", "")) }} |
|
|
27
|
+
| Description | {{ trs.get("schema:description", trs.get("trov:description", "")) }} |
|
|
28
|
+
| Owner | {{ owner.get("schema:name", "") if owner is mapping else owner }} |
|
|
29
|
+
| Contact | {{ trs.get("schema:email", trs.get("trov:contact", "")) }} |
|
|
30
|
+
| URL | {{ trs.get("schema:url", trs.get("trov:url", "")) }} |
|
|
31
|
+
|
|
32
|
+
<details>
|
|
33
|
+
<summary>Show Public Key</summary>
|
|
34
|
+
{{ trs.get("trov:publicKey", "") }}
|
|
35
|
+
</details>
|
|
36
|
+
|
|
37
|
+
### Capabilities
|
|
38
|
+
|
|
39
|
+
| Capability | Identifier |
|
|
40
|
+
| ----------- | ----------- |
|
|
41
|
+
{%- for capability in trs.get("trov:hasCapability", []) %}
|
|
42
|
+
| {{ capability.get("@type", "") }} | {{ capability.get("@id", "") }} |
|
|
43
|
+
{%- endfor %}
|
|
44
|
+
|
|
45
|
+
## Trusted Research Performances
|
|
46
|
+
|
|
47
|
+
A Trusted Research Performance (TRP) captures the execution of a process in the context of a TRACE system. Typically, a TRP would take as input one or more sets of files (input arrangements) and produce another set of files (output arrangements).
|
|
48
|
+
|
|
49
|
+
<img src="data:image/png;charset=utf-8;base64,{{ tro['workflow_diagram'] }}" width=600>
|
|
50
|
+
|
|
51
|
+
| Description | Accessed | Contributed |
|
|
52
|
+
| ----------- | ------------ | ------------ |
|
|
53
|
+
{%- for trp in tro["trps"] %}
|
|
54
|
+
| {{ trp["description"] }} | {{ trp["accessed"] }} | {{ trp["contributed"] }} |
|
|
55
|
+
{%- endfor %}
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
## Arrangements
|
|
59
|
+
|
|
60
|
+
Arrangements define how artifacts, typically files, are organized before and after each TRP. Artifacts are defined by their location and a checksum of their contents. Artifacts may be local or remote, defined by an URI. They may be included or excluded from the associated archive.
|
|
61
|
+
|
|
62
|
+
{%- for arrangement in tro["arrangements"].keys() %}
|
|
63
|
+
|
|
64
|
+
### {{ tro["arrangements"][arrangement]["name"] }}
|
|
65
|
+
{%- set artifacts = tro["arrangements"][arrangement]["artifacts"] %}
|
|
66
|
+
{%- set n_paths = artifacts | length %}
|
|
67
|
+
{%- set n_hashes = artifacts.values() | map(attribute="hash") | unique | list | length %}
|
|
68
|
+
|
|
69
|
+
{{ n_paths }} distinct path{{ "s" if n_paths != 1 }}, {{ n_hashes }} distinct hash{{ "es" if n_hashes != 1 }}
|
|
70
|
+
|
|
71
|
+
<details>
|
|
72
|
+
<summary>Show artifacts</summary>
|
|
73
|
+
|
|
74
|
+
| Artifact | Hash | Status |
|
|
75
|
+
| -------- | ---- | ------ |
|
|
76
|
+
{%- for location in tro["arrangements"][arrangement]["artifacts"] %}
|
|
77
|
+
{%- if tro["arrangements"][arrangement]["artifacts"][location].get("excluded") %}
|
|
78
|
+
| ~~`{{ location }}`~~ | {{ tro["arrangements"][arrangement]["artifacts"][location]["hash"] | truncate(32) }} | Excluded due to {{ tro["arrangements"][arrangement]["artifacts"][location]["excluded"] }} |
|
|
79
|
+
{%- else %}
|
|
80
|
+
| `{{ location }}` | {{ tro["arrangements"][arrangement]["artifacts"][location]["hash"] | truncate(32) }} | {{ tro["arrangements"][arrangement]["artifacts"][location]["status"] }} |
|
|
81
|
+
|
|
82
|
+
{%- endif %}
|
|
83
|
+
{%- endfor %}
|
|
84
|
+
|
|
85
|
+
</details>
|
|
86
|
+
{%- endfor %}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""OOP data models for Transparent Research Objects (TRO)."""
|
|
2
|
+
|
|
3
|
+
from .hash_value import HashValue
|
|
4
|
+
from .agent import Agent, ORGANIZATION, PERSON
|
|
5
|
+
from .artifact import ResearchArtifact
|
|
6
|
+
from .composition import ArtifactComposition, CompositionFingerprint
|
|
7
|
+
from .arrangement import ArtifactArrangement, ArtifactLocation
|
|
8
|
+
from .trs import TrustedResearchSystem, TRSCapability
|
|
9
|
+
from .tsa import TimeStampingAuthority
|
|
10
|
+
from .attribute import TROAttribute
|
|
11
|
+
from .performance import (
|
|
12
|
+
TrustedResearchPerformance,
|
|
13
|
+
PerformanceAttribute,
|
|
14
|
+
ArrangementBinding,
|
|
15
|
+
)
|
|
16
|
+
from .tro import TransparentResearchObject
|
|
17
|
+
|
|
18
|
+
__all__ = [
|
|
19
|
+
"HashValue",
|
|
20
|
+
"Agent",
|
|
21
|
+
"ORGANIZATION",
|
|
22
|
+
"PERSON",
|
|
23
|
+
"ResearchArtifact",
|
|
24
|
+
"ArtifactComposition",
|
|
25
|
+
"CompositionFingerprint",
|
|
26
|
+
"ArtifactArrangement",
|
|
27
|
+
"ArtifactLocation",
|
|
28
|
+
"TrustedResearchSystem",
|
|
29
|
+
"TRSCapability",
|
|
30
|
+
"TimeStampingAuthority",
|
|
31
|
+
"TROAttribute",
|
|
32
|
+
"TrustedResearchPerformance",
|
|
33
|
+
"PerformanceAttribute",
|
|
34
|
+
"ArrangementBinding",
|
|
35
|
+
"TransparentResearchObject",
|
|
36
|
+
]
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""Abstract base class for all TRO data model objects."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import datetime
|
|
6
|
+
import re
|
|
7
|
+
from abc import ABC, abstractmethod
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def ensure_aware(value: datetime.datetime | None) -> datetime.datetime | None:
|
|
12
|
+
"""Return *value* as a timezone-aware datetime.
|
|
13
|
+
|
|
14
|
+
Every timestamp recorded in a TRO must be unambiguous, so naive datetimes
|
|
15
|
+
are assumed to denote local wall-clock time and get the system's current
|
|
16
|
+
UTC offset attached. Values that already carry a ``tzinfo`` (and ``None``)
|
|
17
|
+
pass through untouched.
|
|
18
|
+
|
|
19
|
+
Args:
|
|
20
|
+
value: A datetime to normalise, or ``None``.
|
|
21
|
+
|
|
22
|
+
Returns:
|
|
23
|
+
A timezone-aware datetime for the same instant, or ``None``.
|
|
24
|
+
"""
|
|
25
|
+
if value is None or value.tzinfo is not None:
|
|
26
|
+
return value
|
|
27
|
+
return value.astimezone()
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def aware_now() -> datetime.datetime:
|
|
31
|
+
"""Return the current local time as a timezone-aware datetime."""
|
|
32
|
+
return datetime.datetime.now().astimezone()
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def natural_id_key(value: str) -> tuple:
|
|
36
|
+
"""Sort key ordering embedded integers numerically rather than as text.
|
|
37
|
+
|
|
38
|
+
A plain string sort puts ``artifact/10`` before ``artifact/2``; this key
|
|
39
|
+
keeps the digit runs in numeric order. Each part is tagged with a type
|
|
40
|
+
rank so numeric and non-numeric parts never compare against each other.
|
|
41
|
+
|
|
42
|
+
Args:
|
|
43
|
+
value: An ``@id`` or similar string containing digit runs.
|
|
44
|
+
|
|
45
|
+
Returns:
|
|
46
|
+
A tuple suitable for use as a ``sorted()`` key.
|
|
47
|
+
"""
|
|
48
|
+
return tuple(
|
|
49
|
+
(0, int(part), "") if part.isdigit() else (1, 0, part)
|
|
50
|
+
for part in re.split(r"(\d+)", value)
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class TROVModel(ABC):
|
|
55
|
+
"""Abstract base for all TROV model objects.
|
|
56
|
+
|
|
57
|
+
Every concrete subclass must implement ``to_jsonld()`` and ``from_jsonld()``
|
|
58
|
+
to support full JSON-LD round-trip serialisation.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
@abstractmethod
|
|
62
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
63
|
+
"""Serialise this object to a JSON-LD compatible dict."""
|
|
64
|
+
|
|
65
|
+
@classmethod
|
|
66
|
+
@abstractmethod
|
|
67
|
+
def from_jsonld(cls, data: dict[str, Any]) -> "TROVModel":
|
|
68
|
+
"""Deserialise an instance from a JSON-LD compatible dict."""
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
"""Agent model — a typed ``schema:Person`` or ``schema:Organization``.
|
|
2
|
+
|
|
3
|
+
``schema:creator`` expects an agent, not a bare name, so every creator is
|
|
4
|
+
represented by an :class:`Agent` that serialises to a proper node.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
from ._base import TROVModel
|
|
13
|
+
|
|
14
|
+
PERSON = "schema:Person"
|
|
15
|
+
ORGANIZATION = "schema:Organization"
|
|
16
|
+
|
|
17
|
+
#: The only two types ``schema:creator`` may carry here.
|
|
18
|
+
AGENT_TYPES = (PERSON, ORGANIZATION)
|
|
19
|
+
|
|
20
|
+
# Accept unprefixed terms and the full IRI on input; everything is written
|
|
21
|
+
# back out in the prefixed form used throughout a declaration.
|
|
22
|
+
_TYPE_ALIASES = {
|
|
23
|
+
"person": PERSON,
|
|
24
|
+
"schema:person": PERSON,
|
|
25
|
+
"https://schema.org/person": PERSON,
|
|
26
|
+
"http://schema.org/person": PERSON,
|
|
27
|
+
"organization": ORGANIZATION,
|
|
28
|
+
"schema:organization": ORGANIZATION,
|
|
29
|
+
"https://schema.org/organization": ORGANIZATION,
|
|
30
|
+
"http://schema.org/organization": ORGANIZATION,
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
_KNOWN_AGENT_KEYS = {"@id", "@type", "schema:name"}
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def normalise_agent_type(value: str) -> str:
|
|
37
|
+
"""Return *value* as either ``schema:Person`` or ``schema:Organization``.
|
|
38
|
+
|
|
39
|
+
Args:
|
|
40
|
+
value: A type name, optionally unprefixed (``"person"``) or given as a
|
|
41
|
+
full schema.org IRI.
|
|
42
|
+
|
|
43
|
+
Returns:
|
|
44
|
+
The canonical prefixed type string.
|
|
45
|
+
|
|
46
|
+
Raises:
|
|
47
|
+
ValueError: If *value* is neither a person nor an organization.
|
|
48
|
+
"""
|
|
49
|
+
try:
|
|
50
|
+
return _TYPE_ALIASES[str(value).strip().lower()]
|
|
51
|
+
except KeyError:
|
|
52
|
+
raise ValueError(
|
|
53
|
+
f"schema:creator must be {PERSON} or {ORGANIZATION}, got {value!r}"
|
|
54
|
+
) from None
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass
|
|
58
|
+
class Agent(TROVModel):
|
|
59
|
+
"""A ``schema:Person`` or ``schema:Organization``.
|
|
60
|
+
|
|
61
|
+
Unknown fields (``schema:email``, ``schema:affiliation``, ...) are kept in
|
|
62
|
+
:attr:`extra_fields` and round-tripped verbatim.
|
|
63
|
+
"""
|
|
64
|
+
|
|
65
|
+
name: str = ""
|
|
66
|
+
agent_type: str = ORGANIZATION
|
|
67
|
+
agent_id: str | None = None
|
|
68
|
+
extra_fields: dict[str, Any] = field(default_factory=dict)
|
|
69
|
+
|
|
70
|
+
def __post_init__(self) -> None:
|
|
71
|
+
self.agent_type = normalise_agent_type(self.agent_type)
|
|
72
|
+
|
|
73
|
+
# ------------------------------------------------------------------
|
|
74
|
+
# Convenience constructors
|
|
75
|
+
# ------------------------------------------------------------------
|
|
76
|
+
|
|
77
|
+
@classmethod
|
|
78
|
+
def person(cls, name: str, agent_id: str | None = None, **extra: Any) -> "Agent":
|
|
79
|
+
"""Return a ``schema:Person`` named *name*."""
|
|
80
|
+
return cls(
|
|
81
|
+
name=name, agent_type=PERSON, agent_id=agent_id, extra_fields=dict(extra)
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
@classmethod
|
|
85
|
+
def organization(
|
|
86
|
+
cls, name: str, agent_id: str | None = None, **extra: Any
|
|
87
|
+
) -> "Agent":
|
|
88
|
+
"""Return a ``schema:Organization`` named *name*."""
|
|
89
|
+
return cls(
|
|
90
|
+
name=name,
|
|
91
|
+
agent_type=ORGANIZATION,
|
|
92
|
+
agent_id=agent_id,
|
|
93
|
+
extra_fields=dict(extra),
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
@classmethod
|
|
97
|
+
def coerce(cls, value: Any, default_type: str = ORGANIZATION) -> "Agent":
|
|
98
|
+
"""Return *value* as an :class:`Agent`.
|
|
99
|
+
|
|
100
|
+
Accepts an :class:`Agent` (returned unchanged), a JSON-LD dict, or a
|
|
101
|
+
bare name. A bare name carries no type information, so it becomes
|
|
102
|
+
*default_type*.
|
|
103
|
+
|
|
104
|
+
Args:
|
|
105
|
+
value: An ``Agent``, a JSON-LD agent dict, or a name string.
|
|
106
|
+
default_type: Type to assume for a bare name.
|
|
107
|
+
|
|
108
|
+
Returns:
|
|
109
|
+
An :class:`Agent`.
|
|
110
|
+
|
|
111
|
+
Raises:
|
|
112
|
+
ValueError: If *value* is not one of the accepted forms.
|
|
113
|
+
"""
|
|
114
|
+
if isinstance(value, cls):
|
|
115
|
+
return value
|
|
116
|
+
if isinstance(value, dict):
|
|
117
|
+
return cls.from_jsonld(value)
|
|
118
|
+
if isinstance(value, str):
|
|
119
|
+
return cls(name=value, agent_type=default_type)
|
|
120
|
+
raise ValueError(f"Cannot interpret {value!r} as a schema:creator")
|
|
121
|
+
|
|
122
|
+
# ------------------------------------------------------------------
|
|
123
|
+
# JSON-LD serialisation
|
|
124
|
+
# ------------------------------------------------------------------
|
|
125
|
+
|
|
126
|
+
def to_jsonld(self) -> dict[str, Any]:
|
|
127
|
+
result: dict[str, Any] = {}
|
|
128
|
+
if self.agent_id is not None:
|
|
129
|
+
result["@id"] = self.agent_id
|
|
130
|
+
result["@type"] = normalise_agent_type(self.agent_type)
|
|
131
|
+
# Extra fields first so the typed name wins on conflict.
|
|
132
|
+
result.update(self.extra_fields)
|
|
133
|
+
result["schema:name"] = self.name
|
|
134
|
+
return result
|
|
135
|
+
|
|
136
|
+
@classmethod
|
|
137
|
+
def from_jsonld(cls, data: dict[str, Any] | str) -> "Agent":
|
|
138
|
+
"""Deserialise an agent from JSON-LD.
|
|
139
|
+
|
|
140
|
+
Args:
|
|
141
|
+
data: An agent dict, or a bare name as written by versions that
|
|
142
|
+
stored ``schema:creator`` as a plain string.
|
|
143
|
+
|
|
144
|
+
Returns:
|
|
145
|
+
An :class:`Agent`.
|
|
146
|
+
|
|
147
|
+
Raises:
|
|
148
|
+
ValueError: If ``@type`` names neither a person nor an organization.
|
|
149
|
+
"""
|
|
150
|
+
if isinstance(data, str):
|
|
151
|
+
return cls.coerce(data)
|
|
152
|
+
|
|
153
|
+
raw_type = data.get("@type", ORGANIZATION)
|
|
154
|
+
# @type may be a list; use the first entry that names an agent.
|
|
155
|
+
if isinstance(raw_type, list):
|
|
156
|
+
for candidate in raw_type:
|
|
157
|
+
try:
|
|
158
|
+
agent_type = normalise_agent_type(candidate)
|
|
159
|
+
break
|
|
160
|
+
except ValueError:
|
|
161
|
+
continue
|
|
162
|
+
else:
|
|
163
|
+
raise ValueError(
|
|
164
|
+
f"schema:creator @type names no {PERSON} or {ORGANIZATION}: "
|
|
165
|
+
f"{raw_type!r}"
|
|
166
|
+
)
|
|
167
|
+
else:
|
|
168
|
+
agent_type = normalise_agent_type(raw_type)
|
|
169
|
+
|
|
170
|
+
extra = {k: v for k, v in data.items() if k not in _KNOWN_AGENT_KEYS}
|
|
171
|
+
return cls(
|
|
172
|
+
name=data.get("schema:name", ""),
|
|
173
|
+
agent_type=agent_type,
|
|
174
|
+
agent_id=data.get("@id"),
|
|
175
|
+
extra_fields=extra,
|
|
176
|
+
)
|