sdata 1.5.0__py3-none-any.whl

sdata/semantic.py

@@ -0,0 +1,346 @@
+# -*- coding: utf-8 -*-
+"""JSON-LD-/Linked-Data-Serialisierung für sdata-Metadaten + Sidecar-Dateien.
+
+Wandelt eine :class:`sdata.metadata.Metadata` in ein selbstbeschreibendes
+JSON-LD-Dokument (und zurück) und schreibt/liest optionale Sidecar-Dateien
+``<sname>.meta.jsonld`` neben einem Datenblob.
+
+Modellierung (siehe Projektentscheidungen):
+
+* ``@id`` = DID des Objekts ``did:suuid:<sname>:sdata``.
+* ``@type`` = ``[sdata:<Klasse>, <BFO-IRI der Topologieklasse>]``.
+* Reservierte ``_sdata_*``-Felder -> schema.org/DCAT/PROV-Terme (name,
+  identifier, generatedAtTime, wasDerivedFrom, isPartOf, …).
+* **Hybrid** für User-Attribute: mit echter Einheit -> ``qudt:Quantity``-Knoten;
+  ohne Einheit aber mit ``ontology`` -> getypter Knoten; sonst einfaches
+  typisiertes Literal. ``ontology`` ist stets ein ``@type``/Klasse des Werts;
+  das Prädikat ist ``sdata:<name>``.
+
+Pure-Python; keine Pflicht-Dependency.
+"""
+import json
+import os
+
+import sdata.dtypes as dtypes
+from sdata import vocab, units
+
+try:  # optionales RDF-Backend ([rdf]=rdflib)
+    import rdflib as _rdflib
+except ImportError:  # pragma: no cover - abhängig vom Environment
+    _rdflib = None
+
+__all__ = [
+    "to_jsonld", "from_jsonld", "to_rdf", "to_turtle", "rdf_from_doc",
+    "column_node", "write_sidecar", "read_sidecar",
+    "to_verifiable_credential", "verify_credential", "SIDECAR_SUFFIX",
+]
+
+SIDECAR_SUFFIX = ".meta.jsonld"
+
+# reserviertes Feld -> JSON-LD-Term (für Top-Level-Mapping & Rück-Parsing)
+_RESERVED_TERMS = {
+    "_sdata_name": "name",
+    "_sdata_suuid": "identifier",
+    "_sdata_ctime": "generatedAtTime",
+    "_sdata_topology_class": "topologyClass",
+    "_sdata_version": "sdata:version",
+    "_sdata_unit_system": "sdata:unitSystem",
+}
+_TERMS_RESERVED = {v: k for k, v in _RESERVED_TERMS.items()}
+
+# XSD-CURIE -> dtype (eindeutige Rückabbildung; list/json kommen über JSON-Typ)
+_DTYPE_FROM_XSD = {
+    "xsd:string": "str", "xsd:integer": "int", "xsd:double": "float",
+    "xsd:boolean": "bool", "xsd:dateTime": "timestamp",
+    "xsd:base64Binary": "bytes", "xsd:anyURI": "uri",
+    "xsd:date": "date", "xsd:time": "time",
+    "xsd:duration": "duration", "xsd:decimal": "decimal",
+    "sdata:complex": "complex",
+}
+
+
+def _did(sname):
+    return "did:suuid:{}:sdata".format(sname)
+
+
+def _sname_from_did(ref):
+    """Extrahiere den sname aus ``did:suuid:<sname>:sdata`` (oder aus {'@id':…})."""
+    if isinstance(ref, dict):
+        ref = ref.get("@id", "")
+    parts = str(ref).split(":")
+    if len(parts) >= 4 and parts[0] == "did" and parts[1] == "suuid":
+        return parts[2]
+    return str(ref)
+
+
+def _class_local(class_spec):
+    """``"sdata.sclass.dataframe:DataFrame"`` -> ``"DataFrame"``."""
+    return str(class_spec).split(":")[-1].split(".")[-1]
+
+
+def _value_literal(attr):
+    """Typisiertes JSON-LD-Literal ``{"@value": …, "@type": xsd}`` für ein Attribut.
+
+    Ausnahme ``langstring``: rdf:langString wird über ``@language`` ausgedrückt
+    (nicht ``@type``).
+    """
+    if attr.dtype == "langstring" and isinstance(attr.value, dtypes.LangString):
+        node = {"@value": attr.value.text}
+        if attr.value.lang:
+            node["@language"] = attr.value.lang
+        return node
+    spec = dtypes.get(attr.dtype) or dtypes.get("str")
+    return {"@value": spec.to_json(attr.value), "@type": vocab.xsd_for_dtype(attr.dtype)}
+
+
+def _attr_node(attr):
+    """Hybrid-Repräsentation eines User-Attributs (Knoten oder Literal)."""
+    has_unit = attr.unit not in (None, "", "-")
+    types = []
+    if has_unit:
+        types.append("qudt:Quantity")
+    type_of = vocab.type_iri(attr.ontology)
+    if type_of:
+        types.append(type_of)
+    # ohne Einheit und ohne ontology -> einfaches Literal
+    if not types:
+        return _value_literal(attr)
+    node = {"@type": types if len(types) > 1 else types[0],
+            "name": attr.name,
+            "value": _value_literal(attr)}
+    if has_unit:
+        node.update(units.unit_node(attr.unit))
+    if attr.description:
+        node["description"] = attr.description
+    if attr.label:
+        node["label"] = attr.label
+    if attr.symbol:
+        node["quantitySymbol"] = attr.symbol
+    if attr.required:
+        node["required"] = bool(attr.required)
+    return node
+
+
+def column_node(attr):
+    """JSON-LD-Knoten (CSVW) für eine Tabellenspalte aus ``column_metadata``.
+
+    ``attr.name`` = Spaltenname, ``attr.value`` = pandas-dtype-Name (z.B.
+    ``float64``); optional ``unit``/``label``/``description`` und ``ontology``
+    (Klasse der Spaltenwerte, als ``rdfType``).
+    """
+    node = {"name": attr.name, "datatype": vocab.xsd_for_dtype(attr.value)}
+    if attr.unit not in (None, "", "-"):
+        node.update(units.unit_node(attr.unit))
+    rdf_type = vocab.type_iri(attr.ontology)
+    if rdf_type:
+        node["rdfType"] = rdf_type
+    if attr.label:
+        node["label"] = attr.label
+    if attr.symbol:
+        node["quantitySymbol"] = attr.symbol
+    if attr.description:
+        node["description"] = attr.description
+    return node
+
+
+def to_jsonld(metadata, context_mode="inline", columns=None):
+    """Serialisiere ``metadata`` als JSON-LD-Dokument (dict).
+
+    :param columns: optionale, **geordnete** Iterable von Spalten-``Attribute``s
+        (DataFrame, in df-Spaltenreihenfolge); wird als ``csvw:column``-Liste ergänzt.
+    """
+    doc = {"@context": vocab.build_context(mode=context_mode)}
+
+    sname = metadata.get("_sdata_sname")
+    if sname is not None and sname.value:
+        doc["@id"] = _did(sname.value)
+
+    types = []
+    cls = metadata.get("_sdata_class")
+    if cls is not None and cls.value:
+        types.append("sdata:" + _class_local(cls.value))
+    topo = metadata.get("_sdata_topology_class")
+    bfo = vocab.bfo_iri(topo.value) if topo is not None else None
+    if bfo:
+        types.append(bfo)
+    if types:
+        doc["@type"] = types if len(types) > 1 else types[0]
+
+    # bekannte reservierte Felder -> Terme
+    for key, term in _RESERVED_TERMS.items():
+        attr = metadata.get(key)
+        if attr is None or attr.value in (None, ""):
+            continue
+        doc[term] = attr.value
+    # Relationen als DID-Referenzen
+    parent = metadata.get("_sdata_parent_sname")
+    if parent is not None and parent.value:
+        doc["wasDerivedFrom"] = {"@id": _did(parent.value)}
+    project = metadata.get("_sdata_project_sname")
+    if project is not None and project.value:
+        doc["isPartOf"] = {"@id": _did(project.value)}
+
+    # User-Attribute -> sdata:<name>
+    for attr in metadata.user_attributes.values():
+        doc[vocab.predicate_for(attr.name)] = _attr_node(attr)
+
+    # tabellarische Spalten (DataFrame) als geordnete csvw:column-Liste
+    if columns:
+        doc["columns"] = [column_node(a) for a in columns]
+    return doc
+
+
+def _set_from_node(metadata, name, node):
+    """Rekonstruiere ein User-Attribut aus Knoten/Literal."""
+    unit = "-"
+    ontology = ""
+    lang = None
+    if isinstance(node, dict) and "@value" in node:
+        raw, xsd = node.get("@value"), node.get("@type")
+        lang = node.get("@language")
+    elif isinstance(node, dict):
+        literal = node.get("value", {})
+        raw = literal.get("@value") if isinstance(literal, dict) else literal
+        xsd = literal.get("@type") if isinstance(literal, dict) else None
+        unit = node.get("symbol", "-") or "-"
+        type_list = node.get("@type", [])
+        if isinstance(type_list, str):
+            type_list = [type_list]
+        ontology = next((t for t in type_list if t != "qudt:Quantity"), "")
+    else:
+        raw, xsd = node, None
+    # dtype bestimmen: JSON-Typ/@language haben Vorrang, sonst XSD-Rückabbildung
+    if isinstance(raw, list):
+        dtype = "floatlist" if xsd == "sdata:floatlist" else "list"
+    elif isinstance(raw, dict):
+        dtype = "json"
+    elif lang:
+        dtype = "langstring"
+        raw = "{}@{}".format(raw, lang)          # text@lang rekonstruieren
+    else:
+        dtype = _DTYPE_FROM_XSD.get(xsd, "str")
+    metadata.set_attr(name, raw, dtype=dtype, unit=unit, ontology=ontology)
+
+
+def from_jsonld(doc):
+    """Rekonstruiere eine :class:`Metadata` aus einem JSON-LD-Dokument (dict oder str)."""
+    from sdata.metadata import Metadata
+    if isinstance(doc, str):
+        doc = json.loads(doc)
+    m = Metadata()
+
+    if "@id" in doc:
+        m.set_attr("_sdata_sname", _sname_from_did(doc["@id"]))
+    type_list = doc.get("@type", [])
+    if isinstance(type_list, str):
+        type_list = [type_list]
+    for t in type_list:
+        if isinstance(t, str) and t.startswith("sdata:"):
+            m.set_attr("_sdata_class", t.split(":", 1)[1])
+    for term, key in _TERMS_RESERVED.items():
+        if term in doc:
+            m.set_attr(key, doc[term])
+    if "wasDerivedFrom" in doc:
+        m.set_attr("_sdata_parent_sname", _sname_from_did(doc["wasDerivedFrom"]))
+    if "isPartOf" in doc:
+        m.set_attr("_sdata_project_sname", _sname_from_did(doc["isPartOf"]))
+
+    reserved_terms = set(_TERMS_RESERVED) | {
+        "@context", "@id", "@type", "wasDerivedFrom", "isPartOf"}
+    for key, val in doc.items():
+        if key in reserved_terms:
+            continue
+        if key.startswith("sdata:"):
+            _set_from_node(m, key.split(":", 1)[1], val)
+    return m
+
+
+def to_rdf(metadata, fmt="turtle"):
+    """Serialisiere die Metadaten als RDF.
+
+    Mit installiertem ``rdflib`` (``[rdf]``) wird das JSON-LD nach ``fmt``
+    (turtle/nt/xml/…) serialisiert. Ohne rdflib wird das JSON-LD selbst
+    zurückgegeben – ``application/ld+json`` ist bereits gültiges RDF.
+    """
+    return rdf_from_doc(to_jsonld(metadata), fmt=fmt)
+
+
+def rdf_from_doc(doc, fmt="turtle"):
+    """Serialisiere ein bereits gebautes JSON-LD-Dokument als RDF (siehe :func:`to_rdf`)."""
+    data = json.dumps(doc, default=dtypes.json_default)
+    if _rdflib is not None:
+        graph = _rdflib.Graph()
+        graph.parse(data=data, format="json-ld")
+        return graph.serialize(format=fmt)
+    return json.dumps(doc, indent=2, default=dtypes.json_default)
+
+
+def to_turtle(metadata):
+    """Convenience: RDF im Turtle-Format (siehe :func:`to_rdf`)."""
+    return to_rdf(metadata, fmt="turtle")
+
+
+def to_verifiable_credential(metadata, issuer_did, issuer_priv_jwk,
+                             kid=None, extra_claims=None):
+    """Signiere die Metadaten als W3C Verifiable Credential (Compact-JWS, EdDSA).
+
+    Wickelt :func:`to_jsonld` als ``credentialSubject`` und signiert über den
+    pure-Python-EdDSA-Stack (:mod:`sdata.did.jose`) – keine externe Krypto.
+
+    :return: Compact-JWS-String (``header.payload.signature``)
+    """
+    from sdata.did import jose
+    subject = to_jsonld(metadata)
+    payload = {
+        "iss": issuer_did,
+        "vc": {
+            "@context": ["https://www.w3.org/2018/credentials/v1"],
+            "type": ["VerifiableCredential", "SdataMetadataCredential"],
+            "credentialSubject": subject,
+        },
+    }
+    if subject.get("@id"):
+        payload["sub"] = subject["@id"]
+    if extra_claims:
+        payload.update(extra_claims)
+    return jose.sign_compact(payload, issuer_priv_jwk,
+                             kid=kid or (issuer_did + "#key-1"), typ="vc+ld+jwt")
+
+
+def verify_credential(vc_jws, pub_jwk):
+    """Verifiziere ein VC (Compact-JWS) und gib das ``credentialSubject`` (JSON-LD) zurück.
+
+    :raises sdata.did.errors.VerificationError: bei ungültiger Signatur.
+    """
+    from sdata.did import jose
+    payload = jose.verify_compact(vc_jws, pub_jwk)
+    return payload["vc"]["credentialSubject"]
+
+
+def _sidecar_path(path, sname):
+    """Ziel-Dateipfad: Verzeichnis -> ``<dir>/<sname>.meta.jsonld``; sonst ``path``."""
+    if path is None or os.path.isdir(path):
+        directory = path or "."
+        return os.path.join(directory, "{}{}".format(sname, SIDECAR_SUFFIX))
+    return path
+
+
+def write_sidecar(metadata, path=None, indent=2):
+    """Schreibe ``<sname>.meta.jsonld`` (JSON-LD) neben einen Blob; gibt den Pfad zurück."""
+    sname_attr = metadata.get("_sdata_sname")
+    sname = sname_attr.value if sname_attr is not None and sname_attr.value else "metadata"
+    return write_sidecar_doc(to_jsonld(metadata), path, sname, indent=indent)
+
+
+def write_sidecar_doc(doc, path, sname, indent=2):
+    """Schreibe ein bereits gebautes JSON-LD-Dokument als ``<sname>.meta.jsonld``."""
+    target = _sidecar_path(path, sname)
+    with open(target, "w") as fh:
+        json.dump(doc, fh, indent=indent, default=dtypes.json_default)
+    return target
+
+
+def read_sidecar(path):
+    """Lade eine ``.meta.jsonld``-Sidecar-Datei und rekonstruiere die Metadata."""
+    with open(path, "r") as fh:
+        return from_jsonld(json.load(fh))

