shepherd-core 2025.10.1__py3-none-any.whl → 2026.2.1__py3-none-any.whl

shepherd_core/config.py

@@ -27,7 +27,7 @@ class ConfigDefault(BaseModel):
     UID_SIZE: int = 2
     """Variable size in Byte"""
 
-    TESTBED_SERVER: HttpUrl = "https://shepherd.cfaed.tu-dresden.de:8000/"
+    TESTBED_SERVER: HttpUrl = HttpUrl("https://shepherd.cfaed.tu-dresden.de:8000/")
     """Server that holds up to date testbed fixtures"""
 
 

shepherd_core/data_models/__init__.py

@@ -18,10 +18,11 @@ from .base.calibration import CapeData
 from .base.content import ContentModel
 from .base.shepherd import ShpModel
 from .base.wrapper import Wrapper
-from .content.energy_environment import EnergyDType
 from .content.energy_environment import EnergyEnvironment
+from .content.energy_environment import EnergyProfile
+from .content.enum_datatypes import EnergyDType
+from .content.enum_datatypes import FirmwareDType
 from .content.firmware import Firmware
-from .content.firmware import FirmwareDType
 from .content.virtual_harvester_config import VirtualHarvesterConfig
 from .content.virtual_source_config import VirtualSourceConfig
 from .content.virtual_storage_config import VirtualStorageConfig
