sdata 1.5.0__py3-none-any.whl

sdata/sclass/dataframegroup.py

@@ -0,0 +1,187 @@
+"""Geordnete Sammlung benannter sdata-DataFrames (RFC 0011).
+
+Anders als früher hält die Gruppe ihre Mitglieder als vollwertige
+:class:`~sdata.sclass.dataframe.DataFrame` (mit reichem ``Metadata``/
+``column_metadata`` — Einheit/Label/Ontologie/dtype, RFC 0006), nicht mehr als
+rohe pandas-Frames mit einem ``{label, unit}``-dict. Die öffentliche API
+(``add_dataframe``/``get_dataframe``/``get_column_metadata``/…) bleibt
+abwärtskompatibel; ``from_dict`` liest **beide** Serialisierungs-Layouts (das alte
+``{parquet, column_metadata}`` und das neue ``{sdata: <DataFrame.to_dict>}``).
+"""
+import base64
+import io
+import logging
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from sdata.base import Base
+
+logger = logging.getLogger(__name__)
+
+
+class DataFrameGroup(Base):
+    """Sammlung benannter :class:`~sdata.sclass.dataframe.DataFrame` (eine flache Ebene).
+
+    Die Mitglieder liegen in ``self.data['dataframes']`` als
+    :class:`~sdata.sclass.dataframe.DataFrame`-Objekte; jedes trägt seine volle
+    Spaltensemantik selbst (kein separates ``{label, unit}``-dict mehr).
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the group (forwards ``**kwargs`` to :class:`Base`)."""
+        super().__init__(**kwargs)
+        if 'dataframes' not in self.data:
+            self.data['dataframes'] = {}
+
+    # ------------------------------------------------------------------ helpers
+    @staticmethod
+    def _as_dataframe(df, key=None, column_metadata=None):
+        """Wrap a pandas ``df`` (or pass a :class:`DataFrame` through) and annotate columns."""
+        from sdata.sclass.dataframe import DataFrame
+        sdf = df if isinstance(df, DataFrame) else DataFrame(df=df, name=key or "df")
+        if column_metadata:
+            for col, meta in column_metadata.items():
+                sdf.set_column(col, label=meta.get('label'), unit=meta.get('unit'))
+        return sdf
+
+    # -------------------------------------------------------------- public API
+    def add(self, df, key: Optional[str] = None, overwrite: bool = False):
+        """Add a :class:`DataFrame` (or pandas ``df``); returns the stored member.
+
+        :param df: a :class:`~sdata.sclass.dataframe.DataFrame` or a pandas ``DataFrame``.
+        :param key: storage key (defaults to the member's ``sname``).
+        :param overwrite: allow replacing an existing key.
+        :raises ValueError: if the key exists and ``overwrite`` is False.
+        """
+        sdf = self._as_dataframe(df, key=key)
+        key = key or sdf.sname
+        if key in self.data['dataframes'] and not overwrite:
+            raise ValueError(f"DataFrame with key '{key}' already exists. "
+                             "Set overwrite=True to replace.")
+        self.data['dataframes'][key] = sdf
+        logger.debug("Added DataFrame '%s' to %s", key, self.sname)
+        return sdf
+
+    def add_dataframe(
+            self,
+            key: str,
+            df: pd.DataFrame,
+            column_metadata: Optional[Dict[str, Dict[str, str]]] = None,
+            overwrite: bool = False,
+    ) -> None:
+        """Add a pandas ``df`` under ``key`` (backward-compatible API).
+
+        :param column_metadata: optional ``{colname: {'label': ..., 'unit': ...}}``;
+          if given, must cover **exactly** the df columns and each entry must have
+          both ``label`` and ``unit``. The annotations are written through to the
+          member's per-column :class:`~sdata.metadata.Metadata`.
+        :raises ValueError: on key clash without ``overwrite`` or invalid metadata.
+        """
+        if key in self.data['dataframes'] and not overwrite:
+            raise ValueError(f"DataFrame with key '{key}' already exists. "
+                             "Set overwrite=True to replace.")
+        if column_metadata is not None:
+            if set(column_metadata.keys()) != set(df.columns):
+                raise ValueError("column_metadata keys must match the DataFrame's columns exactly.")
+            for meta in column_metadata.values():
+                if not all(k in meta for k in ['label', 'unit']):
+                    raise ValueError("Each column_metadata entry must have 'label' and 'unit' keys.")
+        sdf = self._as_dataframe(df, key=key, column_metadata=column_metadata)
+        self.data['dataframes'][key] = sdf
+        logger.debug("Added DataFrame '%s' to %s", key, self.sname)
+
+    def get(self, key: str):
+        """Return the stored :class:`DataFrame` member (or ``None``)."""
+        return self.data['dataframes'].get(key)
+
+    def get_dataframe(self, key: str) -> Optional[pd.DataFrame]:
+        """Return the member's pandas ``DataFrame`` (backward-compatible), or ``None``."""
+        member = self.data['dataframes'].get(key)
+        return member.df if member is not None else None
+
+    def get_column_metadata(self, key: str) -> Optional[Dict[str, Dict[str, str]]]:
+        """Return ``{colname: {'label': str, 'unit': str}}`` for a member (backward-compatible).
+
+        Derived from the member's per-column :class:`~sdata.metadata.Metadata`.
+        """
+        member = self.data['dataframes'].get(key)
+        if member is None:
+            return None
+        out: Dict[str, Dict[str, str]] = {}
+        for col in member.df.columns:
+            attr = member.get_column(str(col))
+            out[str(col)] = {
+                'label': attr.label if attr is not None else '',
+                'unit': attr.unit if attr is not None else '',
+            }
+        return out
+
+    def remove_dataframe(self, key: str) -> None:
+        """Remove a member by key.
+
+        :raises KeyError: if the key does not exist.
+        """
+        if key not in self.data['dataframes']:
+            raise KeyError(f"DataFrame with key '{key}' not found.")
+        del self.data['dataframes'][key]
+        logger.debug("Removed DataFrame '%s' from %s", key, self.sname)
+
+    def list_dataframes(self) -> List[str]:
+        """List all member keys."""
+        return list(self.data['dataframes'].keys())
+
+    def items(self):
+        """Iterate ``(key, DataFrame)`` over the members (order preserved)."""
+        return self.data['dataframes'].items()
+
+    # ------------------------------------------------------------ serialization
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize each member via its own lossless :meth:`DataFrame.to_dict`.
+
+        Layout: ``data.dataframes[key] = {'sdata': <DataFrame.to_dict()>}`` — the
+        member keeps its full metadata/column_metadata (RFC 0011, no lossy
+        ``{label, unit}`` reduction).
+        """
+        data_copy = dict(self.data)
+        data_copy['dataframes'] = {
+            key: {'sdata': member.to_dict()}
+            for key, member in self.data['dataframes'].items()
+        }
+        result = super().to_dict()
+        result['data'] = data_copy
+        return result
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> 'DataFrameGroup':
+        """Reconstruct a group, reading **both** the new and the legacy layout.
+
+        * new: ``{'sdata': <DataFrame.to_dict>}`` → :meth:`DataFrame.from_dict`;
+        * legacy: ``{'parquet': <b64>, 'column_metadata': {col: {label, unit}}}``
+          → decode the Parquet payload and lift the flat ``{label, unit}`` dict onto
+          the member's per-column metadata.
+        """
+        from sdata.sclass.dataframe import DataFrame
+        from sdata.format import ensure_compatible
+        from sdata.metadata import Metadata
+        # cls() statt super().from_dict: Base.from_dict baut über sdata_factory eine
+        # dynamische Klasse ohne die Group-Methoden (wie DataFrame.from_dict).
+        d = ensure_compatible(d)                                   # RFC 0010: Version prüfen
+        instance = cls()
+        instance.metadata = Metadata.from_dict(d.get("metadata", {}))
+        instance.description = d.get("description", "")
+        raw = dict(d.get("data", {}))
+        members: Dict[str, Any] = {}
+        for key, entry in raw.get('dataframes', {}).items():
+            if isinstance(entry, dict) and 'sdata' in entry:
+                members[key] = DataFrame.from_dict(entry['sdata'])
+            elif isinstance(entry, dict) and 'parquet' in entry:   # Legacy-Layout
+                df = pd.read_parquet(io.BytesIO(base64.b64decode(entry['parquet'])),
+                                     engine='pyarrow')
+                members[key] = cls._as_dataframe(
+                    df, key=key, column_metadata=entry.get('column_metadata'))
+            else:                                                   # bereits DataFrame
+                members[key] = entry
+        raw['dataframes'] = members
+        instance.data = raw
+        return instance

sdata/sclass/dependency_graph.py

@@ -0,0 +1,85 @@
+from typing import Dict, Set, List, Iterable, TypeVar, Hashable
+
+T = TypeVar('T', bound=Hashable)
+
+
+class CircularDependencyError(ValueError):
+    """Exception raised when circular dependencies are detected during topological sort."""
+
+    def __init__(self, remaining_graph: Dict[T, Set[T]]):
+        message = (
+            "Circular dependencies exist among these items: "
+            f"{{{', '.join(f'{key}: {sorted(value)}' for key, value in sorted(remaining_graph.items()))}}}"
+        )
+        super().__init__(message)
+        self.remaining_graph = remaining_graph
+
+
+def toposort(graph: Dict[T, Iterable[T]]) -> Iterable[Set[T]]:
+    """Perform a topological sort on a directed acyclic graph (DAG).
+
+    Dependencies are expressed as a dictionary where keys are nodes and values are
+    iterables of dependent nodes (nodes that the key depends on). The output is a
+    generator yielding sets of nodes in topological order. The first set contains
+    nodes with no dependencies, and each subsequent set contains nodes that depend
+    only on nodes in preceding sets.
+
+    If the graph contains cycles, a CircularDependencyError is raised.
+
+    Args:
+        graph: A dictionary representing the dependency graph.
+
+    Yields:
+        Sets of nodes in topological order.
+
+    Raises:
+        CircularDependencyError: If a cycle is detected in the graph.
+    """
+    if not graph:
+        return
+
+    # Create a copy of the graph, converting dependencies to sets and removing self-dependencies.
+    graph = {node: set(dep for dep in deps if dep != node) for node, deps in graph.items()}
+
+    # Identify nodes that appear only as dependencies (no outgoing edges defined).
+    extra_nodes = {dep for deps in graph.values() for dep in deps} - set(graph)
+    graph.update({node: set() for node in extra_nodes})
+
+    while True:
+        # Find nodes with no remaining dependencies.
+        independent_nodes = {node for node, deps in graph.items() if not deps}
+        if not independent_nodes:
+            break
+        yield independent_nodes
+        # Remove processed nodes from the graph.
+        graph = {
+            node: (deps - independent_nodes)
+            for node, deps in graph.items()
+            if node not in independent_nodes
+        }
+
+    if graph:
+        raise CircularDependencyError(graph)
+
+
+def toposort_flatten(graph: Dict[T, Iterable[T]], sort: bool = True) -> List[T]:
+    """Flatten the topological sort into a single list.
+
+    This function consumes the generator from toposort() and appends the nodes
+    from each level to a list. If sort is True, nodes within each level are sorted
+    for deterministic order.
+
+    Args:
+        graph: A dictionary representing the dependency graph.
+        sort: Whether to sort nodes within each topological level (default: True).
+
+    Returns:
+        A list of nodes in topological order.
+
+    Raises:
+        CircularDependencyError: If a cycle is detected in the graph.
+    """
+    result: List[T] = []
+    for level in toposort(graph):
+        result.extend(sorted(level) if sort else list(level))
+    return result

sdata/sclass/filereference.py

@@ -0,0 +1,124 @@
+import pandas as pd
+import io
+import os
+import base64
+from typing import Any, Dict, Optional, Union, Iterable
+import logging
+from pathlib import Path
+from sdata import SUUID
+from sdata.metadata import Metadata, Attribute
+from sdata.sclass.blob import Blob
+from sdata.base import Base
+import hashlib
+import datetime
+from sdata.timestamp import get_utc_timestamp
+
+logger = logging.getLogger(__name__)
+
+
+class FileReference(Blob):
+    SDATA_CLS = "sdata.sclass.filereference.FileReference"
+
+    def __init__(
+            self,
+            filetype: Optional[str] = '',  # Default to generic binary, e.g., '.pdf', '.png', '.jpg'
+            **kwargs: Any
+    ) -> None:
+        """
+        Initialize FileReference as a :class:`~sdata.sclass.blob.Blob` over a file URI.
+
+        The file path is kept as the Blob ``uri`` content, so the reference also
+        provides ``content_bytes``/``open``/``exists``/``verify``/``size`` from Blob.
+
+        :param filetype: vestigial; the file suffix is derived from ``name``.
+        :param kwargs: Keyword arguments passed to Base (e.g. ``name`` = file path).
+        """
+        filepath = kwargs.get("name", "noname")
+        basename = os.path.basename(filepath)
+        kwargs["name"] = basename
+        path = Path(filepath)
+        # Blob-Grundlage: die Datei als uri-Content -> behält den Pfad (zuvor verloren)
+        super().__init__(content_type="uri", value=filepath,
+                         filetype=path.suffix.lstrip(".").lower() or "binary", **kwargs)
+
+        self.metadata.add("_sdata_name", basename, description="base name of the file without folder")
+        self.metadata.add("_sdata_stem", path.stem, description="file name without suffix")
+        self.metadata.add("_sdata_filetype", path.suffix.lower(), description="file suffix")
+        self.metadata.add("_sdata_filesize", None, dtype="int", description="file size in bytes")
+        self.metadata.add("_sdata_filectime", None, description="UTC file creation date")
+        self.metadata.add("_sdata_sha3_256", None, description="SHA-3-256")
+
+    @staticmethod
+    def get_hash(filepath):
+        sh = hashlib.sha3_256()
+        with open(filepath, "rb") as fh:
+            sh.update(fh.read())
+        content_hash = sh.hexdigest()
+        return content_hash
+
+    @classmethod
+    def from_file(cls, filepath: str):
+        suuid = SUUID.from_file(class_name="FileReference", filepath=filepath)
+        fr = cls(name=filepath, suuid=suuid)
+
+        fr.metadata.add("_sdata_sha3_256", cls.get_hash(filepath))
+
+        p = Path(filepath)
+        ctime = p.stat().st_ctime
+        fr.metadata.add("_sdata_filectime", get_utc_timestamp(datetime.datetime.fromtimestamp(ctime)))
+
+        fr.metadata.add("_sdata_filesize", p.stat().st_size)
+
+        return fr
+
+    @property
+    def filetype(self) -> str:
+        # robust: _sdata_filetype wird erst nach super().__init__() gesetzt, Blobs
+        # _autofill_metadata fragt filetype aber bereits währenddessen ab.
+        attr = self.metadata.get("_sdata_filetype")
+        return attr.value if attr is not None else ""
+
+    @property
+    def stem(self) -> str:
+        return self.metadata.get("_sdata_stem").value
+
+    @property
+    def ctime(self) -> str:
+        return self.metadata.get("_sdata_filectime").value
+
+    def to_dataframe(self):
+        df =  self.metadata.to_dataframe()[["value"]].T
+        df.index = [self.sname]
+        return df
+
+class FileReferences(Base):
+    SDATA_CLS = "sdata.sclass.filereference.FileReferences"
+
+    def __init__(
+            self,
+            **kwargs: Any
+    ) -> None:
+        """
+        Initialize FileReferences with content type, value, and filetype.
+        :param kwargs: Keyword arguments passed to Base.__init__ (e.g., name, description).
+        :raises ValueError: If invalid content_type or mismatched value type.
+        """
+        super().__init__(**kwargs)
+        self.filereferences = {}
+
+    def add(self, filereference: FileReference) -> None:
+        self.filereferences[filereference.sname] = filereference
+
+    def get_filereferences(self) -> Iterable[FileReference]:
+        return self.filereferences.values()
+
+    def get_filereferences_df(self) -> pd.DataFrame:
+        filereferences = []
+        for sname, filereference in self.filereferences.items():
+            filereferences.append(filereference.to_dataframe())
+        return pd.concat(filereferences)
+
+if __name__ == '__main__':
+    fr = FileReference("/tmp/test.xlsx")
+
+    print(fr)

sdata/sclass/image.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""Image — ein :class:`~sdata.sclass.blob.Blob` über Bild-Inhalt.
+
+Der Bild-Inhalt liegt als Blob-Content (``uri`` für Dateien, ``bytes`` für
+In-Memory-Daten). sdata-Metadaten werden **format-übergreifend nativ** in die
+Bilddatei eingebettet (PNG/JPEG/JP2/GIF/WebP/TIFF) — über :mod:`sdata.imagemeta`,
+das ohne Pillow auskommt. Formate **ohne** nativen Metadaten-Träger (z. B. BMP)
+erhalten einen verlustfreien ``<filepath>.meta.json``-**Sidecar**; die ``save``/
+``from_file``-API ist für alle Formate identisch. Pillow wird nur lazy zum
+**Dekodieren/Transkodieren** der Pixel genutzt (:attr:`Image.pil`/
+:meth:`Image.to_numpy`/:meth:`Image.save` bei Formatwechsel) und ist optional
+(``pip install pillow``).
+"""
+import io
+import os
+import logging
+from pathlib import Path
+
+import numpy as np
+
+from sdata import imagemeta
+from sdata.suuid import SUUID
+from sdata.metadata import Metadata
+from sdata.sclass.blob import Blob
+
+try:
+    import PIL.Image
+except ImportError:  # pragma: no cover - optionale Abhängigkeit (Pillow)
+    PIL = None
+
+logger = logging.getLogger(__name__)
+
+
+class Image(Blob):
+    """Image object based on :class:`~sdata.sclass.blob.Blob`."""
+
+    SDATA_CLS = "sdata.sclass.image.Image"
+
+    #: Datei-Endung → (Pillow-Format, :mod:`sdata.imagemeta`-Format) für :meth:`save`.
+    _SUFFIX_FORMATS = {
+        "png": ("PNG", "png"),
+        "jpg": ("JPEG", "jpeg"), "jpeg": ("JPEG", "jpeg"), "jpe": ("JPEG", "jpeg"),
+        "jp2": ("JPEG2000", "jp2"), "j2k": ("JPEG2000", "jp2"),
+        "jpf": ("JPEG2000", "jp2"), "jpx": ("JPEG2000", "jp2"),
+        "gif": ("GIF", "gif"),
+        "webp": ("WEBP", "webp"),
+        "tif": ("TIFF", "tiff"), "tiff": ("TIFF", "tiff"),
+    }
+
+    @classmethod
+    def from_file(cls, filepath, project=None, ns_name=None, **kwargs):
+        """Create an Image referencing an image file (kept as ``uri`` content).
+
+        Any sdata metadata is read back and merged: natively embedded
+        (PNG/JPEG/JP2/GIF/WebP/TIFF, Pillow-free) and/or from an adjacent
+        ``<filepath>.meta.json`` sidecar (for formats without a native container).
+
+        :param filepath: path to the image file.
+        :param project: namespace for the deterministic SUUID (alias of ``ns_name``).
+        :param ns_name: namespace for the deterministic SUUID.
+        :param kwargs: forwarded to :class:`Blob`/:class:`~sdata.base.Base`.
+        :return: an :class:`Image` instance.
+        """
+        suuid = SUUID.from_file("Image", filepath, ns_name=ns_name or project)
+        suffix = Path(filepath).suffix.lstrip(".").lower() or "binary"
+        img = cls(content_type="uri", value=filepath, filetype=suffix,
+                  name=os.path.basename(filepath), suuid=suuid, **kwargs)
+        img._load_embedded_metadata()
+        img._load_sidecar_metadata(filepath)
+        return img
+
+    @classmethod
+    def from_bytes(cls, name, image_data, project=None, **kwargs):
+        """Create an Image from in-memory image bytes.
+
+        Any embedded sdata metadata is read back and merged (Pillow-free).
+
+        :param name: a name for the image (its suffix sets the filetype).
+        :param image_data: the raw image bytes.
+        :param project: namespace for the deterministic SUUID.
+        :return: an :class:`Image` instance.
+        """
+        suuid = SUUID.from_str("Image", name, ns_name=project)
+        suffix = Path(name).suffix.lstrip(".").lower() or "binary"
+        img = cls(content_type="bytes", value=image_data, filetype=suffix,
+                  name=name, suuid=suuid, **kwargs)
+        img._load_embedded_metadata()
+        return img
+
+    @property
+    def pil(self):
+        """The image decoded lazily with Pillow (:class:`PIL.Image.Image`)."""
+        if PIL is None:
+            raise ImportError("Pillow is required for Image decoding (pip install pillow).")
+        return PIL.Image.open(io.BytesIO(self.content_bytes))
+
+    def to_numpy(self) -> np.ndarray:
+        """The image as a NumPy array (colour channels)."""
+        return np.array(self.pil)
+
+    @property
+    def basename(self) -> str:
+        """The image file base name (== ``name``)."""
+        return self.name
+
+    def embedded_metadata(self):
+        """Return the sdata metadata embedded in the image bytes, or ``None``.
+
+        Reads the native sdata payload (PNG ``iTXt`` / JPEG ``APP1`` / JP2 ``uuid``
+        box / GIF comment / WebP ``sdAT`` chunk) without Pillow.
+
+        :return: a :class:`~sdata.metadata.Metadata`, or ``None`` if absent/invalid.
+        """
+        raw = imagemeta.extract(self.content_bytes)
+        if not raw:
+            return None
+        try:
+            return Metadata.from_json(raw)
+        except Exception as exp:
+            logger.debug(f"embedded sdata metadata not parseable: {exp}")
+            return None
+
+    def _load_embedded_metadata(self) -> None:
+        """Merge sdata metadata embedded in the image bytes (any supported format)."""
+        try:
+            embedded = self.embedded_metadata()
+        except Exception as exp:  # e.g. unreadable uri content
+            logger.debug(f"no embedded sdata metadata: {exp}")
+            return
+        if embedded is not None:
+            self.metadata.update_from_usermetadata(embedded)
+
+    @staticmethod
+    def sidecar_path(filepath) -> str:
+        """Path of the metadata sidecar for ``filepath`` (``<filepath>.meta.json``)."""
+        return str(filepath) + ".meta.json"
+
+    def write_sidecar(self, filepath) -> str:
+        """Write the sdata metadata next to ``filepath`` as a lossless JSON sidecar.
+
+        The sidecar carries the **same** payload as the embedded form
+        (``metadata.to_json()``), so a round-trip is lossless regardless of whether
+        the format has a native metadata container.
+
+        :param filepath: the image path the sidecar belongs to.
+        :return: the sidecar path (``<filepath>.meta.json``).
+        """
+        sidecar = self.sidecar_path(filepath)
+        with open(sidecar, "w", encoding="utf-8") as fh:
+            fh.write(self.metadata.to_json())
+        logger.info(f"Image metadata sidecar written to {sidecar}")
+        return sidecar
+
+    def _load_sidecar_metadata(self, filepath) -> None:
+        """Merge metadata from an adjacent ``<filepath>.meta.json`` sidecar, if present."""
+        sidecar = self.sidecar_path(filepath)
+        if not os.path.exists(sidecar):
+            return
+        try:
+            with open(sidecar, "r", encoding="utf-8") as fh:
+                md = Metadata.from_json(fh.read())
+            self.metadata.update_from_usermetadata(md)
+            logger.debug(f"merged sidecar metadata from {sidecar}")
+        except Exception as exp:
+            logger.debug(f"sidecar metadata not loadable: {exp}")
+
+    def save(self, filepath, sidecar=None, **kwargs):
+        """Save the image to ``filepath`` with sdata metadata — one API for all formats.
+
+        The container is chosen from the file suffix. For a format with a native
+        metadata container (PNG/JPEG/JP2/GIF/WebP/TIFF) the metadata is **embedded**:
+        without re-encoding if the stored bytes already use that container (lossless,
+        Pillow-free), otherwise Pillow transcodes first. For **any other** format
+        (e.g. BMP) the image is written via Pillow and the metadata travels in a
+        lossless ``<filepath>.meta.json`` **sidecar** — so metadata is never lost.
+
+        :param filepath: destination path (its suffix selects the format).
+        :param sidecar: sidecar policy — ``None`` (default) writes a sidecar only when
+          the format has no native container; ``True`` always writes one (in addition
+          to embedding); ``False`` never writes one.
+        :param kwargs: forwarded to ``PIL.Image.save`` when transcoding.
+        :raises ImportError: if Pillow is required (transcode / non-native format) but
+          not installed.
+        :return: the destination ``filepath``.
+        """
+        suffix = Path(filepath).suffix.lstrip(".").lower()
+        target = self._SUFFIX_FORMATS.get(suffix)
+
+        if target is None:
+            # Kein nativer Metadaten-Träger → Pillow schreiben + verlustfreier Sidecar.
+            if PIL is None:
+                raise ImportError("Pillow is required for Image.save (pip install pillow).")
+            self.pil.save(filepath, **kwargs)
+            if sidecar is not False:
+                self.write_sidecar(filepath)
+                logger.info("Image.save: '%s' has no native metadata container; "
+                            "metadata written to a sidecar", filepath)
+            return filepath
+
+        pil_format, meta_fmt = target
+        src = self.content_bytes
+        if imagemeta.detect_format(src) == meta_fmt:
+            img_bytes = src                      # passender Container → kein Transkodieren
+        else:
+            if PIL is None:
+                raise ImportError("Pillow is required to transcode images "
+                                  "(pip install pillow).")
+            buffer = io.BytesIO()
+            self.pil.save(buffer, pil_format, **kwargs)
+            img_bytes = buffer.getvalue()
+
+        img_bytes = imagemeta.embed(img_bytes, self.metadata.to_json(), meta_fmt)
+        with open(filepath, "wb") as fh:
+            fh.write(img_bytes)
+        if sidecar is True:
+            self.write_sidecar(filepath)
+        logger.info(f"Image saved to {filepath}")
+        return filepath