sdata/suuid.py

@@ -0,0 +1,136 @@
+"""sdata.suuid — Adapter auf das eigenständige ``suuid``-Package.
+
+Ab jetzt ist **``suuid``** (``pip install "suuid>=0.2.0"``) die Single Source of
+Truth für semantische, S3-sichere IDs der Form ``Class__safe_name__huuid``.
+Dieses Modul ist ein dünner Rückwärtskompatibilitäts-Adapter: es bildet die
+historisch in sdata genutzte SUUID-API auf das ``suuid``-Package ab.
+
+Mapping (sdata → suuid):
+  ``suuid_str`` / ``suuid_bytes``        → :attr:`suuid.SUUID.compact_token`
+  ``uuid`` / ``get_uuid()``              → :meth:`suuid.SUUID.as_uuid`
+  ``from_name(ns_name=…)``               → :meth:`suuid.SUUID.from_name` (``ns=…``)
+  ``from_suuid_sname(strict=False)``     → :meth:`suuid.SUUID.from_sname`
+  ``from_suuid_str`` / ``from_suuid_bytes`` → :meth:`suuid.SUUID.from_compact_token`
+  ``generate_safe_filename``             → :func:`suuid.safe_name`
+
+Damit gilt durchgängig die in ``suuid`` eingefrorene, 100% S3-sichere
+Normalisierung (kein führendes ``_``, kein ``@``, ``sname`` ∈ ``[A-Za-z0-9_]``).
+"""
+from __future__ import annotations
+
+import uuid as _uuid
+from typing import Optional
+
+from suuid import SUUID as _SUUID, OID_NAMESPACE, safe_name  # noqa: F401
+from suuid.core import clean_class_name
+
+__all__ = ["SUUID"]
+
+
+class SUUID(_SUUID):
+    """sdata-Adapter um :class:`suuid.SUUID` mit Kompatibilitäts-Aliassen.
+
+    Erbt Immutabilität, Wertgleichheit und die S3-sichere Normalisierung von
+    :class:`suuid.SUUID`; ergänzt nur die in sdata genutzten Alias-Namen.
+    """
+
+    #: Separator (Kompat-Konstante; identisch zu ``suuid`` ``SEP``).
+    SEP = "__"
+
+    # --- Property-Aliasse ------------------------------------------------
+    @property
+    def suuid_str(self) -> str:
+        """Kompakter Base64-Token (Alias auf :attr:`compact_token`)."""
+        return self.compact_token
+
+    @property
+    def suuid_bytes(self) -> bytes:
+        """:attr:`suuid_str` als UTF-8-Bytes."""
+        return self.compact_token.encode()
+
+    @property
+    def uuid(self) -> _uuid.UUID:
+        """Das :class:`uuid.UUID`-Objekt hinter ``huuid``."""
+        return self.as_uuid()
+
+    def get_uuid(self) -> _uuid.UUID:
+        """Wie :attr:`uuid`."""
+        return self.as_uuid()
+
+    def to_list(self) -> list:
+        """``[sname, suuid_str, class_name, name, huuid]`` (sdata-Kompat)."""
+        return [self.sname, self.suuid_str, self.class_name, self.name, self.huuid]
+
+    def to_dict(self) -> dict:
+        """Wie :meth:`suuid.SUUID.to_dict`, plus sdata-Alias ``suuid``."""
+        d = super().to_dict()
+        d["suuid"] = self.suuid_str
+        return d
+
+    # --- Konstruktoren mit sdata-Signaturen ------------------------------
+    @classmethod
+    def from_name(cls, class_name: str, name: str = "",
+                  ns_name: Optional[str] = None) -> "SUUID":
+        """Deterministische SUUID; ``ns_name`` (String) scoped die ID."""
+        ns = OID_NAMESPACE if not ns_name else ns_name
+        return super().from_name(class_name, name, ns=ns)
+
+    @classmethod
+    def from_suuid_sname(cls, s, strict: bool = False):
+        """Parse einen ``sname``; ``strict=False`` (Default) → ``None`` bei Fehler."""
+        return super().from_sname(s, strict=strict)
+
+    @classmethod
+    def from_suuid_str(cls, s: str) -> "SUUID":
+        """Aus :attr:`suuid_str`/compact-token rekonstruieren."""
+        return super().from_compact_token(s)
+
+    @classmethod
+    def from_suuid_bytes(cls, b) -> "SUUID":
+        """Aus :attr:`suuid_bytes` rekonstruieren."""
+        token = b.decode() if isinstance(b, (bytes, bytearray)) else b
+        return super().from_compact_token(token)
+
+    @classmethod
+    def from_file(cls, class_name: str, filepath, ns_name: Optional[str] = None) -> "SUUID":
+        """Content-adressierte SUUID aus Dateiinhalt (``name`` = Basename)."""
+        ns = OID_NAMESPACE if not ns_name else ns_name
+        return super().from_file(class_name, filepath, ns=ns)
+
+    @classmethod
+    def from_str(cls, class_name: str, s: str, ns_name: Optional[str] = None) -> "SUUID":
+        """Content-adressierte SUUID aus einem String."""
+        ns = OID_NAMESPACE if not ns_name else ns_name
+        return super().from_content(class_name, "", s.encode("utf-8"), ns=ns)
+
+    @classmethod
+    def from_uuid(cls, class_name: str, uuid_obj: _uuid.UUID) -> "SUUID":
+        """SUUID aus ``class_name`` und einem :class:`uuid.UUID` (ohne Name)."""
+        return cls(class_name=clean_class_name(class_name), name="", huuid=uuid_obj.hex)
+
+    @classmethod
+    def from_obj(cls, obj, class_name: Optional[str] = None):
+        """Koerziere ein Base-artiges Objekt, einen ``sname`` oder String zu SUUID."""
+        if obj is None:
+            return None
+        if hasattr(obj, "sname"):
+            return cls.from_suuid_sname(obj.sname, strict=False)
+        if isinstance(obj, str):
+            parsed = cls.from_suuid_sname(obj, strict=False)
+            return parsed if parsed is not None else cls.from_name(class_name or cls.__name__, obj)
+        return None
+
+    # --- Statics ---------------------------------------------------------
+    @staticmethod
+    def generate_safe_filename(name: str) -> str:
+        """100% S3-sichere Normalisierung (Alias auf :func:`suuid.safe_name`)."""
+        return safe_name(name)
+
+    @staticmethod
+    def is_valid_suuid_str(s: str) -> bool:
+        """``True``, wenn ``s`` ein gültiger :attr:`suuid_str` ist."""
+        try:
+            _SUUID.from_compact_token(s)
+            return True
+        except Exception:
+            return False