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