@@ -45,6 +46,7 @@ __all__ = [
     "ContentModel",
     "EnergyDType",
     "EnergyEnvironment",
+    "EnergyProfile",
     "Experiment",
     "Firmware",
     "FirmwareDType",

shepherd_core/data_models/base/cal_measurement.py

@@ -1,6 +1,7 @@
 """Models for the process of calibration a device by measurements."""
 
 from typing import Annotated
+from typing import final
 
 import numpy as np
 from pydantic import Field
@@ -15,6 +16,7 @@ from .calibration import CapeData
 from .shepherd import ShpModel
 
 
+@final
 class CalMeasurementPair(ShpModel):
     """Value-container for a calibration-measurement."""
 
@@ -39,8 +41,8 @@ def meas_to_cal(data: CalMeasPairs, component: str) -> CalibrationPair:
     gain: float = float(model[0])
 
     # r-squared, Pearson correlation coefficient
-    _p = np.poly1d(model)
-    yhat = _p(x)
+    pcoef = np.poly1d(model)
+    yhat = pcoef(x)
     ybar: float = np.sum(y) / len(y)
     ssreg: float = np.sum((yhat - ybar) ** 2)
     sstot: float = np.sum((y - ybar) ** 2)
@@ -55,6 +57,7 @@ def meas_to_cal(data: CalMeasPairs, component: str) -> CalibrationPair:
     return CalibrationPair(offset=offset, gain=gain)
 
 
+@final
 class CalMeasurementHarvester(ShpModel):
     """Container for the values of the calibration-measurement."""
 
@@ -71,6 +74,7 @@ class CalMeasurementHarvester(ShpModel):
         return CalibrationHarvester(**dcal)
 
 
+@final
 class CalMeasurementEmulator(ShpModel):
     """Container for the values of the calibration-measurement."""
 
@@ -87,6 +91,7 @@ class CalMeasurementEmulator(ShpModel):
         return CalibrationEmulator(**dcal)
 
 
+@final
 class CalMeasurementCape(ShpModel):
     """Container for the values of the calibration-measurement."""
 

shepherd_core/data_models/base/calibration.py

@@ -5,14 +5,16 @@ from collections.abc import Callable
 from collections.abc import Generator
 from collections.abc import Mapping
 from collections.abc import Sequence
+from typing import Annotated
 from typing import TypeVar
+from typing import final
 
 import numpy as np
 from numpy.typing import NDArray
 from pydantic import Field
 from pydantic import PositiveFloat
+from pydantic import StringConstraints
 from pydantic import conbytes
-from pydantic import constr
 from pydantic import validate_call
 from typing_extensions import Self
 
@@ -47,6 +49,7 @@ def dict_generator(
         yield [*pre, in_dict]
 
 
+@final
 class CalibrationPair(ShpModel):
     """SI-value [SI-Unit] = raw-value * gain + offset."""
 
@@ -56,11 +59,11 @@ class CalibrationPair(ShpModel):
 
     def raw_to_si(self, values_raw: Calc_t, *, allow_negative: bool = True) -> Calc_t:
         """Convert between physical units and raw unsigned integers."""
-        values_si = values_raw * self.gain + self.offset
+        values_si = self.gain * values_raw + self.offset
         if not allow_negative:
             if isinstance(values_si, np.ndarray):
                 values_si[values_si < 0.0] = 0.0
-                # if pyright still complains, cast with .astype(float)
+                # if type-checker still complains, cast with .astype(float)
             else:
                 values_si = float(max(values_si, 0.0))
         elif not isinstance(values_si, np.ndarray):
@@ -99,6 +102,7 @@ cal_pair_adc_V = CalibrationPair.from_fn(adc_voltage_to_raw, unit="V")
 cal_pair_adc_C = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
 
 
+@final
 class CalibrationHarvester(ShpModel):
     """Container for all calibration-pairs for that device."""
 
@@ -140,6 +144,7 @@ cal_emu_legacy = {  # legacy translator
 }
 
 
+@final
 class CalibrationEmulator(ShpModel):
     """Container for all calibration-pairs for that device.
 
@@ -177,6 +182,7 @@ class CalibrationEmulator(ShpModel):
         return cal_set
 
 
+@final
 class CapeData(ShpModel):
     """Representation of Beaglebone Cape information.
 
@@ -190,15 +196,17 @@ class CapeData(ShpModel):
     """
 
     header: conbytes(max_length=4) = b"\xaa\x55\x33\xee"
-    eeprom_revision: constr(max_length=2) = "A2"
-    board_name: constr(max_length=32) = "BeagleBone SHEPHERD2 Cape"
-    version: constr(max_length=4) = "24B0"
-    manufacturer: constr(max_length=16) = "NES TU DRESDEN"
-    part_number: constr(max_length=16) = "BB-SHPRD"
+    eeprom_revision: Annotated[str, StringConstraints(max_length=2)] = "A2"
+    board_name: Annotated[str, StringConstraints(max_length=32)] = "BeagleBone SHEPHERD2 Cape"
+    version: Annotated[str, StringConstraints(max_length=4)] = "24B0"
+    manufacturer: Annotated[str, StringConstraints(max_length=16)] = "NES TU DRESDEN"
+    part_number: Annotated[str, StringConstraints(max_length=16)] = "BB-SHPRD"
 
-    serial_number: constr(max_length=12)
+    serial_number: Annotated[str, StringConstraints(max_length=12)]
 
-    cal_date: constr(max_length=12) = Field(default_factory=local_iso_date)
+    cal_date: Annotated[str, StringConstraints(max_length=12)] = Field(
+        default_factory=local_iso_date
+    )
     # ⤷ produces something like '2023-01-01'
 
     def __repr__(self) -> str:  # TODO: override useful?
@@ -206,6 +214,7 @@ class CapeData(ShpModel):
         return str(self.model_dump())
 
 
+@final
 class CalibrationCape(ShpModel):
     """Represents calibration data of shepherd cape.
 
@@ -231,6 +240,7 @@ class CalibrationCape(ShpModel):
         ----
             data: Byte string containing calibration data.
             cape: data can be supplied
+
         Returns:
             CalibrationCape object with extracted calibration data.
 
@@ -240,9 +250,9 @@ class CalibrationCape(ShpModel):
         lw2 = [elem for elem in lw1 if isinstance(elem[-1], float)]
         values = struct.unpack(">" + len(lw2) * "d", data)
         # ⤷ X => double float, big endian
-        for _i, walk in enumerate(lw2):
+        for i_, walk in enumerate(lw2):
             # hardcoded fixed depth ... bad but easy
-            dv[walk[0]][walk[1]][walk[2]] = float(values[_i])
+            dv[walk[0]][walk[1]][walk[2]] = float(values[i_])
         dv["cape"] = cape
         return cls(**dv)
 
@@ -260,6 +270,7 @@ class CalibrationCape(ShpModel):
         return struct.pack(">" + len(values) * "d", *values)
 
 
+@final
 class CalibrationSeries(ShpModel):
     """Cal-Data for a typical recording of a testbed experiment."""
 

shepherd_core/data_models/base/content.py

@@ -9,12 +9,15 @@ from pydantic import StringConstraints
 from pydantic import model_validator
 from typing_extensions import Self
 
+from shepherd_core.logger import log
+from shepherd_core.version import version as core_ver
+
 from .shepherd import ShpModel
 
 # constr -> to_lower=True, max_length=16, regex=r"^[\w]+$"
 # ⤷ Regex = AlphaNum
 IdInt = Annotated[int, Field(ge=0, lt=2**128)]
-NameStr = Annotated[str, StringConstraints(max_length=32, pattern=r"^[^<>:;,?\"\*|\/\\]+$")]
+NameStr = Annotated[str, StringConstraints(max_length=50, pattern=r"^[^<>:;,?\"\*|\/\\]+$")]
 # ⤷ Regex = FileSystem-Compatible ASCII
 SafeStr = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 # ⤷ Regex = All Printable ASCII-Characters with Space
@@ -41,6 +44,8 @@ class ContentModel(ShpModel):
     comment: SafeStr | None = None
     created: datetime = Field(default_factory=datetime.now)
     updated_last: datetime = Field(default_factory=datetime.now)
+    deprecated: str | None = None
+    """ ⤷ deprecation-comments provoke a warning during validation of model."""
     # TODO: add dedicated 'inherit_from' field?
 
     # Ownership & Access
@@ -50,7 +55,8 @@ class ContentModel(ShpModel):
     visible2group: bool = False
     visible2all: bool = False
 
-    # TODO: we probably need to remember the lib-version for content &| experiment
+    sw_ver: Annotated[str, Field(default=core_ver)]
+    """ ⤷ store core-version with content for compatibility management."""
 
     def __str__(self) -> str:
         return self.name
@@ -62,4 +68,6 @@ class ContentModel(ShpModel):
             raise ValueError(
                 "Public instances require a description (check visible2*- and description-field)"
             )
+        if isinstance(self.deprecated, str) and len(self.deprecated) > 0:
+            log.warning(f"Content {self.name} is deprecated: {self.deprecated}")
         return self

shepherd_core/data_models/base/shepherd.py

@@ -8,6 +8,7 @@ from datetime import timedelta
 from ipaddress import IPv4Address
 from pathlib import Path
 from typing import Any
+from typing import final
 from uuid import UUID
 
 import yaml
@@ -38,6 +39,7 @@ def generic2str(dumper: SafeDumper, data: Any) -> Node:
     return dumper.represent_scalar("tag:yaml.org,2002:str", str(data))
 
 
+# TODO: put in helper-file (similar to models/task/helper_paths.py) and make it callable
 yaml.add_representer(pathlib.PosixPath, path2str, SafeDumper)
 yaml.add_representer(pathlib.WindowsPath, path2str, SafeDumper)
 yaml.add_representer(pathlib.Path, path2str, SafeDumper)
@@ -108,12 +110,15 @@ class ShpModel(BaseModel):
         )
         return str(content)
 
-    def __getitem__(self, key: str) -> Any:
+    def __getitem__(self, key: Any) -> Any:
         """Allow dict access like model["key"].
 
         in addition to model.key.
         """
-        return self.__getattribute__(key)
+        if isinstance(key, str):
+            return self.__getattribute__(key)
+        msg = f"Unknown key '{key}' used when selecting from Model."
+        raise IndexError(msg)
 
     def __contains__(self, item: str) -> bool:
         """Allow checks like 'x in YClass'."""
@@ -127,8 +132,9 @@ class ShpModel(BaseModel):
     def items(self) -> Generator[tuple, None, None]:
         """Fn of dict."""
         for key in self.keys():
-            yield key, self[key]
+            yield key, self.__getattribute__(key)
 
+    @final
     @classmethod
     def schema_to_file(cls, path: str | Path) -> None:
         """Store schema to yaml (for frontend-generators)."""
@@ -137,6 +143,7 @@ class ShpModel(BaseModel):
         with Path(path).resolve().with_suffix(".yaml").open("w") as f:
             f.write(model_yaml)
 
+    @final
     def to_file(
         self,
         path: str | Path,
@@ -178,6 +185,7 @@ class ShpModel(BaseModel):
             f.write(model_serial)
         return model_path
 
+    @final
     @classmethod
     def from_file(cls, path: str | Path) -> Self:
         """Load from YAML or pickle file."""
@@ -188,12 +196,13 @@ class ShpModel(BaseModel):
             with Path(path).open("rb") as shp_file:
                 shp_dict = pickle.load(shp_file)  # noqa: S301
         else:
-            with Path(path).open() as shp_file:
+            with Path(path).open(encoding="utf-8-sig") as shp_file:
                 shp_dict = yaml.safe_load(shp_file)
         shp_wrap = Wrapper(**shp_dict)
         if shp_wrap.datatype != cls.__name__:
             raise ValueError("Model in file does not match the actual Class")
         return cls(**shp_wrap.parameters)
 
+    @final
     def get_hash(self) -> str:
         return hashlib.sha3_224(str(self.model_dump()).encode("utf-8")).hexdigest()

shepherd_core/data_models/base/wrapper.py

@@ -2,6 +2,7 @@
 
 from datetime import datetime
 from typing import Annotated
+from typing import final
 
 from pydantic import BaseModel
 from pydantic import StringConstraints
@@ -12,6 +13,7 @@ SafeStrClone = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 # ⤷ copy avoids circular import
 
 
+@final
 class Wrapper(BaseModel):
     """Generalized web- & file-interface for all models with dynamic typecasting."""
 

shepherd_core/data_models/content/__init__.py

@@ -3,10 +3,11 @@
 These models import externally from: /base, /testbed.
 """
 
-from .energy_environment import EnergyDType
 from .energy_environment import EnergyEnvironment
+from .energy_environment import EnergyProfile
+from .enum_datatypes import EnergyDType
+from .enum_datatypes import FirmwareDType
 from .firmware import Firmware
-from .firmware_datatype import FirmwareDType
 from .virtual_harvester_config import VirtualHarvesterConfig
 from .virtual_source_config import VirtualSourceConfig
 from .virtual_storage_config import VirtualStorageConfig
@@ -14,6 +15,7 @@ from .virtual_storage_config import VirtualStorageConfig
 __all__ = [
     "EnergyDType",
     "EnergyEnvironment",
+    "EnergyProfile",
     "Firmware",
     "FirmwareDType",
     "VirtualHarvesterConfig",